Skip to content

Commit 523c835

Browse files
CameronBadmanCameronBadman
committed
added Terraform collab guide and link to it in the project assessment
1 parent 5eaf811 commit 523c835

5 files changed

Lines changed: 257 additions & 1 deletion

File tree

‎assessment/project/guides/terraform-collaboration/latexmkrc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
ensure_path( 'TEXINPUTS', '../../../../tex//' );
2+
ensure_path( 'BIBINPUTS', '../../../../references//', '../../../../../references//' );
3+
4+
@default_files = ('main.tex');
5+
6+
$pre_tex_code = '\\\\AtBeginDocument{\\\\teachermodetrue}\\\\input{main.tex}';
7+
8+
$pdflatex = 'pdflatex -interaction=nonstopmode -shell-escape';
9+
$out_dir = 'out';
10+
11+
$pdf_mode = 1;

‎assessment/project/guides/terraform-collaboration/main.tex‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
\documentclass{csse4400}
2+
3+
% \teachermodetrue
4+
5+
\usepackage{float}
6+
\usepackage{languages}
7+
8+
\title{Terraform Collaboration Guide}
9+
\author{CSSE6400 Teaching Team}
10+
\date{Assignment Guide}
11+
12+
\begin{document}
13+
14+
\maketitle
15+
16+
\aside{
17+
Use this guide when setting up Terraform for your team assignment.
18+
Each team should use one shared Terraform state file stored in S3.
19+
}
20+
21+
\section{Overview}
22+
23+
Terraform records the resources it manages in a state file.
24+
When working alone, this is usually a local file named \texttt{terraform.tfstate}.
25+
When working in a team, local state causes problems because each person may have a different view of the infrastructure.
26+
27+
For the assignment, your team should store Terraform state in a shared S3 bucket.
28+
This lets every team member run \texttt{terraform plan} against the same state.
29+
It also allows Terraform to lock the state while someone is applying changes.
30+
31+
\warning{
32+
Never commit \texttt{terraform.tfstate}, \texttt{terraform.tfstate.backup},
33+
\texttt{.terraform/}, AWS credentials, or Learner Lab tokens.
34+
}
35+
36+
\section{Choose a Region and Bucket Name}
37+
38+
Your team needs one S3 bucket for Terraform state.
39+
Choose one AWS region and one bucket name before configuring Terraform.
40+
Every team member must use the same region, bucket, and state file path.
41+
42+
\begin{code}[numbers=none]{}
43+
AWS region: us-east-1
44+
S3 state bucket: csse6400-team-00-tfstate-a1b2
45+
State file path: taskoverflow/terraform.tfstate
46+
\end{code}
47+
48+
\noindent
49+
Replace \texttt{us-east-1} with the AWS region your team is using.
50+
Replace \texttt{csse6400-team-00-tfstate-a1b2} with your team's actual bucket name.
51+
52+
\info{
53+
S3 bucket names are globally unique.
54+
Include your course, team number, and a short unique suffix in the name.
55+
}
56+
57+
\section{Step 1: Create the Bucket}
58+
59+
One team member should create the bucket.
60+
Do this before running \texttt{terraform init} with the S3 backend.
61+
First set your chosen values in the terminal.
62+
63+
\begin{code}[language=shell,numbers=none]{}
64+
export TF_STATE_BUCKET=csse6400-team-00-tfstate-a1b2
65+
export AWS_REGION=us-east-1
66+
\end{code}
67+
68+
\noindent
69+
For \texttt{us-east-1}, use:
70+
71+
\begin{code}[language=shell,numbers=none]{}
72+
aws s3api create-bucket \
73+
--bucket "$TF_STATE_BUCKET" \
74+
--region "$AWS_REGION"
75+
76+
aws s3api put-bucket-versioning \
77+
--bucket "$TF_STATE_BUCKET" \
78+
--versioning-configuration Status=Enabled
79+
\end{code}
80+
81+
\noindent
82+
For other regions, change \texttt{AWS\_REGION} and include a location constraint:
83+
84+
\begin{code}[language=shell,numbers=none]{}
85+
export AWS_REGION=ap-southeast-2
86+
87+
aws s3api create-bucket \
88+
--bucket "$TF_STATE_BUCKET" \
89+
--region "$AWS_REGION" \
90+
--create-bucket-configuration LocationConstraint="$AWS_REGION"
91+
92+
aws s3api put-bucket-versioning \
93+
--bucket "$TF_STATE_BUCKET" \
94+
--versioning-configuration Status=Enabled
95+
\end{code}
96+
97+
\info{
98+
Bucket versioning is recommended so that accidental state changes are easier to recover from.
99+
}
100+
101+
\warning{
102+
The bucket that stores Terraform state should be created before the backend is configured.
103+
Do not put this same bucket in the Terraform configuration that will use it as a backend.
104+
}
105+
106+
\section{Step 2: Create Backend Files}
107+
108+
In your Terraform directory, create \texttt{backend.tf}.
109+
110+
\begin{code}[language=terraform,numbers=none]{backend.tf}
111+
terraform {
112+
backend "s3" {}
113+
}
114+
\end{code}
115+
116+
\noindent
117+
Create \texttt{backend.hcl}.
118+
This file tells Terraform which S3 bucket should store the shared state.
119+
120+
\begin{code}[language=terraform,numbers=none]{backend.hcl}
121+
bucket = "csse6400-team-00-tfstate-a1b2"
122+
key = "taskoverflow/terraform.tfstate"
123+
region = "us-east-1"
124+
encrypt = true
125+
use_lockfile = true
126+
\end{code}
127+
128+
\noindent
129+
The \texttt{region} value must match the region where your team created the bucket.
130+
131+
\info{
132+
\texttt{use\_lockfile = true} enables S3 state locking.
133+
This helps stop two team members from applying changes to the same state at the same time.
134+
}
135+
136+
\warning{
137+
Backend blocks cannot use Terraform variables.
138+
Do not write \texttt{bucket = var.bucket\_name} inside a backend configuration.
139+
If Terraform rejects \texttt{use\_lockfile}, update Terraform or ask a tutor.
140+
}
141+
142+
\section{Step 3: Initialise Terraform}
143+
144+
Run Terraform initialisation from the Terraform directory.
145+
146+
\bash{
147+
terraform init -backend-config=backend.hcl
148+
}
149+
150+
\noindent
151+
If this is a fresh project, Terraform should initialise the S3 backend.
152+
If there is already local state, Terraform may ask whether to migrate that state to S3.
153+
154+
\warning{
155+
Only migrate state from the machine that has the correct current state.
156+
If multiple people have already run \texttt{terraform apply} locally,
157+
stop and ask a tutor before migrating.
158+
}
159+
160+
\newpage
161+
\section{Step 4: Ignore Local Files}
162+
163+
Make sure your repository ignores generated Terraform files and local credentials.
164+
165+
\begin{code}[numbers=none]{.gitignore}
166+
.terraform/
167+
terraform.tfstate
168+
terraform.tfstate.backup
169+
*.tfstate
170+
*.tfstate.backup
171+
credentials
172+
aws.env
173+
\end{code}
174+
175+
\noindent
176+
Commit \texttt{backend.tf}.
177+
You may commit \texttt{backend.hcl} if it only contains the team bucket name and no secrets.
178+
If each student needs different local settings,
179+
commit \texttt{backend.example.hcl} instead and keep \texttt{backend.hcl} ignored.
180+
181+
\section{Normal Team Workflow}
182+
183+
Before making changes:
184+
185+
\begin{code}[language=shell,numbers=none]{}
186+
git pull
187+
terraform init -backend-config=backend.hcl
188+
terraform validate
189+
terraform plan
190+
\end{code}
191+
192+
\noindent
193+
Before opening a pull request:
194+
195+
\begin{code}[language=shell,numbers=none]{}
196+
terraform fmt
197+
terraform validate
198+
terraform plan
199+
\end{code}
200+
201+
\noindent
202+
When applying shared infrastructure changes:
203+
204+
\begin{code}[language=shell,numbers=none]{}
205+
git pull
206+
aws sts get-caller-identity
207+
terraform init -backend-config=backend.hcl
208+
terraform plan
209+
terraform apply
210+
\end{code}
211+
212+
\warning{
213+
Only one person should run \texttt{terraform apply} at a time.
214+
Tell your team before applying.
215+
Do not use \texttt{-lock=false} during normal team work.
216+
}
217+
218+
\section{Changing the Backend}
219+
220+
If you change \texttt{backend.tf} or \texttt{backend.hcl},
221+
reinitialise Terraform.
222+
Do this carefully:
223+
a wrong bucket name or wrong region can point your team at a different state file.
224+
225+
\bash{
226+
terraform init -reconfigure -backend-config=backend.hcl
227+
}
228+
229+
\warning{
230+
If \texttt{terraform plan} wants to destroy something important,
231+
do not apply until the team understands why.
232+
Ask a tutor if unsure.
233+
}
234+
235+
\end{document}

