Skip to content

Commit dc93e52

Browse files
applebyterapplebyter
authored
Merge pull request #14 from CameronBadman/tf-collab
Added Terraform collab guide and link to it in the project assessment
2 parents 5eaf811 + 0e849eb commit dc93e52

5 files changed

Lines changed: 269 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: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
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 an Account, Region, and Bucket Name}
37+
38+
Your team needs one S3 bucket for Terraform state.
39+
Choose one AWS account, one AWS region, and one bucket name before configuring Terraform.
40+
Every team member must use the same account, region, bucket, and state file path.
41+
42+
\begin{code}[numbers=none]{}
43+
AWS account ID: 123456789012
44+
AWS region: us-east-1
45+
S3 state bucket: csse6400-t00-123456789012-us-east-1-tfstate
46+
State file path: taskoverflow/terraform.tfstate
47+
\end{code}
48+
49+
\noindent
50+
Replace \texttt{123456789012} with the AWS account ID from your team's assignment Learner Lab.
51+
Replace \texttt{us-east-1} with the AWS region your team is using.
52+
Replace \texttt{t00} with your team number.
53+
54+
\info{
55+
S3 bucket names are globally unique.
56+
Including the team number, AWS account ID, and AWS region makes collisions unlikely
57+
and helps your team spot accidental account or region mismatches.
58+
}
59+
60+
\section{Step 1: Create the Bucket}
61+
62+
One team member should create the bucket.
63+
Do this before running \texttt{terraform init} with the S3 backend.
64+
First set your chosen values in the terminal.
65+
66+
\begin{code}[language=shell,numbers=none]{}
67+
export AWS_REGION=us-east-1
68+
export TEAM_NUMBER=00
69+
export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
70+
export TF_STATE_BUCKET="csse6400-t${TEAM_NUMBER}-${AWS_ACCOUNT_ID}-${AWS_REGION}-tfstate"
71+
\end{code}
72+
73+
\warning{
74+
Use the AWS account ID from the shared assignment Learner Lab account that will host the project.
75+
Do not create a separate state bucket in each team member's personal practical lab.
76+
}
77+
78+
\noindent
79+
For \texttt{us-east-1}, use:
80+
81+
\begin{code}[language=shell,numbers=none]{}
82+
aws s3api create-bucket \
83+
--bucket "$TF_STATE_BUCKET" \
84+
--region "$AWS_REGION"
85+
86+
aws s3api put-bucket-versioning \
87+
--bucket "$TF_STATE_BUCKET" \
88+
--versioning-configuration Status=Enabled
89+
\end{code}
90+
91+
\noindent
92+
For other regions, set \texttt{AWS\_REGION} before generating the bucket name,
93+
and include a location constraint:
94+
95+
\begin{code}[language=shell,numbers=none]{}
96+
export AWS_REGION=ap-southeast-2
97+
export TF_STATE_BUCKET="csse6400-t${TEAM_NUMBER}-${AWS_ACCOUNT_ID}-${AWS_REGION}-tfstate"
98+
99+
aws s3api create-bucket \
100+
--bucket "$TF_STATE_BUCKET" \
101+
--region "$AWS_REGION" \
102+
--create-bucket-configuration LocationConstraint="$AWS_REGION"
103+
104+
aws s3api put-bucket-versioning \
105+
--bucket "$TF_STATE_BUCKET" \
106+
--versioning-configuration Status=Enabled
107+
\end{code}
108+
109+
\info{
110+
Bucket versioning is recommended so that accidental state changes are easier to recover from.
111+
}
112+
113+
\warning{
114+
The bucket that stores Terraform state should be created before the backend is configured.
115+
Do not put this same bucket in the Terraform configuration that will use it as a backend.
116+
}
117+
118+
\section{Step 2: Create Backend Files}
119+
120+
In your Terraform directory, create \texttt{backend.tf}.
121+
122+
\begin{code}[language=terraform,numbers=none]{backend.tf}
123+
terraform {
124+
backend "s3" {}
125+
}
126+
\end{code}
127+
128+
\noindent
129+
Create \texttt{backend.hcl}.
130+
This file tells Terraform which S3 bucket should store the shared state.
131+
132+
\begin{code}[language=terraform,numbers=none]{backend.hcl}
133+
bucket = "csse6400-t00-123456789012-us-east-1-tfstate"
134+
key = "taskoverflow/terraform.tfstate"
135+
region = "us-east-1"
136+
encrypt = true
137+
use_lockfile = true
138+
\end{code}
139+
140+
\noindent
141+
The \texttt{region} value must match the region where your team created the bucket.
142+
143+
\info{
144+
\texttt{use\_lockfile = true} enables S3 state locking.
145+
This helps stop two team members from applying changes to the same state at the same time.
146+
}
147+
148+
\warning{
149+
Backend blocks cannot use Terraform variables.
150+
Do not write \texttt{bucket = var.bucket\_name} inside a backend configuration.
151+
If Terraform rejects \texttt{use\_lockfile}, update Terraform or ask a tutor.
152+
}
153+
154+
\section{Step 3: Initialise Terraform}
155+
156+
Run Terraform initialisation from the Terraform directory.
157+
158+
\bash{
159+
terraform init -backend-config=backend.hcl
160+
}
161+
162+
\noindent
163+
If this is a fresh project, Terraform should initialise the S3 backend.
164+
If there is already local state, Terraform may ask whether to migrate that state to S3.
165+
166+
\warning{
167+
Only migrate state from the machine that has the correct current state.
168+
If multiple people have already run \texttt{terraform apply} locally,
169+
stop and ask a tutor before migrating.
170+
}
171+
172+
\newpage
173+
\section{Step 4: Ignore Local Files}
174+
175+
Make sure your repository ignores generated Terraform files and local credentials.
176+
177+
\begin{code}[numbers=none]{.gitignore}
178+
.terraform/
179+
terraform.tfstate
180+
terraform.tfstate.backup
181+
*.tfstate
182+
*.tfstate.backup
183+
credentials
184+
aws.env
185+
\end{code}
186+
187+
\noindent
188+
Commit \texttt{backend.tf}.
189+
You may commit \texttt{backend.hcl} if it only contains the team bucket name and no secrets.
190+
If each student needs different local settings,
191+
commit \texttt{backend.example.hcl} instead and keep \texttt{backend.hcl} ignored.
192+
193+
\section{Normal Team Workflow}
194+
195+
Before making changes:
196+
197+
\begin{code}[language=shell,numbers=none]{}
198+
git pull
199+
terraform init -backend-config=backend.hcl
200+
terraform validate
201+
terraform plan
202+
\end{code}
203+
204+
\noindent
205+
Before opening a pull request:
206+
207+
\begin{code}[language=shell,numbers=none]{}
208+
terraform fmt
209+
terraform validate
210+
terraform plan
211+
\end{code}
212+
213+
\noindent
214+
When applying shared infrastructure changes:
215+
216+
\begin{code}[language=shell,numbers=none]{}
217+
git pull
218+
aws sts get-caller-identity
219+
terraform init -backend-config=backend.hcl
220+
terraform plan
221+
terraform apply
222+
\end{code}
223+
224+
\warning{
225+
Only one person should run \texttt{terraform apply} at a time.
226+
Tell your team before applying.
227+
Do not use \texttt{-lock=false} during normal team work.
228+
}
229+
230+
\section{Changing the Backend}
231+
232+
If you change \texttt{backend.tf} or \texttt{backend.hcl},
233+
reinitialise Terraform.
234+
Do this carefully:
235+
a wrong bucket name or wrong region can point your team at a different state file.
236+
237+
\bash{
238+
terraform init -reconfigure -backend-config=backend.hcl
239+
}
240+
241+
\warning{
242+
If \texttt{terraform plan} wants to destroy something important,
243+
do not apply until the team understands why.
244+
Ask a tutor if unsure.
245+
}
246+
247+
\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)