Terraform fundamentals
Write, plan and apply your first Terraform configuration for AWS: an encrypted, private audit-evidence bucket for Harbourline Bank. You learn providers, resources, data sources, variables, outputs and the init, plan, apply and destroy workflow.
Assumes: Terraform 1.17.2 (Docker image hashicorp/terraform:1.17.2) ยท Terraform AWS provider 6.73.0 (constraint ~> 6.0) ยท AWS CLI v2 ยท Region us-east-1. Verified against official sources on 2026-11-18.
Learning objectives
By the end of this lesson you can:
- Explain what Terraform is, how it differs from CloudFormation, and where the provider, the state and the plan fit.
- Read and write HCL:
terraform,provider,resource,data,variable,localsandoutputblocks. - Run the core workflow โ
init,fmt,validate,plan,apply,destroyโ from Docker on Windows with your SSO profile. - Read a plan the way a reviewer would: creates, updates in place, replacements and destroys.
- Use references, implicit and explicit dependencies,
count,for_eachand lifecycle settings safely. - Tag every resource automatically with provider
default_tags.
Prerequisites
- Module 10 overview โ read the "How the pieces fit" diagram first. The CloudFormation and CDK lessons in this module are useful background but not required.
- Module 5: Security โ S3 Block Public Access, KMS and bucket policies.
- Tools: Docker Desktop (the lesson runs Terraform in a container, so you do not need to install it), AWS CLI v2 with the
learn-sandboxSSO profile, and VS Code with the HashiCorp Terraform extension (optional, for syntax highlighting).
Why this matters in banking
Harbourline Bank's Payments team runs on AWS. The Data Platform team arrived from a company that used Terraform for everything, and their existing modules are written in HCL. The audit department needs an evidence bucket in every workload account to hold exported reports, and the platform team wants one definition of that bucket used everywhere.
Last year someone created such a bucket by hand in the console for an urgent audit request. They forgot to turn on versioning, so when a script overwrote the quarter's evidence file, the old version was gone. The finding in the internal audit report was not "S3 is unsafe". It was "infrastructure changes are not reviewed and not reproducible". Terraform answers that finding: the bucket's settings live in a Git repository, every change shows up as a reviewed diff called a plan, and the same code builds the same bucket in every account.
Many banks use Terraform alongside or instead of CloudFormation, especially when they also run workloads on Azure or need to manage non-AWS systems (GitHub, Datadog, Okta) in the same way. As a .NET developer moving to AWS, you will almost certainly meet both. This lesson gets you fluent in the Terraform half.
The idea in plain language
Terraform is a command-line tool from HashiCorp (now part of IBM). You describe the infrastructure you want in text files written in HCL (HashiCorp Configuration Language). Terraform then works out what has to change in the real world to match your description, shows you that list, and โ when you approve โ makes the changes by calling cloud APIs.
Three ideas carry the whole tool:
- Configuration โ the
.tffiles you write. They say what you want. - State โ a JSON file in which Terraform records what it created last time and the real IDs of those things (bucket names, key ARNs). Without state, Terraform could not tell "this bucket in my code" apart from "some other bucket in the account".
- Plan โ the difference between configuration, state and reality. A plan is a proposal: "create 3, change 1, destroy 0".
Terraform does not know anything about AWS by itself. It downloads a provider โ a plugin, here hashicorp/aws โ that knows how to call the AWS APIs for each resource type. The same Terraform binary with a different provider manages Azure, GitHub or Kubernetes.
Analogy: think of a building surveyor and a builder. Your
.tffiles are the architect's drawings. The state file is the surveyor's record of what was actually built last time, with serial numbers. The plan is the builder's quote: "to match the new drawings I'll add a window, move a door and knock nothing down". Nobody picks up a tool until you sign the quote.
What problem the tool solves
Without IaC, environments drift apart, changes are invisible to reviewers, and rebuilding an account after an incident depends on someone's memory. Terraform solves this with a declarative, provider-based model:
- Declarative. You write the end state, not the steps. Terraform orders the API calls from the dependency graph it builds from your references.
- Plan before apply. Every change can be reviewed โ by a person in a pull request and by policy tools such as Checkov (see Policy-as-code and secure deployment).
- Multi-provider. One language for AWS, Azure, GitHub, PagerDuty and hundreds more. This is Terraform's main advantage over CloudFormation.
- Large ecosystem. Thousands of public modules (covered in Terraform modules).
Honest limitations:
- You own the state. CloudFormation keeps its state inside the AWS service. Terraform's state is a file you must store, encrypt, lock and back up โ see Terraform state. State files contain resource attributes, which can include secrets.
- No automatic rollback. If an
applyfails half-way, CloudFormation rolls the stack back. Terraform stops, records what it did create, and leaves you to fix the code and apply again. - Provider lag. A new AWS feature appears in the AWS provider when someone implements it. Usually that is days or weeks; occasionally longer. CloudFormation sometimes has it first, sometimes later.
- Licence. Since version 1.6 (August 2023) Terraform has been under the Business Source License (BSL 1.1), not an open-source licence. Using it to manage your own infrastructure is allowed; building a competing hosted product is not. OpenTofu is the open-source fork run under the Linux Foundation, and it is largely compatible with the HCL in this lesson. Your bank's legal team, not you, decides whether the licence is acceptable.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | Terraform on AWS | What's different |
|---|---|---|
Terraform with azurerm | Terraform with hashicorp/aws | Same CLI and HCL; only the resource types change (aws_s3_bucket instead of azurerm_storage_account) |
Bicep param | variable block | Terraform variables have types and validation blocks; values come from .tfvars files, -var or TF_VAR_* environment variables |
Bicep output | output block | Outputs are also stored in state and can be read by other configurations |
Bicep existing keyword | data source | A data source reads something Terraform does not manage, such as the current account ID |
| ARM what-if / deployment stacks | terraform plan | The plan compares against state, then refreshes against the real API |
| Resource group as the deletion boundary | The state file (one configuration) is the boundary | terraform destroy removes everything in that state, nothing else |
| Azure tags inherited by policy | Provider default_tags | Tags applied to every taggable resource from one place |
az login | aws sso login --profile learn-sandbox | Terraform's AWS provider uses the same credential chain as the AWS CLI and SDKs |
NuGet package versions in .csproj | Provider version constraints + .terraform.lock.hcl | The lock file pins exact provider builds with hashes, like packages.lock.json |
Architecture
The workflow
Security-boundary view
- Credentials come from your SSO session โ never from access keys in
.tffiles orterraform.tfvars. - The state file sits inside the trust boundary. Anyone who can read it learns your resource layout and any secret attribute values. In this lesson it is local; the next lesson moves it into an encrypted S3 bucket.
- The provider plugin is third-party code that runs with your AWS credentials. The lock file records its checksums so a tampered download is rejected.
Step-by-step implementation
Create the project folder
Create C:\dev\hl-m10-l8 and open it in VS Code. Terraform treats every .tf file in the folder as one configuration โ file names are just for humans. The usual split is:
| File | Holds |
|---|---|
versions.tf | terraform block: Terraform and provider version constraints |
providers.tf | provider "aws" settings and default tags |
variables.tf | Inputs |
main.tf | Resources and data sources |
outputs.tf | Values to print or share |
terraform.tfvars | Your values for the inputs (do not commit secrets here) |
Sign in and make credentials available to the container
Run aws sso login --profile learn-sandbox. The CLI caches a short-lived token under %USERPROFILE%\.aws\sso\cache. The Terraform container reads the same files when you mount %USERPROFILE%\.aws read-only, and you tell it which profile to use with AWS_PROFILE.
Write the configuration
Copy the files from the Complete code section. Set owner in terraform.tfvars to your name in lower case.
Initialise
terraform init downloads the AWS provider into .terraform/ and writes .terraform.lock.hcl. Commit the lock file; never commit .terraform/.
Format and validate
terraform fmt rewrites files into the canonical style (like dotnet format). terraform validate checks syntax and types without calling AWS.
Plan and save the plan
terraform plan -out=tfplan writes the exact proposal to a binary file. Read every line. You should see 7 to add and nothing to change or destroy.
Apply the saved plan
terraform apply tfplan executes exactly what you reviewed โ no new surprises from changes made between plan and apply. If anything changed in the meantime, Terraform refuses the stale plan.
Make a change and read the diff
Change noncurrent_days from 30 to 90 and plan again. You should see ~ update in-place for the lifecycle configuration only. Then change the bucket's bucket_suffix variable and plan: the bucket shows -/+ destroy and then create replacement because S3 bucket names cannot be changed. Discard that change โ this is exactly the line a reviewer must catch.
Destroy
terraform destroy shows a plan of deletions and asks you to type yes. Afterwards, check that nothing tagged Lab=m10-l8 remains.
AWS Console instructions
Terraform is a CLI tool, so you use the console only to check the result:
- Console โ S3 โ Buckets and open
hl-m10-l8-audit-<account-id>. - Properties tab: confirm Bucket Versioning: Enabled, Default encryption: SSE-KMS with the AWS managed key
aws/s3, and Bucket Key: Enabled. Scroll to Tags and confirm the four lab tags. - Permissions tab: confirm Block public access: On (all four settings), Object Ownership: Bucket owner enforced, and the bucket policy statement
DenyInsecureTransport. - Management tab: the lifecycle rule
expire-noncurrent-versions.
Do not change anything here. If you do, the next terraform plan will show it as drift and propose to put it back โ which is a good experiment for the ๐ก exercise.
AWS CLI
# Sign in once; the token lasts for the SSO session duration
aws sso login --profile learn-sandbox
# The account ID becomes part of the bucket name, so note it
aws sts get-caller-identity --profile learn-sandbox --query Account --output text
# After apply: confirm versioning and encryption
aws s3api get-bucket-versioning --bucket hl-m10-l8-audit-111122223333 --profile learn-sandbox
aws s3api get-bucket-encryption --bucket hl-m10-l8-audit-111122223333 --profile learn-sandbox
# Confirm Block Public Access
aws s3api get-public-access-block --bucket hl-m10-l8-audit-111122223333 --profile learn-sandbox
# After destroy: nothing tagged for this lab should remain
aws resourcegroupstaggingapi get-resources \
--tag-filters Key=Lab,Values=m10-l8 \
--profile learn-sandbox --region us-east-1 \
--query "ResourceTagMappingList[].ResourceARN"Replace 111122223333 with your account ID. The tagging API can list a deleted resource for a short time after deletion; run it again after a minute if you see the bucket.
Running Terraform in Docker on Windows
Every Terraform command in this lesson runs in the official image. In PowerShell:
# One reusable function for this session: mounts the project and your AWS config (read-only)
function tf {
docker run --rm -it `
-v "${PWD}:/workspace" -w /workspace `
-v "$env:USERPROFILE\.aws:/root/.aws:ro" `
-e AWS_PROFILE=learn-sandbox `
hashicorp/terraform:1.17.2 @args
}
tf init
tf fmt
tf validate
tf plan -out=tfplan
tf apply tfplan
tf destroyIf you prefer a native install, winget install Hashicorp.Terraform โ VERIFY the package ID with winget search terraform, then use terraform in place of tf.
Infrastructure as Code
This whole lesson is infrastructure as code. For comparison, here is the same bucket core in CDK (C#), which you met earlier in this module. Notice that the CDK L2 construct turns several Terraform resources into properties of one object.
resource "aws_s3_bucket" "audit" {
bucket = "hl-m10-l8-audit-${data.aws_caller_identity.current.account_id}"
}
resource "aws_s3_bucket_versioning" "audit" {
bucket = aws_s3_bucket.audit.id
versioning_configuration {
status = "Enabled"
}
}
resource "aws_s3_bucket_public_access_block" "audit" {
bucket = aws_s3_bucket.audit.id
block_public_acls = true
block_public_policy = true
ignore_public_acls = true
restrict_public_buckets = true
}Since version 4 of the AWS provider, S3 bucket settings are separate resources (aws_s3_bucket_versioning, aws_s3_bucket_server_side_encryption_configuration and so on). Old blog posts that put versioning { } inside aws_s3_bucket are out of date.
Complete code
terraform {
# Fail fast if someone runs an old CLI that lacks features we rely on
required_version = ">= 1.14.0, < 2.0.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.0" # any 6.x, never 7.0 without a deliberate upgrade
}
}
}provider "aws" {
region = var.region
# Every taggable resource created by this provider gets these tags
default_tags {
tags = {
Project = "cea-lab"
Lab = "m10-l8"
Environment = "learn"
Owner = var.owner
ManagedBy = "terraform"
}
}
}variable "region" {
description = "AWS Region for every resource in this configuration."
type = string
default = "us-east-1"
}
variable "owner" {
description = "Your name in lower case; becomes the Owner tag."
type = string
validation {
condition = can(regex("^[a-z][a-z0-9-]{1,30}$", var.owner))
error_message = "owner must be 2-31 lower-case letters, digits or hyphens, starting with a letter."
}
}
variable "bucket_suffix" {
description = "Purpose suffix in the bucket name."
type = string
default = "audit"
}
variable "noncurrent_days" {
description = "Days to keep old object versions before S3 deletes them."
type = number
default = 30
validation {
condition = var.noncurrent_days >= 1 && var.noncurrent_days <= 3650
error_message = "noncurrent_days must be between 1 and 3650."
}
}
variable "force_destroy" {
description = "Allow terraform destroy to delete a bucket that still holds objects. Learning only."
type = bool
default = true
}# Read-only lookups: who am I, and which partition am I in?
data "aws_caller_identity" "current" {}
data "aws_partition" "current" {}
locals {
account_id = data.aws_caller_identity.current.account_id
bucket_name = "hl-m10-l8-${var.bucket_suffix}-${local.account_id}"
}
resource "aws_s3_bucket" "audit" {
bucket = local.bucket_name
# Learning shortcut: lets destroy remove a non-empty bucket
force_destroy = var.force_destroy
}
resource "aws_s3_bucket_ownership_controls" "audit" {
bucket = aws_s3_bucket.audit.id
rule {
object_ownership = "BucketOwnerEnforced" # ACLs disabled
}
}
resource "aws_s3_bucket_public_access_block" "audit" {
bucket = aws_s3_bucket.audit.id
block_public_acls = true
block_public_policy = true
ignore_public_acls = true
restrict_public_buckets = true
}
resource "aws_s3_bucket_versioning" "audit" {
bucket = aws_s3_bucket.audit.id
versioning_configuration {
status = "Enabled"
}
}
resource "aws_s3_bucket_server_side_encryption_configuration" "audit" {
bucket = aws_s3_bucket.audit.id
rule {
apply_server_side_encryption_by_default {
sse_algorithm = "aws:kms" # AWS managed key aws/s3: no monthly key fee
}
bucket_key_enabled = true # fewer KMS requests, lower cost
}
}
resource "aws_s3_bucket_lifecycle_configuration" "audit" {
bucket = aws_s3_bucket.audit.id
rule {
id = "expire-noncurrent-versions"
status = "Enabled"
filter {} # whole bucket
noncurrent_version_expiration {
noncurrent_days = var.noncurrent_days
}
abort_incomplete_multipart_upload {
days_after_initiation = 7
}
}
# Lifecycle rules on noncurrent versions need versioning first
depends_on = [aws_s3_bucket_versioning.audit]
}
data "aws_iam_policy_document" "tls_only" {
statement {
sid = "DenyInsecureTransport"
effect = "Deny"
actions = ["s3:*"]
principals {
type = "*"
identifiers = ["*"]
}
resources = [
aws_s3_bucket.audit.arn,
"${aws_s3_bucket.audit.arn}/*",
]
condition {
test = "Bool"
variable = "aws:SecureTransport"
values = ["false"]
}
}
}
resource "aws_s3_bucket_policy" "audit" {
bucket = aws_s3_bucket.audit.id
policy = data.aws_iam_policy_document.tls_only.json
# Block Public Access must exist before any policy is attached
depends_on = [aws_s3_bucket_public_access_block.audit]
}output "bucket_name" {
description = "Name of the audit evidence bucket."
value = aws_s3_bucket.audit.bucket
}
output "bucket_arn" {
description = "ARN of the audit evidence bucket, for IAM policies elsewhere."
value = aws_s3_bucket.audit.arn
}
output "partition" {
description = "aws, aws-cn or aws-us-gov."
value = data.aws_partition.current.partition
}owner = "yourname".terraform/
*.tfstate
*.tfstate.*
tfplan
crash.log
# Keep .terraform.lock.hcl in GitCode explained line by line
versions.tf
required_version = ">= 1.14.0, < 2.0.0"โ refuses to run on an older or a future major CLI. Teams pin this so everyone produces the same plan.required_providers { aws = { source = "hashicorp/aws", version = "~> 6.0" } }โ the provider's registry address and a pessimistic constraint:~> 6.0means "6.0 or higher, below 7.0". Major versions of the AWS provider contain breaking changes, so a jump from 6 to 7 should be a deliberate pull request.
providers.tf
provider "aws" { region = var.region }โ configures the plugin. Credentials are not here: the provider follows the standard chain (environment variables, thenAWS_PROFILEand~/.aws/config, then container or instance roles), just like the AWS SDK for .NET.default_tags { tags = { โฆ } }โ merges these tags into every resource that supports tags. Resource-leveltagswin when a key is duplicated. This is how you meet theProject/Lab/Environment/Ownerconvention without repeating yourself.
variables.tf
variable "owner" { type = string โฆ }โ an input with a type. No default means Terraform asks for it, or reads it fromterraform.tfvars.validation { condition = can(regex(โฆ)) โฆ }โ runs at plan time.can()turns a function error intofalse. Validation is your first, cheapest guard rail: a bad value fails before any API call.variable "force_destroy"โ a deliberate, visible switch for the learning shortcut, defaulting totruehere and tofalsein any real module.
main.tf
data "aws_caller_identity" "current" {}โ a data source: read-only. It calls STSGetCallerIdentityat plan time. Referencingdata.aws_caller_identity.current.account_idgives you the account number without hard-coding it.locals { โฆ }โ named expressions, like privateconstvalues in a class. Use them to avoid repeating string interpolation.resource "aws_s3_bucket" "audit"โ the resource type (aws_s3_bucket) and the local name (audit). Together they form the addressaws_s3_bucket.audit, which is how Terraform tracks this object in state. Renamingauditlater looks like "destroy one, create another" unless you add amovedblock (see Terraform modules).bucket = local.bucket_nameโ globally unique name, made unique by the account ID.force_destroy = var.force_destroyโ without it, destroying a bucket that still contains objects (including old versions) fails. That failure is a feature in production.aws_s3_bucket_ownership_controlswithBucketOwnerEnforcedโ disables ACLs so access is controlled only by policies. New buckets have this by default; declaring it makes the intent explicit and catches drift.aws_s3_bucket_public_access_blockโ all four switchestrue. Account-level Block Public Access should also be on (Module 5); this is defence in depth.bucket = aws_s3_bucket.audit.idโ an implicit dependency. Because this resource references the bucket, Terraform creates the bucket first and destroys it last. You rarely need to think about ordering.aws_s3_bucket_versioningโ keeps every version, so an overwrite is recoverable.sse_algorithm = "aws:kms"with no key ID โ SSE-KMS using the AWS managed keyaws/s3. A customer managed key gives you control over the key policy and rotation and costs about $1 per month; you will use one in the state lesson.bucket_key_enabled = trueโ S3 asks KMS for a bucket-level data key and reuses it, cutting KMS request volume and cost.filter {}inside the lifecycle rule โ an empty filter applies to the whole bucket. In provider v6 you should state the filter explicitly rather than leave it out.depends_on = [aws_s3_bucket_versioning.audit]โ an explicit dependency, needed when the relationship is real but not visible through a reference.data "aws_iam_policy_document" "tls_only"โ builds IAM JSON from HCL. It is checked for structure at plan time and avoids hand-written JSON strings with escaping mistakes.condition { test = "Bool", variable = "aws:SecureTransport", values = ["false"] }โ denies any request made over plain HTTP.aws_s3_bucket_policywithdepends_onthe public access block โ attaching a policy before Block Public Access exists can briefly create a window, and some policy shapes would be rejected. Ordering it explicitly is cheap.
outputs.tf
output "bucket_arn"โ printed after apply and stored in state. Another configuration can read it (withterraform_remote_stateor, better, an SSM parameter) to grant access.
Reading a plan like a reviewer
The plan is the most important output Terraform produces. Learn the symbols:
| Symbol | Meaning | Risk |
|---|---|---|
+ | create | Low, but check names, encryption and public access |
~ | update in place | Usually low; read which attributes change |
-/+ | destroy, then create a replacement | High for anything holding data โ the old object and its contents go |
+/- | create replacement, then destroy (when create_before_destroy is set) | Medium; two copies briefly exist |
- | destroy | High for stateful resources |
<= | read a data source during apply | Usually harmless |
(known after apply) | value the API assigns, such as an ARN or ID | Normal |
# forces replacement | this attribute cannot be changed in place | Read it twice |
A minimal excerpt for this lesson's first plan:
# aws_s3_bucket.audit will be created
+ resource "aws_s3_bucket" "audit" {
+ arn = (known after apply)
+ bucket = "hl-m10-l8-audit-111122223333"
+ force_destroy = true
+ tags_all = {
+ "Environment" = "learn"
+ "Lab" = "m10-l8"
+ "ManagedBy" = "terraform"
+ "Owner" = "yourname"
+ "Project" = "cea-lab"
}
}
Plan: 7 to add, 0 to change, 0 to destroy.tags_all is the merged result of default_tags and the resource's own tags.
Expressions you will use every day
| Feature | Example | Use |
|---|---|---|
| String interpolation | "hl-${var.env}-payments" | Build names |
| Conditional | var.env == "prod" ? 35 : 7 | Different values per environment |
count | count = var.create_alarm ? 1 : 0 | Optional resource; address becomes aws_x.y[0] |
for_each over a map | for_each = { payments = 30, ledger = 90 } | Several similar resources keyed by name; address aws_x.y["payments"] |
for expression | [for k, v in aws_s3_bucket.b : v.arn] | Transform collections |
lifecycle { prevent_destroy = true } | On a database or KMS key | Plan fails if it would destroy the resource |
lifecycle { ignore_changes = [tags["LastScanned"]] } | A tag set by another system | Stop Terraform fighting another tool |
lifecycle { create_before_destroy = true } | Launch templates, certificates | Avoid downtime on replacement |
Prefer for_each over count for anything with an identity. With count, removing the first item of a list shifts every index, and Terraform plans to destroy and recreate the rest. With for_each, items are keyed by name and removing one touches only that one.
# Two evidence buckets with different retention, keyed by purpose
variable "evidence_buckets" {
type = map(number)
default = {
payments = 30
ledger = 90
}
}
resource "aws_s3_bucket" "evidence" {
for_each = var.evidence_buckets
bucket = "hl-m10-l8-${each.key}-${local.account_id}"
}
resource "aws_s3_bucket_versioning" "evidence" {
for_each = aws_s3_bucket.evidence
bucket = each.value.id
versioning_configuration {
status = "Enabled"
}
}Security considerations
โ Learning shortcut โ not for production
This lesson keeps state on your laptop, applies from your laptop, and sets force_destroy = true on the bucket. In production: state goes in an encrypted, versioned, access-controlled S3 bucket with locking (Terraform state); plan runs in a pipeline on every pull request and apply runs only from the pipeline's deploy role after approval (Module 9); and force_destroy stays false, with lifecycle { prevent_destroy = true } on evidence buckets.
- Never put credentials in
.tfor.tfvars. The provider supportsaccess_keyandsecret_keyarguments; do not use them. Use SSO locally and OIDC-federated roles in CI. - Treat state as sensitive.
sensitive = trueon a variable or output hides it from CLI output, not from the state file. - Pin providers and commit the lock file.
.terraform.lock.hclrecords hashes of the provider packages.terraform initfails if a downloaded provider does not match. For multiple platforms (Windows laptops, Linux CI) runterraform providers lock -platform=windows_amd64 -platform=linux_amd64so the file holds hashes for both. - Review
-/+lines on anything that stores data. Replacing an S3 bucket, RDS instance or KMS key is data loss or worse. - Scan before apply. Run Checkov against the configuration (covered in Policy-as-code and secure deployment).
- Least privilege for whoever applies. Your SSO permission set probably has broad rights in the sandbox. A pipeline role should be limited to the services the configuration touches.
Banking use case
Harbourline's platform team publishes the evidence-bucket configuration as a module. Each workload account โ Payments, Accounts API, Data Platform โ has a small Terraform root configuration that calls the module with its own retention period. Internal Audit gets read access to the Git repository and the pipeline history, so for any bucket they can answer who changed what, when, who approved it and what the plan said. When the regulator asks how long payment evidence is retained, the answer is a line in Git, not a screenshot.
Because S3 bucket names are global, the team includes the account ID in every name. Because names cannot be changed, the plan's forces replacement line on bucket is configured as a blocking review rule in the pipeline.
Common mistakes
- Committing
terraform.tfstateโ the state contains resource details and possibly secrets โ add it to.gitignorefrom day one and move to remote state. - Not committing
.terraform.lock.hclโ colleagues and CI get different provider versions and different plans โ commit it, and update it withterraform init -upgradein a reviewed pull request. - Using
countfor a list of named things โ removing one item recreates others โ usefor_eachwith a map or set. - Writing
versioning { enabled = true }insideaws_s3_bucketโ copied from a pre-v4 blog post โ use the separateaws_s3_bucket_versioningresource. - Running
terraform applywithout a saved plan โ the apply recomputes the plan and may differ from what was reviewed โplan -out=tfplanthenapply tfplan. - Hard-coding the account ID or Region โ the code breaks in the next account โ use
data.aws_caller_identity,data.aws_regionand variables. - Editing resources in the console "just this once" โ the next plan reverts it, or worse, someone's urgent fix is silently undone โ make the change in code.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
No valid credential sources found | SSO session expired, or .aws not mounted into the container | Run aws sso login --profile learn-sandbox; check the -v mount and AWS_PROFILE |
The SSO session associated with this profile has expired | Token past its lifetime | Sign in again |
BucketAlreadyExists | The name is taken in another account | Keep the account ID in the name |
Error acquiring the state lock | Another Terraform process, or a crashed one | Wait; with local state delete nothing unless you are sure no process runs. Remote locking is in the next lesson |
Inconsistent dependency lock file | Provider changed in required_providers but lock file not updated | terraform init -upgrade, review and commit the lock file |
Saved plan is stale | State changed after plan -out | Plan again, review again, apply the new plan |
BucketNotEmpty on destroy | force_destroy = false and objects or versions remain | Empty the bucket (including versions) or set force_destroy = true for learning only |
Plan shows changes to tags_all on every run | A tag set both in default_tags and tags with different values, or another tool tagging | Pick one source of truth; use ignore_changes for externally managed tags |
Invalid value for variable | Your validation block rejected the input | Read the custom error message |
Cost and cleanup
- Terraform CLI and the AWS provider: free.
- An empty S3 bucket: free. A few test objects: fractions of a cent.
- SSE-KMS with the AWS managed key
aws/s3: no monthly key charge; KMS requests count against the KMS free tier (20,000 requests per month), and the Bucket Key reduces them further. - Expected cost for this lesson: $0.00 if you destroy within the day.
# Remove everything this configuration created
tf destroy
# Confirm nothing tagged for this lab remains
aws resourcegroupstaggingapi get-resources --tag-filters Key=Lab,Values=m10-l8 `
--profile learn-sandbox --region us-east-1 --query "ResourceTagMappingList[].ResourceARN"
# Remove local artefacts (state is now empty, but delete it anyway)
Remove-Item -Recurse -Force .terraform, terraform.tfstate*, tfplan -ErrorAction SilentlyContinueExercises
- ๐ข Guided: Build, plan, apply and destroy the configuration exactly as written. Then add a second output
versioning_statusthat printsaws_s3_bucket_versioning.audit.versioning_configuration[0].status. Apply and confirm it printsEnabled. - ๐ก Challenge: Apply the configuration. In the console, suspend versioning on the bucket. Run
terraform planwithout changing code. Explain the output, then decide how to restore the setting. Next, add anevidence_bucketsmap withpayments = 30andledger = 90, usingfor_each, and confirm that removingpaymentsfrom the map only plans to destroy that one bucket. - ๐ด Live problem: A colleague's pull request changes
bucket_suffixfromaudittoaudit-evidence"to make the name clearer". The plan in the PR says1 to add, 4 to change, 1 to destroy, and the bucket holds six months of audit exports. Write the review comment you would leave, and propose two safe ways to get the clearer name without losing data.
Assignment
Create a public repository harbourline-iac-terraform with this configuration, a README.md explaining the workflow, a .gitignore, the committed lock file (with hashes for both windows_amd64 and linux_amd64), and a docs/plan-review.md that annotates a real plan output line by line. Do not commit state.
Solutions
output "versioning_status" {
description = "Should always be Enabled."
value = aws_s3_bucket_versioning.audit.versioning_configuration[0].status
}versioning_configuration is a nested block, and Terraform exposes nested blocks as lists even when there is only one, hence [0]. After apply, the output shows versioning_status = "Enabled". You can also run tf output versioning_status at any time without calling AWS, because outputs are read from state.
The plan shows ~ aws_s3_bucket_versioning.audit will be updated in-place with status: "Suspended" -> "Enabled". During planning Terraform refreshes each resource from the AWS API, compares reality with the configuration, and proposes to put it back. That is drift detection for free. The correct fix is to apply the plan โ the code is the source of truth โ and then find out who changed it (CloudTrail PutBucketVersioning, Module 5).
For the second part, with for_each the resource addresses are aws_s3_bucket.evidence["payments"] and aws_s3_bucket.evidence["ledger"]. Removing payments from the map plans - for exactly the ["payments"] instances (bucket and its versioning) and leaves ["ledger"] alone. With count and a list, removing the first item would shift ledger from index 1 to index 0 and plan a destroy-and-recreate โ which is why for_each is preferred.
Review comment: "This PR replaces the audit bucket. bucket forces replacement because S3 names are immutable, so the plan destroys hl-m10-l8-audit-โฆ and creates a new, empty bucket. With force_destroy = true the six months of evidence would be deleted; with false the apply would fail half-way after creating the new bucket. The four in-place changes are the dependent resources being re-pointed. Please do not merge."
Safe options:
- Keep the name; change the description. Bucket names are identifiers, not documentation. Put the friendly name in a
Purposetag. - Migrate deliberately. Add the new bucket alongside the old one, copy the data (S3 Batch Operations or
aws s3 syncwith versions considered), switch writers, verify, keep the old bucket read-only underprevent_destroyfor the retention period, and remove it later in a separate, approved change.
Also suggest adding lifecycle { prevent_destroy = true } to evidence buckets so this class of mistake fails at plan time.
Knowledge check
Answer: It initialises the working directory: downloads providers (and modules) into .terraform/, configures the backend, and writes .terraform.lock.hcl with the exact provider versions and hashes. Commit the lock file; never commit .terraform/. It does not call AWS to create anything.
Answer: A resource is something Terraform creates, updates and destroys, and tracks in state. A data source only reads something that exists โ the current account ID, an existing VPC, an AMI โ and never changes it. Using a data source for an object you then manage elsewhere is the right pattern for sharing without coupling.
Answer: apply tfplan executes exactly the reviewed proposal. A bare apply recomputes the plan, so code merged a minute later, a changed variable or drift in the account could produce different actions from the ones a reviewer approved. Terraform also rejects a saved plan if state changed after it was made.
Answer: Destroy and then create a replacement, because an attribute cannot be changed in place (for example bucket). For a bucket, the old bucket and its objects are deleted (or the destroy fails if it is non-empty), so it means data loss or a broken apply.
Answer: They are set in the provider "aws" block and applied to every taggable resource that provider creates. The resource-level tags value wins for a duplicated key; tags_all shows the merged result.
Answer: No. It only redacts the value in CLI output and plans. The value is still stored in plain text inside state, which is why state must be encrypted and access-controlled.
Interview questions
- "How does Terraform know what to change?" โ It compares three things: the configuration, the state file (what it created last time, with real IDs), and the current reality from a refresh against the provider's APIs. The plan is the set of actions that makes reality match the configuration.
- "Terraform or CloudFormation for a bank?" โ Both are defensible. Terraform gives one language across clouds and SaaS tools and a strong plan workflow, but you own the state and there is no automatic rollback. CloudFormation is AWS-native with managed state, rollback, StackSets and drift detection. I would choose based on the team's estate, skills and the platform team's support model โ and I would document it in an ADR. (See CloudFormation vs CDK vs Terraform.)
- "
countorfor_each?" โfor_eachfor anything with a natural key, because it keeps addresses stable when items are added or removed.countfor a simple on/off switch. - "How do you stop Terraform destroying a production database?" โ
lifecycle { prevent_destroy = true }, deletion protection on the resource itself, a policy check in CI that fails on anydeleteaction against stateful resource types, and apply only through an approved pipeline. - "What is in the lock file and why does it matter for supply-chain security?" โ The selected provider versions and their package hashes.
initrefuses a provider whose hash does not match, so a tampered or substituted plugin cannot slip in silently.
Certification practice
A DevOps engineer reviews a Terraform plan in a pull request. It shows -/+ resource "aws_db_instance" "ledger" with # forces replacement next to identifier. The database holds production ledger data. What is the BEST action?
A. Approve; Terraform will snapshot the database automatically before replacing it.
B. Reject the change, revert the identifier edit, and add lifecycle { prevent_destroy = true } to the resource.
C. Approve, but run terraform apply -refresh=false to skip the replacement.
D. Approve, because the plan also creates the replacement before destroying the original.
Answer: B. Changing the identifier replaces the instance, destroying the original. A is wrong: Terraform takes no automatic snapshot (a final snapshot depends on skip_final_snapshot and is no substitute for avoiding the replacement). C is wrong: skipping refresh does not remove a configured replacement. D is wrong: the symbol is -/+, which destroys first, and even create-before-destroy would leave you with an empty new database.
A SysOps administrator must ensure every resource created by several Terraform configurations carries CostCentre and Environment tags, with the least ongoing effort. What should they do?
A. Add a tags argument to each resource in every configuration.
B. Configure default_tags in the aws provider block of each configuration.
C. Create an AWS Config rule that adds missing tags after creation.
D. Use a CloudFormation stack to tag resources Terraform creates.
Answer: B. Provider-level default_tags apply the tags to every taggable resource from a single place. A works but repeats the same block everywhere and is easy to forget. C is wrong: the managed required-tags rule detects missing tags; it does not add them (remediation is a separate setup and happens after creation). D is wrong: CloudFormation stack tags only apply to resources in that stack.
A team runs Terraform in GitHub Actions to deploy to AWS. Security forbids long-lived access keys. Which approach meets the requirement?
A. Store an IAM user's access keys as encrypted GitHub secrets and rotate them every 90 days.
B. Configure GitHub's OIDC provider in IAM and let the workflow assume a role with sts:AssumeRoleWithWebIdentity, restricted by repository and branch.
C. Put the access keys in terraform.tfvars and mark the variables sensitive.
D. Use the AWS provider's shared_credentials_files argument pointing at a file committed to the repository.
Answer: B. OIDC federation issues short-lived credentials per run, scoped by the trust policy's sub condition. A still uses long-lived keys. C and D put secrets in files โ sensitive only hides values from output, and a committed credentials file is a leak.
Completion checklist
- I can explain configuration, state, plan and provider in two sentences
- I ran
init,fmt,validate,plan -out,applyanddestroyin Docker - I can read
+,~,-/+and-in a plan and say which are risky - I committed the lock file and ignored state and
.terraform/ - I ran the cleanup and the tagging check returned nothing for
Lab=m10-l8
Key takeaways
- Terraform compares configuration, state and reality, and proposes a plan. Review the plan, then apply exactly that plan.
- Providers are versioned plugins; pin them with constraints and commit
.terraform.lock.hcl. -/+and-on stateful resources are the lines that cause incidents. Guard them withprevent_destroy, deletion protection and policy checks.- Use
default_tags, data sources and variables with validation instead of repeating or hard-coding values. - You own the state. The next lesson makes it safe.
Further reading
- Terraform S3 backend documentation โ you will need it in the next lesson
- Terraform AWS provider on the Terraform Registry
- Terraform language documentation
- Terraform CLI: plan command
- Amazon S3 Block Public Access
- Next lesson: Terraform state
Independent learning resource โ not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.
Testing CDK: assertions, snapshots and cdk-nag
Prove infrastructure controls with xUnit tests over the synthesized template, add a coarse snapshot that catches surprise changes, and run cdk-nag v3 as a test with every finding fixed or acknowledged with a written reason.
Terraform state
Move Terraform state into an encrypted, versioned S3 bucket with native lock files, see locking stop two applies racing each other, use workspaces carefully, and bring existing resources under management with import, moved and removed blocks.