‎assessment/project/guides/terraform-collaboration/publish‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎assessment/project/main.tex‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,9 @@ \section{Report}
185185
\section{Repository}
186186
Your team will be provisioned with a repository on GitHub.
187187
All source code, documentation and support artefacts are to be committed to the repository.
188+
If your team uses Terraform for deployment, refer to the
189+
\link{Terraform collaboration guide}{https://csse6400.uqcloud.net/assessment/project-guide-terraform-collaboration.pdf}
190+
for guidance on sharing state safely within your team.
188191

189192
\begin{itemize}[itemsep=3pt,parsep=3pt]
190193
\item Model artefacts (e.g. Structurizr DSL or PUML files) should be stored in the \textbf{\texttt{/model}} directory.
@@ -363,4 +366,4 @@ \section{Grading Criteria}
363366

364367
\input{criteria}
365368

366-
\end{document}
369+
\end{document}

‎bin/build_assessment.sh‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,9 @@ for folder in ${REPO_ROOT}/assessment/project/project-descriptions/*; do
3232
build_assignment "${folder}" "project-$(basename "${folder}")"
3333
fi
3434
done
35+
36+
for folder in ${REPO_ROOT}/assessment/project/guides/*; do
37+
if [[ -f "${folder}/latexmkrc" && -f "${folder}/main.tex" && -f "${folder}/publish" ]]; then
38+
build_assignment "${folder}" "project-guide-$(basename "${folder}")"
39+
fi
40+
done

0 commit comments

Comments
 (0)