CODE · PROVIDERS · PLAN · STATE · DRIFT · BACKENDS · MODULES

Terraform:
how code, state and AWS fit together

Terraform reads text files that describe the cloud resources you want and makes AWS match them. Between runs it keeps a record of everything it created, and that record, the state, decides what it changes, what it deletes and what it leaves alone.

The system on this page is the infrastructure behind a small shop’s receipts service. After each payment the app stores a PDF receipt in an S3 bucket and puts a job on a queue for a worker that renders it; an IAM role lets the app do both. The payments team describes all of it in one Terraform repository and changes it through pull requests. Each chapter edits that repository, or something in AWS, and shows exactly what Terraform does next.

Here is every part of a Terraform run. Most boxes won’t mean much yet; each chapter explains one of them.

MapSolid outlines are things on disk or in AWS; the dashed Region holds the receipts resources. Every AWS call starts at the provider.

You need to know what an S3 bucket, an IAM role and an API call are; no Terraform experience is assumed. Every plan, error and state excerpt comes from one run of Terraform 1.17.2 and the AWS provider 6.73.0 on 20 November 2026, against a local stand-in for AWS, so nothing was created in a real account. Queue URLs are shown in their real AWS form. Tap any figure to open it full screen and zoom. are tappable. Each deep dive ends with cues for the Terraform Associate (004) exam.

Configuration: the infrastructure you describe

You have an AWS account and a console. A bucket you click into existence leaves no record of its settings or of why it exists, and a second environment means clicking it all again. Terraform starts from text instead: a folder of files that describe the resources you want, reviewed and changed like any other code. What does a .tf file describe, and what name does Terraform give each thing in it?

STEP 01 / 04

THE CODE COMES FIRST

Fig 1.1The accent box is the code; faint parts arrive in later chapters.

The is every .tf file in one folder, read together as one document. Terraform reads all of them before it does anything, so file names and the order of blocks don’t matter: main.tf is a habit, not a rule. The folder you run terraform in is the ; here it is receipts-infra/, the payments team’s repository.

The files are written in , HashiCorp’s configuration language: blocks with a type, one or two labels, and arguments inside braces. For now the folder holds main.tf, which declares a bucket, a queue and a role. A second file, policy.tf, joins it later in this chapter.

STEP 02 / 04

A RESOURCE BLOCK DESCRIBES ONE OBJECT

Fig 1.2The accent row is the address Terraform uses; only the bucket name reaches AWS.

A block describes one object you want to exist. It starts with the block type, two labels and then a body of arguments. The first label is the resource type, aws_s3_bucket: its aws_ prefix says the AWS provider handles it. The second is a local name you choose, receipts. Inside the braces, bucket = "shop-receipts-prod" sets the bucket’s real name.

The type and the local name together make the , aws_s3_bucket.receipts. It is unique in the configuration, and every plan line and error message uses it. AWS never sees it: S3 knows the bucket only as shop-receipts-prod. The same file declares aws_sqs_queue.jobs and aws_iam_role.app, the queue and the role the app uses.

MAIN.TF: THE BUCKET, THE QUEUE AND THE ROLE
resource "aws_s3_bucket" "receipts" {
  bucket = "shop-receipts-prod"
}

resource "aws_sqs_queue" "jobs" {
  name                       = "receipt-jobs"
  tags                       = { team = "payments" }
  visibility_timeout_seconds = 60
}

resource "aws_iam_role" "app" {
  name = "receipts-app"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "ecs-tasks.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })
}
STEP 03 / 04

YOU SET ARGUMENTS, AWS RETURNS ATTRIBUTES

Fig 1.3Left is what the block says; the accent value on the right exists only after AWS creates the queue.

An argument is a value you set in a block: name, visibility_timeout_seconds = 60, tags. An attribute is a value of the real object, and some exist only once AWS has created it: the queue’s arn, its id and its url. The first plan prints each of them as (known after apply).

An expression such as aws_sqs_queue.jobs.arn reads another resource’s attribute; it is called a reference. The app’s role needs a policy that names both the bucket and the queue, so policy.tf builds it from aws_s3_bucket.receipts.arn and aws_sqs_queue.jobs.arn. Terraform can’t write that policy until both ARNs exist, so each reference also sets an order.

POLICY.TF: THE ROLE POLICY, BUILT FROM THREE REFERENCES
resource "aws_iam_role_policy" "app" {
  name = "receipts-app"
  role = aws_iam_role.app.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      { Effect = "Allow", Action = ["s3:PutObject", "s3:GetObject"], Resource = "${aws_s3_bucket.receipts.arn}/*" },
      { Effect = "Allow", Action = ["sqs:SendMessage", "sqs:ReceiveMessage"], Resource = aws_sqs_queue.jobs.arn },
    ]
  })
}
STEP 04 / 04

A DATA BLOCK ONLY READS

Fig 1.4Read across the accent row: a data source has nothing to destroy.

A reads something that already exists. data "aws_caller_identity" "me" {} asks AWS which account the credentials belong to, and the account output prints 123456789012. Its address starts with data., and Terraform reads it again on every plan. Only its last result is kept, in the state, Terraform’s record of what it manages (chapter 04).

A data source never creates, changes or destroys anything. Use one to look up a value another team owns, such as a VPC ID or the newest Amazon Linux image, instead of copying that value into your code.

THE ACCOUNT LOOKUP AND ITS OUTPUT
data "aws_caller_identity" "me" {}

output "account" {
  value = data.aws_caller_identity.me.account_id
}

COMMON QUESTIONS

Does the order of blocks in a file matter?
No. Terraform reads every block first and works out the order from references (chapter 03).
Is the local name receipts sent to AWS?
No. Only argument values such as bucket and tags reach AWS. The local name lives only in your code and in Terraform’s own records.
Can I write the configuration in JSON?
Yes. Files ending .tf.json use the same structure in JSON. People write HCL; tools that generate configuration write JSON.

WHAT YOU NOW KNOW

  • A configuration is every .tf file in one folder; each resource block describes one object you want.
  • aws_s3_bucket.receipts is an address: resource type plus local name, used by Terraform and never by AWS.
  • You set arguments; attributes such as arn come back after creation, and a reference to one also orders the work.
DEEP DIVE: HCL syntax, fmt and validate, variables, locals and outputs, meta-arguments

HCL in one page

A file is a list of blocks. A block has a type, zero or more labels and a body in braces; the body holds arguments (name = value) and nested blocks. A value is an expression: a literal, a reference, a function call such as jsonencode(…), or a string with ${…} interpolation. Lists use square brackets, maps use braces. Comments start with a hash or two slashes, or sit between slash-star and star-slash.

BLOCKS, EXPRESSIONS AND COMMENTS
# A comment. // also starts one; /* and */ wrap several lines.
variable "env" {
  type    = string
  default = "prod"
}

locals {
  # A string with interpolation, a list and a map.
  name    = "receipts-${var.env}"
  regions = ["eu-west-1", "us-east-1"]
  tags = {
    team = "payments"
    app  = "receipts"
  }
}

output "bucket_arn" {
  # An expression that reads another block: a reference.
  value = aws_s3_bucket.receipts.arn
}

terraform fmt and terraform validate

terraform fmt rewrites every file in the folder to the canonical style: two-space indents and aligned equals signs. With -check it rewrites nothing and exits non-zero when a file isn’t formatted, which is what a CI job runs. terraform validate checks syntax, argument names, types and references against the provider’s schema without calling AWS, so it needs no credentials.

Variables, locals and outputs

A variable block declares an input with a type and an optional default, read as var.env. A locals block names a value computed once, such as "receipts-${var.env}", read as local.name. An output block prints a value after apply, as account does here, and is how a module hands values back to its caller (chapter 10).

Meta-arguments

A few arguments work on any resource because Terraform itself reads them, not the provider: count and for_each make copies (chapter 10), depends_on adds an ordering rule no reference implies (chapter 03), provider picks a second provider configuration (chapter 02), and lifecycle limits what a plan may do to the resource (chapter 08).

ON THE EXAM

“differentiate resource and data blocks”
a data block reads; a resource block creates, updates and destroys
“format configuration to the canonical style”
terraform fmt; -check fails CI without rewriting
“check a configuration without accessing remote services”
terraform validate
“refer to another resource’s attribute”
<type>.<name>.<attribute>, for example aws_s3_bucket.receipts.arn

Providers: plugins that turn blocks into API calls

You have a main.tf that describes a bucket, a queue and a role. The terraform binary itself has no idea what an S3 bucket is: it knows how to read HCL, plan and keep records, and nothing about any cloud. Something else has to know the S3 API, its arguments and its errors. How does a block of HCL become a CreateBucket call to AWS?

STEP 01 / 04

THE PROVIDER IS A SEPARATE PROGRAM

Fig 2.1The accent path runs from the registry to the provider and on to core; core itself never talks to AWS.

A is a plugin: a separate program that knows one API. hashicorp/aws 6.73.0 knows every AWS service Terraform can manage: its resource types, their arguments and the API calls behind them. On each run the terraform binary, called Terraform core, starts it as a child process and asks it to do everything that touches AWS.

The provider comes from the , registry.terraform.io, and the exact version is recorded in a lock file in your working directory. Core holds no AWS code at all, so a new AWS feature arrives as a new provider release, not a new Terraform.

STEP 02 / 04

INIT DOWNLOADS THE PROVIDER AND PINS IT

Fig 2.2Follow 1 to 3; the accent file is the one you commit.

terraform init prepares the working directory. It reads the required_providers block, where version = "~> 6.73" is a version constraint: any 6.x release from 6.73 up. The registry answered with 6.73.0, the newest match on the day of the run, and init downloaded it into .terraform/providers/.

Init then wrote the , .terraform.lock.hcl: the chosen version, the constraint, and hashes of the package (h1: and zh: lines) that every later download is checked against. The next init on any machine installs exactly that version, until you run terraform init -upgrade.

PROVIDERS.TF: WHICH TERRAFORM AND WHICH PROVIDER
terraform {
  required_version = ">= 1.17"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.73"
    }
  }
}
.TERRAFORM.LOCK.HCL AFTER THE FIRST INIT, HASHES CUT
# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.

provider "registry.terraform.io/hashicorp/aws" {
  version     = "6.73.0"
  constraints = "~> 6.73"
  hashes = [
    # … one hash per platform
  ]
}
STEP 03 / 04

CORE AND PROVIDER TALK OVER GRPC

Fig 2.3Only hop 5 and its reply leave your machine; hops 1 to 4 run between two local processes.

Core and the provider talk over gRPC, a remote procedure call protocol, on a local socket; hashicorp/aws speaks version 5 of Terraform’s plugin protocol. First core calls GetSchema to learn the provider’s schema: every resource type, its arguments, and which of them can’t change in place. Then Configure passes the Region and the credentials.

For each resource, core calls PlanResourceChange during a plan and ApplyResourceChange during an apply. Only then does the provider turn the bucket into CreateBucket, an HTTPS request to S3 signed with your AWS credentials, and hand the new attributes back to core. Reading an existing object is one more call, ReadResource.

STEP 04 / 04

THE PROVIDER BLOCK SETS REGION AND CREDENTIALS

Fig 2.4The accent box is where the keys come from: never the .tf file.

The provider "aws" block configures the plugin: region = "eu-west-1" for every call, and default_tags, tags the provider adds to every resource that takes them. The run behind this page set no default tags, so its plans show only the queue’s own team tag.

The block holds no keys. The provider finds credentials the way the AWS CLI does: environment variables first, then the profiles in ~/.aws (static keys, an SSO session or a role to assume), then the role of the container or EC2 instance it runs on. On a laptop that is usually an SSO profile; in CI, a role.

Since provider 6.0 every resource also has a region argument, and the plan in chapter 03 shows region = "eu-west-1" on the queue. Set it on one resource and only that resource goes to another Region, so one provider block can serve several.

THE PROVIDER BLOCK: A REGION, DEFAULT TAGS, NO KEYS
# For real AWS. No keys here: the provider takes them from the
# environment, an ~/.aws profile, SSO or the role it runs under.
provider "aws" {
  region = "eu-west-1"

  default_tags {
    tags = {
      app = "receipts"
    }
  }
}

COMMON QUESTIONS

Should .terraform/ go in git?
No. It holds downloaded binaries and modules, and init recreates it. Commit the lock file and ignore the folder.
Can one configuration use two AWS accounts?
Yes: a second provider "aws" block with alias = "audit" and an assume_role, and provider = aws.audit on the resources that belong there.
Does the AWS provider work with OpenTofu?
Yes. OpenTofu is a fork of Terraform 1.5 that runs the same providers from its own registry; this tutorial uses Terraform.

WHAT YOU NOW KNOW

  • A provider is a separate program; core asks it over gRPC, and it alone calls the AWS APIs.
  • Init downloads hashicorp/aws 6.73.0 from the registry and writes the version and hashes to .terraform.lock.hcl, which you commit.
  • The provider block sets eu-west-1 and default tags; credentials come from the AWS CLI’s chain, never from the code.
DEEP DIVE: verbose logs, the plugin cache, protocol versions, several providers, required_version

Verbose logs

TF_LOG=DEBUG (or TRACE) turns on logging for core and every provider. TF_LOG_CORE and TF_LOG_PROVIDER set each side’s level on its own, and TF_LOG_PATH sends the log to a file. At DEBUG the AWS provider logs every request it sends to AWS and every response, which is where a puzzling error usually explains itself.

A PLAN WITH DEBUG LOGS IN A FILE
# Core and provider logs at DEBUG, written to tf.log instead of the terminal
TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform plan

# Only the provider's log, with every AWS request and response
TF_LOG_PROVIDER=DEBUG TF_LOG_PATH=tf.log terraform plan

The plugin cache

TF_PLUGIN_CACHE_DIR points every working directory at one shared folder of downloaded providers, so ten repositories don’t download the same provider ten times. The lock file still checks each package’s hash. terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 records hashes for each platform you name, so a Linux CI runner and a macOS laptop can verify the same lock file.

Protocol versions

Providers speak plugin protocol 5 or 6. Version 6 renames two calls, to GetProviderSchema and ConfigureProvider. hashicorp/aws serves resources written with two libraries, the older SDKv2 and the newer Plugin Framework, combined behind protocol 5. You notice the protocol only when a provider needs a newer Terraform than the one you run.

Several providers

A second provider "aws" block needs an alias. A resource picks it with provider = aws.audit, and a module call passes it with providers = { aws = aws.audit }. Aliases used to be the only way to reach a second Region; in provider 6.x the per-resource region argument replaces most of them, and aliases remain for second accounts.

required_version

required_version = ">= 1.17" makes init and plan stop on an older binary with a clear error. Pin it, so a teammate on Terraform 1.15 can’t run a configuration that relies on something newer, such as the resource-level destroy = false rule that arrived in 1.16 (chapter 08).

ON THE EXAM

“where Terraform records the selected provider versions”
.terraform.lock.hcl
“upgrade providers within the constraints”
terraform init -upgrade
“use two configurations of the same provider”
alias, then provider = aws.<alias>
“enable detailed logs”
TF_LOG, with TF_LOG_PATH for a file

Plan and apply: core works out the steps

You have a configuration and a provider, and nothing exists in AWS yet. Something has to turn four blocks into API calls in an order that works: the role policy can’t name a queue ARN that doesn’t exist yet. It also has to show you those calls before it makes them. How does Terraform decide what to do, and in what order?

STEP 01 / 04

CORE PLANS, THE PROVIDER CALLS AWS

Fig 3.1Follow the accent path from the code to AWS; every call to AWS passes through the provider.

is the terraform binary, version 1.17.2 here. It reads the configuration and its record of earlier runs, works out which actions would make AWS match the code, and has the provider carry them out, resource by resource, over gRPC.

Two commands split that work. terraform plan works out the actions and prints them without changing anything. terraform apply carries them out. From this chapter on, the bucket, the queue and the role exist in AWS, so they join the map.

STEP 02 / 04

PLAN LISTS EVERY CHANGE BEFORE IT HAPPENS

Fig 3.2Read the accent row first: it counts what apply will add, change and destroy.

The first has one entry per resource, each marked with a symbol: + means create. Under each address it lists every argument it will send, and prints every attribute it can’t know yet as (known after apply), such as the queue’s arn and url. This plan was made before policy.tf existed, so it has three entries: the role, the bucket and the queue.

The last line counts the actions: Plan: 3 to add, 0 to change, 0 to destroy. A section headed Changes to Outputs follows, with account and bucket_arn. terraform plan -out=tfplan saves the same actions to a file for a later apply.

THE QUEUE’S ENTRY IN THE FIRST PLAN, AND THE SUMMARY
# aws_sqs_queue.jobs will be created
  + resource "aws_sqs_queue" "jobs" {
      + arn                               = (known after apply)
      + content_based_deduplication       = false
      + deduplication_scope               = (known after apply)
      + delay_seconds                     = 0
      + fifo_queue                        = false
      + fifo_throughput_limit             = (known after apply)
      + id                                = (known after apply)
      + kms_data_key_reuse_period_seconds = (known after apply)
      + max_message_size                  = 262144
      + message_retention_seconds         = 345600
      + name                              = "receipt-jobs"
      + name_prefix                       = (known after apply)
      + policy                            = (known after apply)
      + receive_wait_time_seconds         = 0
      + redrive_allow_policy              = (known after apply)
      + redrive_policy                    = (known after apply)
      + region                            = "eu-west-1"
      + sqs_managed_sse_enabled           = (known after apply)
      + tags                              = {
          + "team" = "payments"
        }
      + tags_all                          = {
          + "team" = "payments"
        }
      + url                               = (known after apply)
      + visibility_timeout_seconds        = 60
    }

Plan: 3 to add, 0 to change, 0 to destroy.
STEP 03 / 04

REFERENCES SET THE ORDER, THE REST RUNS AT ONCE

Fig 3.3The accent edges are the policy’s references; the three boxes above it have none between them and start together.

Before it plans, core builds a from references. The role policy reads aws_iam_role.app.id, aws_s3_bucket.receipts.arn and aws_sqs_queue.jobs.arn, so terraform graph draws three edges from it, and it waits for all three. Nothing among the role, the bucket and the queue references anything else, so no edge joins them.

Core starts every resource whose dependencies are finished, up to 10 operations at a time (the -parallelism flag). In the first apply the role, the queue and the bucket all printed Creating... before any of them finished, and the queue took longest. depends_on adds an edge that no reference implies, such as a wait for something Terraform can’t see.

THE FIRST APPLY: THREE CREATES STARTED TOGETHER
aws_iam_role.app: Creating...
aws_sqs_queue.jobs: Creating...
aws_s3_bucket.receipts: Creating...
aws_iam_role.app: Creation complete after 1s [id=receipts-app]
aws_s3_bucket.receipts: Creation complete after 0s [id=shop-receipts-prod]
aws_sqs_queue.jobs: Still creating... [00m10s elapsed]
aws_sqs_queue.jobs: Still creating... [00m21s elapsed]
aws_sqs_queue.jobs: Creation complete after 26s [id=https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs]
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.
STEP 04 / 04

APPLY CARRIES OUT A SAVED PLAN EXACTLY

Fig 3.4The red hop is a second apply that changed the state, so the saved plan no longer matches it.

terraform apply tfplan runs exactly the saved actions, with no prompt. Plain terraform apply plans again and waits for you to type yes. Either way, core writes each resource to the state, Terraform’s record of what it created (chapter 04), the moment the provider finishes it.

A saved plan is tied to the state it was made from. In the run, a plan to change the queue was saved, and then another apply made the same change first. Applying the saved plan failed with Saved plan is stale, and nothing in AWS was touched.

APPLYING A SAVED PLAN AFTER ANOTHER APPLY
Error: Saved plan is stale

The given plan file can no longer be applied because the state was changed by
another operation after the plan was created.

COMMON QUESTIONS

Does terraform destroy work differently?
No. It is apply with a plan that destroys everything in the state, in reverse dependency order. In the run the role policy went first, then the role, queue and bucket together: Plan: 0 to add, 0 to change, 4 to destroy.
What does -auto-approve skip?
Only the yes prompt. The plan is still made; nobody reads it.
Can I apply just one resource?
-target=aws_sqs_queue.jobs limits the plan to that resource and what it depends on. It exists for recovery, not daily use: the rest of the configuration goes unchecked.

WHAT YOU NOW KNOW

  • Plan reads and reports, apply changes AWS; a saved plan applies exactly what you reviewed or stops as stale.
  • References build a graph: the role policy waits for the role, bucket and queue, while those three start together.
  • Core writes each finished resource to the state as it goes, which is what the next chapter opens.
DEEP DIVE: exit codes for CI, -target and -replace, skipping the refresh, plans as JSON, parallelism

Exit codes for CI

terraform plan -detailed-exitcode returns 0 when there is nothing to do, 1 on an error and 2 when the plan has changes. A scheduled job that runs it and alerts on 2 finds every change made outside Terraform (chapter 06).

-target and -replace

-replace=aws_sqs_queue.jobs plans a replacement of that one resource even though nothing changed, and succeeds the old terraform taint command. -target narrows a plan to some addresses and their dependencies, and every targeted run prints a warning that the result may be incomplete.

Skipping the refresh

A plan normally reads every managed object from AWS first, the refresh that chapter 04 explains. -refresh=false plans from Terraform’s records alone. -minimal-refresh, new in 1.17, reads only the resources that have changes planned: large plans get faster, and drift anywhere else goes unseen.

Plans as JSON

terraform show -json tfplan prints a saved plan as JSON. Each entry in resource_changes has change.actions, such as ["create"] or ["delete", "create"] for a replacement, and policy tools read that list to approve or block a change.

A PLAN FOR CI, THEN THE SAME PLAN AS JSON
# Exit code 0: no changes, 1: an error, 2: changes to apply
terraform plan -out=tfplan -detailed-exitcode

# The planned actions per address, as JSON
terraform show -json tfplan | jq '.resource_changes[] | {address, actions: .change.actions}'

Parallelism

The default of 10 operations at once suits most configurations. When AWS throttles a burst of calls, the provider retries with backoff on its own, so lowering -parallelism rarely helps; it mostly makes a large apply slower.

ON THE EXAM

“the core workflow”
write, plan, apply
“save a plan and apply exactly it”
plan -out=tfplan, then apply tfplan
“remove all managed infrastructure”
terraform destroy, equal to apply -destroy
“declare a dependency Terraform can’t infer”
depends_on
“default number of concurrent operations”
10, set with -parallelism

State: Terraform’s record of what it made

The first apply created three resources: the role, the bucket and the queue. Run terraform plan again and it prints No changes. Your infrastructure matches the configuration. Yet Terraform never tagged the bucket or the queue, and the account could hold a hundred other queues. How does Terraform know which real queue is aws_sqs_queue.jobs, and why can’t it just look in AWS?

STEP 01 / 04

THE STATE SITS BETWEEN THE CODE AND AWS

Fig 4.1The accent box is the state file; core reads it before every plan and writes it during every apply.

The is a JSON file, terraform.tfstate, that Terraform core reads at the start of every plan and writes during every apply. It records what Terraform created, so that the next run can find those objects again.

For now the file sits in the working directory, beside the code. That is the default when the configuration says nothing about where to keep it. Chapter 09 moves it into an S3 bucket so a whole team works from one copy.

STEP 02 / 04

STATE TIES EACH ADDRESS TO ONE REAL ID

Fig 4.2The accent row is the only link between aws_sqs_queue.jobs and one real queue.

For each resource the state records its , the provider that manages it, and every attribute AWS returned after the create. One attribute is the resource ID, the value the provider needs to find the object again: the name for the bucket and the role, and for the queue its URL, https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs.

The first apply left 30 attributes for the bucket, 24 for the queue and 16 for the role. A header comes first: the file format version, 4; the Terraform version, 1.17.2; a serial that rises with every write, 4 after the first apply; and a lineage, an ID fixed when the state was first created.

TERRAFORM.TFSTATE AFTER THE FIRST APPLY, CUT TO THE QUEUE
{
  "version": 4,
  "terraform_version": "1.17.2",
  "serial": 4,
  "lineage": "41a9f545-d589-f427-68eb-57e8286eb546",
  "resources": [
    {
      "mode": "managed",
      "type": "aws_sqs_queue",
      "name": "jobs",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "attributes": {
            "arn": "arn:aws:sqs:eu-west-1:123456789012:receipt-jobs",
            "id": "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs",
            "name": "receipt-jobs",
            "tags": {
              "team": "payments"
            },
            "url": "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs",
            "visibility_timeout_seconds": 60
          }
        }
      ]
    }
  ]
}
STEP 03 / 04

TERRAFORM ONLY LOOKS UP IDS IT ALREADY HAS

Fig 4.3Hop 2 reads only the IDs the state lists; the faint queue in AWS is never read.

A plan has three inputs: the configuration, the state and AWS itself. First core reads the state. Then it runs a : for every resource in the state, the provider reads that one object from AWS by its ID, and the plan prints a Refreshing state... line for each.

Last, core compares the configuration with the refreshed state. Here they match, so the plan ends with No changes. Your infrastructure matches the configuration. Core never lists the account to look for objects. A queue whose ID isn’t in the state is invisible to it, however close its name.

TERRAFORM PLAN RIGHT AFTER THE FIRST APPLY
aws_iam_role.app: Refreshing state... [id=receipts-app]
aws_sqs_queue.jobs: Refreshing state... [id=https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs]
aws_s3_bucket.receipts: Refreshing state... [id=shop-receipts-prod]
No changes. Your infrastructure matches the configuration.
Terraform has compared your real infrastructure against your configuration
and found no differences, so no changes are needed.
STEP 04 / 04

THE STATE STORES SECRETS IN PLAIN TEXT

Fig 4.4The accent cell is the password, readable by anyone who can read the file.

The state keeps every attribute the provider returns, 30 for the bucket alone, and secrets are attributes too. Add the database password as an SSM parameter, /receipts/prod/db-password, of type SecureString, and apply. AWS Systems Manager stores the value encrypted; the state file stores it as plain text.

The plan prints the value as (sensitive value), because the provider marks that argument sensitive, and you can mark your own variables and outputs with sensitive = true. Both hide the value on screen only. The file keeps the real one, which is why chapter 09 shows an argument that never reaches the state.

THE PASSWORD, SEARCHED FOR IN THE STATE FILE
# the password the SSM parameter block sets, searched for in the state
grep -c 'correct-horse-battery-staple' terraform.tfstate
# → 1

COMMON QUESTIONS

Can I delete the state file and start again?
The resources stay in AWS and Terraform forgets them. The next apply plans to create every one of them again, and chapter 06 shows what AWS answers then.
Should the state go in git?
No. It holds secrets, it changes on every apply, and two branches can’t merge it. Chapter 09 puts it in S3.
Does Terraform tag what it owns?
No. Ownership lives only in the state. Tags are yours to add, for example with default_tags in the provider block.

WHAT YOU NOW KNOW

  • The state maps each address to one real ID: aws_sqs_queue.jobs is the queue at …/123456789012/receipt-jobs because the state says so.
  • Every plan refreshes only the IDs in the state, then compares them with the code; nothing else in the account is looked at.
  • The state holds every attribute in plain text, secrets included, so who can read it matters.
DEEP DIVE: the local backend and its backup, serial and lineage, reading the state with commands, editing state by hand, the JSON format

The local backend and its backup

With no backend block, Terraform uses the local backend: the state is terraform.tfstate in the working directory. Before each write it copies the previous version to terraform.tfstate.backup, so one earlier copy always sits beside it. Both files hold every secret the state holds, so list them in .gitignore.

Serial and lineage

The serial rises on every write. It reached 4 after the first apply, not 1, because core saves the state as resources finish. The lineage is a UUID fixed when the state is first created. terraform state push refuses a file with a different lineage or a lower serial unless you add -force, which stops an old copy overwriting a newer one.

Reading the state with commands

terraform state list prints every address in the state, 4 here, because the data source is recorded too. terraform state show prints one resource’s recorded attributes. Both only read. Use them rather than opening the JSON, whose layout is an internal format that can change between versions.

TERRAFORM STATE LIST
data.aws_caller_identity.me
aws_iam_role.app
aws_s3_bucket.receipts
aws_sqs_queue.jobs
TERRAFORM STATE SHOW AWS_SQS_QUEUE.JOBS, CUT DOWN
# aws_sqs_queue.jobs:
resource "aws_sqs_queue" "jobs" {
    arn                               = "arn:aws:sqs:eu-west-1:123456789012:receipt-jobs"
    id                                = "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs"
    name                              = "receipt-jobs"
    url                               = "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs"
    visibility_timeout_seconds        = 60
}

Editing state by hand

terraform state pull prints the current state, and terraform state push uploads a file in its place. They exist for recovery. Editing the JSON comes last: take a backup first, raise the serial by one, then push. Chapter 07’s blocks change what the state tracks through a reviewed plan instead.

The JSON format

"version": 4 is the file format, not the Terraform version, which has its own field. Each entry in resources is one resource block, and its instances list holds one entry per copy, so a block with count or for_each has several. An instance whose create half failed carries "status": "tainted", which chapter 06 explains.

ON THE EXAM

“the purpose of state”
mapping configuration to real objects, tracking metadata, performance
“default backend”
local: terraform.tfstate in the working directory
“list resources in state”
terraform state list
“show one resource’s recorded attributes”
terraform state show <address>
“does sensitive keep a value out of state”
no: it only hides the value in output

Code changes: update, replace or destroy

The receipts stack is live, and the state records three resources. Now the payments team edits the code: a longer timeout on the queue, a new queue name, and one block commented out while someone decides whether it’s still needed. When you edit, rename or comment out a block, what happens to the real resource?

STEP 01 / 05

A PLAN COMPARES THE CODE WITH THE STATE

Fig 5.1The two accent lanes are the plan’s inputs: the code and the state, matched by address.

A plan’s actions come from one comparison. For each , core looks in the configuration and in the refreshed state, and four outcomes are possible. In both and equal: nothing to do. In both and different: update or replace. Only in the configuration: create. Only in the state: destroy.

The name the object has in AWS plays no part in the match. Terraform pairs a block with a state entry by address alone, which explains every surprise in this chapter.

STEP 02 / 05

MOST EDITS UPDATE IN PLACE

Fig 5.2The accent row is the safe one: the same queue, changed where it stands.

Change visibility_timeout_seconds from 60 to 120 and plan. The queue’s entry is marked ~, update in place: the object stays and only the changed line moves, from 60 -> 120. The summary reads Plan: 0 to add, 1 to change, 0 to destroy.

On apply the provider calls SQS’s SetQueueAttributes on the existing queue. The queue keeps its URL and every message waiting in it. Most arguments change this way, and the plan hides the attributes that stay the same, printing only how many there are.

TERRAFORM PLAN AFTER THE TIMEOUT EDIT
# aws_sqs_queue.jobs will be updated in-place
  ~ resource "aws_sqs_queue" "jobs" {
        id                                = "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs"
        name                              = "receipt-jobs"
        tags                              = {
            "team" = "payments"
        }
      ~ visibility_timeout_seconds        = 60 -> 120
        # (19 unchanged attributes hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.
STEP 03 / 05

SOME ARGUMENTS FORCE A REPLACEMENT

Fig 5.3Hop 1 deletes the old queue and its messages before hop 2 creates the new one.

Change the queue’s name to receipt-jobs-eu and the plan changes shape. The entry opens with -/+ destroy and then create replacement, the name line ends # forces replacement, and the summary reads Plan: 1 to add, 0 to change, 1 to destroy.

SQS has no call that renames a queue, so the provider’s schema marks the queue’s name as unchangeable: any edit to it means a . By default Terraform deletes the old queue first, with every message in it, and then creates the new one at a new URL.

TERRAFORM PLAN AFTER THE NAME EDIT
-/+ destroy and then create replacement

  # aws_sqs_queue.jobs must be replaced
      ~ name                              = "receipt-jobs" -> "receipt-jobs-eu" # forces replacement

Plan: 1 to add, 0 to change, 1 to destroy.
STEP 04 / 05

A COMMENTED-OUT BLOCK IS A DELETED BLOCK

Fig 5.4Read left to right: the address is in the state but not in the code, so the plan destroys it.

Comment out the aws_sqs_queue.jobs block and plan. Terraform prints # aws_sqs_queue.jobs will be destroyed, then # (because aws_sqs_queue.jobs is not in configuration), and Plan: 0 to add, 0 to change, 1 to destroy. The state still holds the address, the configuration no longer has it, and an address found only in the state is destroyed.

A comment is not code. Terraform reads only the blocks that are there, so it can’t tell a block you paused from a block you deleted. So yes: commenting out a block destroys its resource on the next apply. Chapter 07’s lets go of a resource without deleting it.

MAIN.TF WITH THE QUEUE BLOCK COMMENTED OUT
resource "aws_s3_bucket" "receipts" {
  bucket = "shop-receipts-prod"
}

# resource "aws_sqs_queue" "jobs" {
#   name                       = "receipt-jobs"
#   tags                       = { team = "payments" }
#   visibility_timeout_seconds = 60
# }
THE PLAN THAT FOLLOWS
# aws_sqs_queue.jobs will be destroyed
  # (because aws_sqs_queue.jobs is not in configuration)
  - resource "aws_sqs_queue" "jobs" {
      - arn                               = "arn:aws:sqs:eu-west-1:123456789012:receipt-jobs" -> null
      - content_based_deduplication       = false -> null
      - delay_seconds                     = 0 -> null
      - fifo_queue                        = false -> null
      - id                                = "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs" -> null
      - kms_data_key_reuse_period_seconds = 300 -> null
      - max_message_size                  = 262144 -> null
      - message_retention_seconds         = 345600 -> null
      - name                              = "receipt-jobs" -> null
      - receive_wait_time_seconds         = 0 -> null
      - region                            = "eu-west-1" -> null
      - sqs_managed_sse_enabled           = true -> null
      - tags                              = {
          - "team" = "payments"
        } -> null
      - tags_all                          = {
          - "team" = "payments"
        } -> null
      - url                               = "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs" -> null
      - visibility_timeout_seconds        = 60 -> null
        # (7 unchanged attributes hidden)
    }

Plan: 0 to add, 0 to change, 1 to destroy.
STEP 05 / 05

RENAMING A BLOCK DESTROYS ONE AND CREATES ANOTHER

Fig 5.5Nothing joins the two addresses, so the plan treats them as two different queues.

Rename the block’s local name from jobs to receipt_jobs and leave the queue’s name alone. The address changes, so the plan finds the old address only in the state and the new one only in the code: one destroy, one create, Plan: 1 to add, 0 to change, 1 to destroy.

Apply it and both actions start at once, since neither depends on the other: a delete and a create for the same queue name. Real SQS refuses a deleted queue’s name for 60 seconds, and provider 6.73.0 retries the create through that wait, so you end with a new, empty queue.

If the create reaches SQS before the delete, SQS returns the existing queue’s URL, and the delete then removes that queue; the next plan creates it again. Either way the messages that were waiting are gone. Chapter 07’s avoids all of it.

TERRAFORM PLAN AFTER THE RENAME, CUT DOWN
# aws_sqs_queue.jobs will be destroyed
  # (because aws_sqs_queue.jobs is not in configuration)
  # aws_sqs_queue.receipt_jobs will be created

Plan: 1 to add, 0 to change, 1 to destroy.
THE FIRST TWO LINES OF THE APPLY
aws_sqs_queue.jobs: Destroying... [id=https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs]
aws_sqs_queue.receipt_jobs: Creating...

COMMON QUESTIONS

Why does commenting out a block sometimes fail the plan instead?
Something else still references it, such as an output or the role policy, so the plan stops with Reference to undeclared resource. Comment out the references too, or use chapter 07’s removed block.
Does terraform plan ever delete anything?
No. Only apply and destroy change AWS; a plan only reports what they would do.
How do I find destroys in a long plan?
Read the Plan: line first, then search for will be destroyed and must be replaced. In CI, read the saved plan as JSON and look for delete actions.

WHAT YOU NOW KNOW

  • Terraform matches code to state by address: equal does nothing, different updates or replaces, missing from the code destroys.
  • Changing visibility_timeout_seconds updates in place; changing the queue’s name forces a replacement, and the old queue’s messages go with it.
  • Commenting out aws_sqs_queue.jobs plans to destroy the queue, and so does renaming its local name without a moved block.
DEEP DIVE: every plan symbol, replace_triggered_by, what forces replacement, reading plans in JSON

Every plan symbol

Three more symbols join the five. <= marks a data source read during apply, because its arguments aren’t known until something else is created. . is forget: the address leaves the state and the object stays, which chapter 07’s removed block prints. ./+ is forget and then create replacement, where a lifecycle rule keeps the old object; chapter 08 shows it.

replace_triggered_by

Some objects must be rebuilt when another one changes. In a lifecycle block, replace_triggered_by = [aws_ssm_parameter.db_password] replaces the resource whenever the password parameter changes, even though none of its own arguments did. The plan says which reference triggered it.

What forces replacement

The provider’s schema decides it, argument by argument, and the resource’s page in the Terraform Registry marks each such argument “Forces new resource”. In this stack: the bucket’s bucket, the queue’s name and fifo_queue, and the role’s name. To replace one object on purpose, run terraform apply -replace=<address>.

Reading plans in JSON

terraform show -json tfplan prints a saved plan as JSON. Each entry in resource_changes has an actions list: ["update"], or ["delete", "create"] for a replacement. A CI job can stop on any delete before the apply step runs, as below.

LIST EVERY DELETE IN A SAVED PLAN
terraform plan -out=tfplan
# every address the saved plan deletes, including replacements
terraform show -json tfplan |
  jq -r '.resource_changes[] | select(.change.actions | index("delete")) | .address'

ERRORS THIS CHAPTER EXPLAINS

Reference to undeclared resource
a block was removed or commented out while an output or another block still refers to it
remove the references in the same change, or use a removed block

ON THE EXAM

“symbol for a resource that will be replaced”
-/+, or +/- with create_before_destroy
“a resource block was removed from configuration”
the next apply destroys the object
“force one resource to be recreated”
terraform apply -replace=<address>

Drift: when AWS changes behind Terraform

The state is only right while Terraform is the one changing these resources, and it rarely is. During an incident someone shortens the queue’s timeout in the console; a cleanup script deletes a queue; a colleague creates the bucket by hand before the code is merged. What does Terraform do when AWS doesn’t match its state, and does apply fail when a resource already exists?

STEP 01 / 05

TERRAFORM ISN’T THE ONLY THING CHANGING AWS

Fig 6.1The accent edge is a change Terraform didn’t make; Terraform sees it only on the next refresh.

The AWS console, the AWS CLI, scripts and other teams’ tools call the same AWS APIs the provider calls, and nothing tells Terraform when they do. It finds out at the next , when it reads each ID in its state. A difference found there is .

What Terraform does next depends on the difference: an attribute changed, an object gone, or an object that exists but was never in the state. Each gets one step below.

STEP 02 / 05

THE NEXT APPLY PUTS THE CODE BACK

Fig 6.2The accent row undoes the console edit; the right panel records it instead.

During an incident someone sets the queue’s timeout to 30 seconds in the console and changes its team tag. The next plan prints ~ visibility_timeout_seconds = 30 -> 60 and ~ "team" = "growth" -> "payments", then Plan: 0 to add, 1 to change, 0 to destroy. The configuration wins: apply sets both back.

To keep the console edit, run terraform plan -refresh-only, a plan that only updates the state. It lists the same change under Note: Objects have changed outside of Terraform and promises no action to undo it. Applying it writes the new values into the state; then you edit the code to match, or the next plan reverts them.

TERRAFORM PLAN AFTER THE CONSOLE EDIT
# aws_sqs_queue.jobs will be updated in-place
  ~ resource "aws_sqs_queue" "jobs" {
        id                                = "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs"
        name                              = "receipt-jobs"
      ~ tags                              = {
          ~ "team" = "growth" -> "payments"
        }
      ~ tags_all                          = {
          ~ "team" = "growth" -> "payments"
        }
      ~ visibility_timeout_seconds        = 30 -> 60
        # (18 unchanged attributes hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.
TERRAFORM PLAN -REFRESH-ONLY, THE SAME EDIT
Note: Objects have changed outside of Terraform

Terraform detected the following changes made outside of Terraform since the
last "terraform apply" which may have affected this plan:

  # aws_sqs_queue.jobs has changed
  ~ resource "aws_sqs_queue" "jobs" {
        id                                = "https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs"
        name                              = "receipt-jobs"
      ~ tags                              = {
          ~ "team" = "payments" -> "growth"
        }
      ~ tags_all                          = {
          ~ "team" = "payments" -> "growth"
        }
      ~ visibility_timeout_seconds        = 60 -> 30
        # (18 unchanged attributes hidden)
    }

This is a refresh-only plan, so Terraform will not take any actions to undo
these. If you were expecting these changes then you can apply this plan to
record the updated values in the Terraform state without changing any remote
objects.
STEP 03 / 05

A RESOURCE DELETED OUTSIDE IS CREATED AGAIN

Fig 6.3Hop 2 finds nothing at the recorded ID, so hop 3 plans the queue as new.

Delete the queue with the CLI and plan. The refresh asks for the URL in the state, AWS answers that no such queue exists, and the address drops out of the refreshed state. It is now only in the code, so the plan prints # aws_sqs_queue.jobs will be created and Plan: 1 to add, 0 to change, 0 to destroy.

Apply makes a new queue with the same name. A queue URL is built from the account and the name, so even the URL matches, but the queue is new and empty. If the apply comes within 60 seconds of the delete, the provider retries until SQS releases the name.

TERRAFORM PLAN AFTER THE DELETE
# aws_sqs_queue.jobs will be created

Plan: 1 to add, 0 to change, 0 to destroy.
STEP 04 / 05

AN EXISTING RESOURCE FAILS ONLY IF AWS REFUSES A DUPLICATE

Fig 6.4The accent row is the dangerous one: no error, and a second instance.

This is the other question people ask most: does apply fail when the resource already exists? With nothing in the state, the plan says create, because Terraform never checks AWS for an object it has no ID for. What happens next is each AWS API’s own rule.

Lose the state file and apply the same configuration: Plan: 4 to add, 0 to change, 0 to destroy. The bucket fails with BucketAlreadyOwnedByYou and the role with EntityAlreadyExists, both HTTP 409. The queue prints Creation complete with the same URL, because SQS answers an identical CreateQueue with the existing queue, and the new state now claims it.

An EC2 instance has no unique name, so it is simply launched again: 2 instances tagged receipt-worker afterwards. A queue someone made by hand with other settings fails with QueueAlreadyExists, because the provider sends every attribute and the tag, so the request isn’t identical.

APPLY FROM AN EMPTY STATE, CUT TO THE RESULTS
Plan: 4 to add, 0 to change, 0 to destroy.

aws_instance.worker: Creation complete after 10s [id=i-bc372153d07367328]
aws_sqs_queue.jobs: Creation complete after 25s [id=https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs]
Error: creating S3 Bucket (shop-receipts-prod): operation error S3: CreateBucket, https response error StatusCode: 409, RequestID: …, HostID: …, BucketAlreadyOwnedByYou: Your previous request to create the named bucket succeeded and you already own it.
Error: creating IAM Role (receipts-app): operation error IAM: CreateRole, https response error StatusCode: 409, RequestID: …, EntityAlreadyExists: Role with name receipts-app already exists.
APPLY AFTER A QUEUE WAS MADE BY HAND WITH OTHER SETTINGS
Error: creating SQS Queue (receipt-jobs): operation error SQS: CreateQueue, https response error StatusCode: 400, RequestID: …, QueueAlreadyExists: The specified queue already exists.
STEP 05 / 05

A FAILED APPLY KEEPS WHAT IT FINISHED

Fig 6.5Two creates finished and are in the state; the failed one isn’t, so the next apply tries only that one.

Terraform doesn’t roll back. In the run where the bucket already existed, the role and the queue were created before the bucket failed, and terraform state list afterwards shows exactly those two, plus the data source. Fix the cause and apply again: the next plan creates only the bucket.

A create can also succeed and then fail in a later step of the same resource, such as a provisioner, a command Terraform runs after making the object. The object exists, so the state keeps it, marked , and the next plan prints # aws_s3_bucket.receipts is tainted, so must be replaced and Plan: 1 to add, 0 to change, 1 to destroy.

TERRAFORM STATE LIST AFTER THE FAILED APPLY
data.aws_caller_identity.me
aws_iam_role.app
aws_sqs_queue.jobs
A FAILED PROVISIONER, THEN THE NEXT PLAN
Error: local-exec provisioner error

  # aws_s3_bucket.receipts is tainted, so must be replaced

Plan: 1 to add, 0 to change, 1 to destroy.

COMMON QUESTIONS

Does Terraform scan my account for things it doesn’t manage?
No. It reads only the IDs in its state. terraform query with list blocks, in 1.14 and later, can list candidates to import (chapter 07).
How do I catch drift before an apply does?
Run terraform plan -detailed-exitcode on a schedule. Exit code 2 means the plan has changes: someone changed AWS, or merged code nobody applied.
Can Terraform leave alone an attribute another tool manages?
Yes: lifecycle { ignore_changes = [tags["team"]] } on the resource, which chapter 08 covers.

WHAT YOU NOW KNOW

  • Terraform sees console edits only at the next refresh, and the next apply sets the timeout back from 30 to 60 seconds.
  • A queue deleted outside Terraform is planned as a new create; -refresh-only records drift instead of undoing it.
  • Without an ID in the state, apply fails only where AWS refuses duplicates: the bucket errors, an identical queue is adopted, an instance doubles.
DEEP DIVE: refresh-only versus the old refresh command, drift checks in CI, why each API answers differently, S3 in us-east-1, tainted objects

Refresh-only versus the old refresh command

terraform refresh wrote whatever it found straight into the state, with no review. Point it at the wrong Region and every object reads as missing, so it empties the state. It is deprecated. terraform apply -refresh-only shows the same changes as a plan first and writes them only after you approve.

Drift checks in CI

A nightly job runs one plan per state and opens an issue when the exit code is 2. It passes -lock=false so it never blocks a real apply, which is safe only because this plan is never applied.

A NIGHTLY DRIFT CHECK
# 0 = no changes, 1 = error, 2 = changes: someone changed AWS, or code wasn't applied
terraform plan -detailed-exitcode -lock=false -input=false
echo "exit code $?"

Why each API answers differently

Names are unique at different scopes: an S3 bucket name across every AWS account, an IAM role name within one account. Some creates are idempotent: SQS returns the existing queue for identical attributes. Some resources have no unique name at all, such as an EC2 instance, whose client token only makes one request safe to retry.

The provider passes AWS’s answer through, and Terraform core adds no check of its own. That is why one apply can show an error, a silent adoption and a duplicate side by side.

S3 in us-east-1

In us-east-1, S3 answers CreateBucket for a bucket you already own with 200 OK, and resets its access control list. So provider 6.73.0 first calls HeadBucket there, and only there, and fails with BucketAlreadyExists if the bucket is found. In every other Region it relies on S3’s own 409. The check is in the provider’s internal/service/s3/bucket.go.

Tainted objects

A tainted object carries "status": "tainted" in the state, and every plan replaces it until it is gone. terraform untaint clears the mark when you know the object is fine. terraform apply -replace=<address> asks for the same replacement on purpose, and replaced the deprecated terraform taint.

ERRORS THIS CHAPTER EXPLAINS

BucketAlreadyOwnedByYou
the bucket exists in your account but not in the state
adopt it with an import block (chapter 07), or delete it if nothing needs it
EntityAlreadyExists
an IAM role with that name already exists in the account
import it, or pick another name
QueueAlreadyExists
a queue with that name exists with different attributes or tags
import it, or match its settings in the code
# aws_s3_bucket.receipts is tainted, so must be replaced
the object was created, then a later step of its create failed
fix the cause and apply, or clear the mark with terraform untaint

ON THE EXAM

“record changes made outside Terraform without changing infrastructure”
terraform apply -refresh-only
“what happens to a manual change on the next apply”
Terraform changes it back to match the configuration
“deprecated command that updated state from real infrastructure”
terraform refresh

Import, moved, removed: editing state through a plan

Chapters 05 and 06 left three problems. The bucket shop-receipts-prod exists in AWS but not in the state, so apply fails with a 409. Renaming the queue’s block plans a destroy and a create. Commenting the block out, to stop managing the queue, deletes it. Each fix has to change what the state records and leave AWS alone, and each should be reviewed like any other change. How do you change what Terraform tracks without touching the real resource?

STEP 01 / 04

THREE BLOCKS EDIT THE STATE, NOT AWS

Fig 7.1The accent box sits in the configuration, whose only lane runs to core, never straight to AWS.

An , a and a sit in .tf files beside the resource blocks. None of them describes an object in AWS. Each tells Terraform how to change its state: adopt an object that exists, record that an address changed, or forget an object.

Because they are code, they go through the same plan as every other change, and a reviewer sees them in the pull request before anything is written.

STEP 02 / 04

AN IMPORT BLOCK ADOPTS WHAT ALREADY EXISTS

Fig 7.2Hop 3 is the only write, and it goes to the state; AWS is only read.

An import block names an address and the ID of an object that already exists: to = aws_s3_bucket.receipts and id = "shop-receipts-prod". The plan reads the bucket by that ID, compares it with the resource block and prints Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.. Apply writes the address and the ID into the state: Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed..

The ID’s format depends on the resource type, and each resource’s documentation page lists it at the bottom: a bucket name for a bucket, a queue URL for a queue, a role name for a role. This fixes chapter 06’s failed apply. The bucket that answered 409 is now in the state, and the next plan prints No changes. Your infrastructure matches the configuration.

IMPORTS.TF: ADOPT THE BUCKET
import {
  to = aws_s3_bucket.receipts
  id = "shop-receipts-prod"
}
PLAN, APPLY, THEN PLAN AGAIN
aws_s3_bucket.receipts: Preparing import... [id=shop-receipts-prod]

Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.

aws_s3_bucket.receipts: Importing... [id=shop-receipts-prod]
aws_s3_bucket.receipts: Import complete [id=shop-receipts-prod]
Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.

No changes. Your infrastructure matches the configuration.
STEP 03 / 04

A MOVED BLOCK RENAMES AN ADDRESS

Fig 7.3The accent panel is the same rename with one moved block: nothing is created or destroyed.

A moved block records that an address changed: from = aws_sqs_queue.jobs, to = aws_sqs_queue.receipt_jobs. Keep the renamed resource block and add the moved block beside it. The plan then moves the queue’s entry in the state and prints # aws_sqs_queue.jobs has moved to aws_sqs_queue.receipt_jobs.

Chapter 05’s rename on its own planned Plan: 1 to add, 0 to change, 1 to destroy. With the moved block the plan is Plan: 0 to add, 0 to change, 0 to destroy. The queue keeps its URL and the messages in it. The same block also covers a resource moving into a module, which chapter 10 needs.

MAIN.TF: RECORD THE RENAME
moved {
  from = aws_sqs_queue.jobs
  to   = aws_sqs_queue.receipt_jobs
}
TERRAFORM PLAN
# aws_sqs_queue.jobs has moved to aws_sqs_queue.receipt_jobs

Plan: 0 to add, 0 to change, 0 to destroy.
STEP 04 / 04

A REMOVED BLOCK FORGETS A RESOURCE AND KEEPS IT

Fig 7.4Same block gone from the code; the accent side leaves the queue running in AWS.

Delete the queue’s resource block and put a removed block in its place: from = aws_sqs_queue.jobs with lifecycle { destroy = false }. The plan marks the queue with a dot, . resource "aws_sqs_queue" "jobs" {, prints Plan: 0 to add, 0 to change, 0 to destroy. and warns Some objects will no longer be managed by Terraform.

After apply, terraform state list no longer lists the queue, and SQS still lists receipt-jobs. This is the answer to chapter 05’s commented-out block: the code stops describing the queue, and the queue keeps running for whoever manages it next.

MAIN.TF: THE QUEUE’S BLOCK, REPLACED
removed {
  from = aws_sqs_queue.jobs
  lifecycle {
    destroy = false
  }
}
TERRAFORM PLAN
. resource "aws_sqs_queue" "jobs" {

Plan: 0 to add, 0 to change, 0 to destroy.

Warning: Some objects will no longer be managed by Terraform

If you apply this plan, Terraform will discard its tracking information for
the following objects, but it will not delete them:
 - aws_sqs_queue.jobs

After applying this plan, Terraform will no longer manage these objects. You
will need to import them into Terraform to manage them again.

COMMON QUESTIONS

Can I delete an import or removed block after applying it?
Yes. Once applied, it has nothing left to do. Keep moved blocks in shared modules, so a caller still on an older version moves cleanly when it upgrades.
Can Terraform write the resource block for an import?
Yes: terraform plan -generate-config-out=generated.tf writes a block from the real object’s attributes. Trim it before you commit it.
Can I import into a module?
Yes. Prefix the address with the module’s name, as in to = module.jobs.aws_sqs_queue.this.

WHAT YOU NOW KNOW

  • An import block adopted shop-receipts-prod: the plan said 1 to import, and the plan after the apply said No changes.
  • A moved block turned chapter 05’s rename from 1 to add and 1 to destroy into nothing added, changed or destroyed.
  • A removed block with destroy = false dropped the queue from the state and left receipt-jobs running in SQS.
DEEP DIVE: generating configuration, importing many with for_each, finding candidates with terraform query, moved across modules and types, the CLI commands that skip the plan

Generating configuration

With an import block in place, terraform plan -generate-config-out=generated.tf writes a resource block for each import that has none, from the real object’s attributes. It writes every argument, defaults included. Delete what you don’t mean to own before you commit the file, or the next change to a default shows up as a change to your code.

Importing many with for_each

Since Terraform 1.7 an import block takes for_each, so one block can adopt a queue per Region: for_each = toset(["eu", "us"]), to = aws_sqs_queue.by_key[each.key], and an id built from the key. Each key becomes one import in the plan, with its own address.

Finding candidates with terraform query

Terraform 1.14 added list blocks in .tfquery.hcl files and the terraform query command. A list block asks the provider for every existing object of one type, such as every SQS queue in the account, and the command can write an import block for each one it finds.

Moved across modules and types

A moved block works into and out of modules, and between instance keys, such as from aws_sqs_queue.jobs[0] to aws_sqs_queue.jobs["eu"] when count becomes for_each. A move between two resource types works only where the provider supports that pair; otherwise the plan reports an error and moves nothing.

The CLI commands that skip the plan

terraform import, terraform state mv and terraform state rm make the same three edits as the blocks, but write the state at once: no plan, no review, nothing in git. Keep them for one-off repairs, and save a copy first.

THE SAME EDITS, WRITTEN AT ONCE
# keep a copy before any state command
terraform state pull > backup.tfstate

# adopt the bucket: what the import block does
terraform import aws_s3_bucket.receipts shop-receipts-prod

# rename the address: what the moved block does
terraform state mv aws_sqs_queue.jobs aws_sqs_queue.receipt_jobs

# forget the queue and leave it in SQS: removed with destroy = false
terraform state rm aws_sqs_queue.receipt_jobs

If you edit a pulled copy and upload it with terraform state push, its serial, the state’s version counter, must be higher than the stored one, or the push is refused.

Only the block rows reach the accent column: a command never shows up in a plan.

ON THE EXAM

“bring an existing resource under management”
an import block, or terraform import
“rename a resource without destroying it”
a moved block, or terraform state mv
“stop managing a resource without destroying it”
a removed block with destroy = false, or terraform state rm

Lifecycle rules: limits on what a plan may do

Terraform deletes a resource whenever the code and the state say so, and chapter 05 showed how easily they say so: a commented-out block, a rename, a forced replacement. The bucket shop-receipts-prod holds every receipt the shop has issued. Chapter 07’s blocks repair a mistake once you spot it in a plan; nothing so far stops a plan that deletes. What stops Terraform deleting a resource you can’t lose, and where does the protection end?

STEP 01 / 05

A LIFECYCLE RULE BELONGS TO ONE BLOCK

Fig 8.1The accent box sits inside the configuration: each rule belongs to one resource block.

A sits inside one resource block and limits what any plan may do to that resource. It can refuse to destroy it, forget it instead of destroying it, create its replacement first, or ignore changes to some of its attributes.

Its values must be literals such as true. Terraform reads them before it evaluates any expression, so a variable or a reference there is an error.

STEP 02 / 05

PREVENT_DESTROY FAILS THE WHOLE PLAN

Fig 8.2The plan stops at the red ✗ on hop 3: the whole run fails, not only the bucket.

Add prevent_destroy = true to the bucket’s lifecycle block and run terraform plan -destroy. The plan lists all three resources for destruction and then stops with Error: Instance cannot be destroyed. The command exits with code 1, and the error names the bucket, the rule, and two ways out: remove the rule, or narrow the plan with -target.

Any plan that would destroy or replace the bucket fails the same way, whatever else it holds. Nothing in that plan is applied, so the queue and the role stay too. Deleting the bucket on purpose takes two reviewed changes: one that removes the rule, then one that removes the bucket.

MAIN.TF: THE BUCKET, PROTECTED
resource "aws_s3_bucket" "receipts" {
  bucket = "shop-receipts-prod"
  lifecycle {
    prevent_destroy = true
  }
}
TERRAFORM PLAN -DESTROY
Error: Instance cannot be destroyed

  on main.tf line 3:
   3: resource "aws_s3_bucket" "receipts" {

Resource aws_s3_bucket.receipts has lifecycle.prevent_destroy set, but the
plan calls for this resource to be destroyed. To avoid this error and
continue with the plan, either disable lifecycle.prevent_destroy or reduce
the scope of the plan using the -target option.
STEP 03 / 05

A RULE IN THE BLOCK LEAVES WITH THE BLOCK

Fig 8.3The plan no longer sees the rule; only S3’s own check at hop 3 saved the bucket.

Now comment out the protected bucket’s block. The rule was inside it, so it goes too, and the plan is a plain destroy: # (because aws_s3_bucket.receipts is not in configuration), then Plan: 0 to add, 0 to change, 1 to destroy. No error, no warning.

Apply got as far as aws_s3_bucket.receipts: Destroying... [id=shop-receipts-prod]. S3 stopped it with BucketNotEmpty (409), because the bucket held one receipt, 2026/11/r-1001.pdf, and force_destroy, the argument that lets Terraform empty a bucket before deleting it, was false. An empty bucket would have been deleted.

TERRAFORM APPLY, BLOCK COMMENTED OUT
# aws_s3_bucket.receipts will be destroyed
  # (because aws_s3_bucket.receipts is not in configuration)

Plan: 0 to add, 0 to change, 1 to destroy.

aws_s3_bucket.receipts: Destroying... [id=shop-receipts-prod]
Error: deleting S3 Bucket (shop-receipts-prod): operation error S3: DeleteBucket, https response error StatusCode: 409, RequestID: …, HostID: …, api error BucketNotEmpty: The bucket you tried to delete is not empty
STEP 04 / 05

DESTROY = FALSE FORGETS INSTEAD OF DELETING

Fig 8.4The accent row leaves the old queue running; the red row shows the rule doesn’t help once the block is gone.

Terraform 1.16 added destroy = false as a rule on the resource itself. On the queue, terraform plan -destroy prints # aws_sqs_queue.jobs will no longer be managed by Terraform, but will not be destroyed and # (destroy = false is set in the configuration). Instead of deleting the queue, apply would drop it from the state and leave it in SQS.

A changes too. Rename the queue to receipt-jobs-v2, which SQS can’t do in place, and the plan prints ./+ forget and then create replacement and Plan: 1 to add, 0 to change, 0 to destroy. The new queue is created, and the old one keeps running, tracked by nothing. Comment the block out, though, and the plan reads Plan: 0 to add, 0 to change, 1 to destroy. The rule left with the block, as in step 3.

MAIN.TF: THE QUEUE, FORGOTTEN ON DESTROY
resource "aws_sqs_queue" "jobs" {
  name                       = "receipt-jobs"
  tags                       = { team = "payments" }
  visibility_timeout_seconds = 60
  lifecycle {
    destroy = false
  }
}
PLAN -DESTROY, THEN A FORCED REPLACEMENT
# aws_sqs_queue.jobs will no longer be managed by Terraform, but will not be destroyed
 # (destroy = false is set in the configuration)

./+ forget and then create replacement

 # aws_sqs_queue.jobs must be replaced, but the existing object will not be destroyed
 # (destroy = false is set in the configuration)

Plan: 1 to add, 0 to change, 0 to destroy.
STEP 05 / 05

CREATE_BEFORE_DESTROY NEEDS A NAME THAT CAN EXIST TWICE

Fig 8.5With a fixed name both steps hit one queue; the accent timeline has two real queues for a moment.

By default a replacement deletes the old object first. create_before_destroy = true reverses the order, and the plan says +/- create replacement and then destroy, so something exists throughout. That only works when the new object can exist beside the old one.

With the fixed name receipt-jobs, terraform apply -replace=aws_sqs_queue.jobs sent a CreateQueue identical to the existing queue’s, and SQS answers that with the existing queue’s URL. The destroy of the deposed object, the old copy the state keeps until the swap ends, then deleted that same queue. Apply printed Apply complete! Resources: 1 added, 0 changed, 1 destroyed. and the next plan Plan: 1 to add, 0 to change, 0 to destroy.

With name_prefix = "receipt-jobs-", SQS gets a generated name; the run’s queue was receipt-jobs-7bcb4ba2b1e13679ce71dac471. A replacement gets a new suffix, so two queues exist for a moment, and then the old one is deleted.

MAIN.TF: A NAME THAT CAN EXIST TWICE
resource "aws_sqs_queue" "jobs" {
  name_prefix                = "receipt-jobs-"
  tags                       = { team = "payments" }
  visibility_timeout_seconds = 60
  lifecycle {
    create_before_destroy = true
  }
}
WITH A FIXED NAME: APPLY -REPLACE, THEN THE NEXT PLAN
+/- create replacement and then destroy

  # aws_sqs_queue.jobs will be replaced, as requested

aws_sqs_queue.jobs: Creation complete after 25s [id=https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs]
aws_sqs_queue.jobs (deposed object b8d9d156): Destroying... [id=https://sqs.eu-west-1.amazonaws.com/123456789012/receipt-jobs]
aws_sqs_queue.jobs: Destruction complete after 42s
Apply complete! Resources: 1 added, 0 changed, 1 destroyed.

  # aws_sqs_queue.jobs will be created

Plan: 1 to add, 0 to change, 0 to destroy.

COMMON QUESTIONS

Does prevent_destroy stop someone deleting the bucket in the console?
No. It only stops Terraform plans. Protection against everyone lives in AWS: S3 Object Lock, a bucket policy that denies s3:DeleteBucket, or deletion protection on a database.
Can a variable switch prevent_destroy on in prod only?
No: lifecycle takes literal values only. Give each environment its own configuration, and write the rule into the production one.
How do I let Terraform ignore a tag another tool sets?
lifecycle { ignore_changes = [tags["team"]] }. The plan then never reverts that tag, as chapter 06’s drift plan would.

WHAT YOU NOW KNOW

  • prevent_destroy failed the destroy plan with Instance cannot be destroyed, and nothing in that plan ran.
  • Commented out, the protected bucket was planned for destruction anyway; only S3’s BucketNotEmpty stopped the delete of shop-receipts-prod.
  • destroy = false forgets instead of deleting. create_before_destroy with a fixed queue name deleted the only queue; name_prefix replaces it cleanly.
DEEP DIVE: ignore_changes, replace_triggered_by, preconditions and postconditions, protection inside AWS, destroy = false or removed

ignore_changes

ignore_changes takes a list of attributes, such as [tags["team"]], or the keyword all. A difference in those attributes is neither shown as a change nor reverted. The value is still sent when the resource is created, so the code sets the starting point and another tool owns it from then on.

replace_triggered_by

replace_triggered_by replaces a resource whenever another resource, or one of its attributes, changes or is replaced. A render worker that must restart on a new queue would list aws_sqs_queue.jobs there. It takes references to managed resources only, not variables, so a value from elsewhere goes through a terraform_data resource first.

Preconditions and postconditions

A precondition block inside lifecycle holds a condition and an error_message. Terraform checks it before it plans the resource’s change, or during apply if a value isn’t known until then. A postcondition is checked after the provider answers, so it can test what AWS returned, such as an ARN or a Region.

Protection inside AWS

A lifecycle rule only binds Terraform, and only while its block exists. Protection that holds against every tool lives in AWS: S3 versioning and Object Lock, deletion_protection on RDS and DynamoDB, EC2 termination protection, or a service control policy that denies deletes in the production account. Terraform hits those too, and fails.

destroy = false or removed

The resource rule, from 1.16, applies to every destroy and every replacement while the block exists. The removed block, from 1.7, is a one-time instruction written after the block is gone. Use the rule for an object Terraform creates but must never delete; use the removed block to hand an object over. Terraform 1.17.2 fixed a dependency cycle when a provider references a resource with destroy = false (#39507).

ON THE EXAM

“make a replacement create the new object first”
lifecycle { create_before_destroy = true }
“reject any plan that would destroy a resource”
lifecycle { prevent_destroy = true }
“stop Terraform reverting an attribute changed elsewhere”
lifecycle { ignore_changes = [...] }
“validate an assumption before apply”
a precondition block

Remote state: one shared, locked copy in S3

So far terraform.tfstate sits on one laptop. A teammate who clones the repository has no state, so their first apply would try to create everything again, and chapter 06 showed how that ends. Two people applying at once would each write their own version of the file. And the file holds the database password in plain text (chapter 04). Where should the state live so a team and CI can share it safely?

STEP 01 / 04

THE STATE MOVES INTO AN S3 BUCKET

Fig 9.1The accent bucket now holds the state; every laptop and CI runner reads the same object.

A decides where Terraform keeps the state. Until now it was the default local backend: one terraform.tfstate file beside the code. With the s3 backend the state is one object, receipts/prod.tfstate, in the bucket shop-tfstate, and every run on every machine reads and writes that object.

The bucket must exist before terraform init runs, so teams create it once, by hand or from a small separate configuration, and keep it out of the code it stores state for.

STEP 02 / 04

INIT COPIES THE LOCAL STATE UP ONCE

Fig 9.2Hops 1 and 2 copy the local file up once; after that the S3 object is the only state.

The backend is set in a terraform block (below), and encrypt = true has S3 encrypt the object at rest. Run terraform init after adding it. If a local state already exists, terraform init -migrate-state copies it into the bucket, and from then on the S3 object is the state.

Turn on versioning for the state bucket, so S3 keeps every earlier version of the object and a damaged state can be rolled back. A backend block can’t read variables: its values are literals, or come from a file passed with -backend-config.

BACKEND.TF
# For real AWS: credentials come from the usual chain, never from this block.
terraform {
  backend "s3" {
    bucket       = "shop-tfstate"
    key          = "receipts/prod.tfstate"
    region       = "eu-west-1"
    use_lockfile = true # a .tflock object beside the state
    encrypt      = true
  }
}
TERRAFORM INIT, AFTER ADDING THE BLOCK
Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.
STEP 03 / 04

A LOCK FILE STOPS TWO RUNS AT ONCE

Fig 9.3Hop 2 fails because the lock object already exists; run B waits or gives up.

With use_lockfile = true, every plan and apply first writes a : the object receipts/prod.tfstate.tflock, created with an S3 conditional write that succeeds only if the object doesn’t exist yet. Only one run can create it. Its body (below) records the lock ID, the operation, who holds it, the Terraform version and the time.

In the run, a second plan started while an apply held the lock. Its write got 412 PreconditionFailed, and Terraform stopped with Error acquiring the state lock and the holder’s lock info. By default it fails at once; -lock-timeout=5m makes it retry for up to five minutes. When the apply ended, the lock object was gone.

Native S3 locking is generally available since Terraform 1.11. The older lock in a DynamoDB table, set with dynamodb_table, is deprecated.

THE .TFLOCK OBJECT WHILE THE APPLY RAN
{
  "ID": "c9c9573c-1a93-5732-054b-d1707ba969e7",
  "Operation": "OperationTypeApply",
  "Info": "",
  "Who": "payments-ci@runner",
  "Version": "1.17.2",
  "Created": "2026-11-20T10:23:07.534387Z",
  "Path": "shop-tfstate/receipts/prod.tfstate"
}
THE SECOND RUN
Error: Error acquiring the state lock

Error message: operation error S3: PutObject, https response error
StatusCode: 412, RequestID: …, HostID: …,
api error PreconditionFailed: At least one of the pre-conditions you
specified did not hold
Lock Info:
  ID:        c9c9573c-1a93-5732-054b-d1707ba969e7
  Path:      shop-tfstate/receipts/prod.tfstate
  Operation: OperationTypeApply
  Who:       payments-ci@runner
  Version:   1.17.2
  Created:   2026-11-20 10:23:07.534387 +0000 UTC
  Info:


Terraform acquires a state lock to protect the state from being written
by multiple users at the same time. Please resolve the issue above and try
again. For most commands, you can disable locking with the "-lock=false"
flag, but this is not recommended.
STEP 04 / 04

WRITE-ONLY ARGUMENTS KEEP SECRETS OUT OF STATE

Fig 9.4The accent row is what the state keeps now: a version number, not the password.

Chapter 04 found the database password, correct-horse-battery-staple, in the state as plain text. A fixes that: Terraform passes value_wo to the provider, which sends it to SSM, and neither the plan nor the state stores it. Write-only arguments need Terraform 1.11 or later; this run used 1.17.2.

After the switch the plan showed + value_wo_version = 1 and no password, and grep found 0 copies of the password in the state, against 1 before. Terraform can’t compare a value it never keeps, so it sends a new one only when you raise value_wo_version.

SECRET.TF
resource "aws_ssm_parameter" "db_password" {
  name = "/receipts/prod/db-password"
  type = "SecureString"

  # sent to SSM when the version changes; never saved in the state
  value_wo         = "correct-horse-battery-staple"
  value_wo_version = 1
}
TERRAFORM PLAN, AFTER THE SWITCH
# aws_ssm_parameter.db_password will be updated in-place
  ~ resource "aws_ssm_parameter" "db_password" {
      ~ has_value_wo     = false -> (known after apply)
        id               = "/receipts/prod/db-password"
        name             = "/receipts/prod/db-password"
        tags             = {}
      + value_wo_version = 1
        # (12 unchanged attributes hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.
THE PASSWORD IN THE STATE, BEFORE AND AFTER
# after the apply with value = "correct-horse-battery-staple"
grep -c 'correct-horse-battery-staple' terraform.tfstate
# → 1

# after the apply with value_wo
grep -c 'correct-horse-battery-staple' terraform.tfstate
# → 0

COMMON QUESTIONS

Who can read the state now?
Anyone with s3:GetObject on shop-tfstate/receipts/prod.tfstate. Give CI and the payments team access to that key and nobody else: the state still holds every attribute AWS returned.
What about HCP Terraform?
Its cloud block replaces the backend block: HashiCorp stores and locks the state and runs plans on its own workers. The state works the same way.
How do staging and prod stay apart?
Each gets its own state: a different key, such as receipts/staging.tfstate, a different folder, or a workspace (see the deep dive).

WHAT YOU NOW KNOW

  • The S3 backend keeps one state object, receipts/prod.tfstate, that every laptop and CI runner reads and writes.
  • use_lockfile = true creates receipts/prod.tfstate.tflock during a run, and a second run’s write fails with 412.
  • value_wo sent the password to SSM and left 0 copies in the state, where value had left 1.
DEEP DIVE: workspaces, one state per environment, partial backend configuration, recovering an old state, HCP Terraform, reading another stack’s outputs

Workspaces

terraform workspace new staging makes a second, empty state for the same code. The S3 backend keeps it under a prefix, env:/staging/receipts/prod.tfstate, beside the default workspace’s receipts/prod.tfstate. Expressions read the current name as terraform.workspace. Workspaces suit short-lived copies, such as a test stack per branch. For prod and staging they are risky: the code is identical, so nothing on screen says which state a plan will touch.

One state per environment

The safer layout is a folder per environment, such as envs/prod/ and envs/staging/, each with its own backend key and each calling the same module (chapter 10). Smaller states also plan faster, since refresh reads fewer objects, and they limit what one mistake can destroy.

The accent column is the safer layout: each environment’s state is reached only from its own folder.

Partial backend configuration

A backend block is read before variables exist, so it can’t use them. Leave the values that change out of the block and pass them at init: terraform init -backend-config=prod.s3.tfbackend, where the file holds lines such as key = "receipts/prod.tfstate". One code folder can then point at different state objects without editing the block.

Recovering an old state

With versioning on, every write of receipts/prod.tfstate leaves the previous version in the bucket. To roll back, download the earlier version and upload it with terraform state push. Terraform refuses a state whose lineage, the ID every copy of one state shares, differs, or whose serial is lower than the current one. -force skips both checks, so compare the lineage yourself first.

HCP Terraform

HCP Terraform replaces the backend with a cloud block. It stores and locks the state, runs plans and applies on its own workers, groups workspaces into projects, and can check every plan against policies before it is applied. A workspace there is closer to a folder per environment than to a CLI workspace: each has its own variables, permissions and state.

Reading another stack’s outputs

data "terraform_remote_state" reads another configuration’s outputs straight from its state object, so the reader needs access to that whole state, secrets included. Publishing the one value to SSM Parameter Store and reading it with an aws_ssm_parameter data source shares only that value.

ON THE EXAM

“prevent two concurrent writes to state”
state locking; with S3, use_lockfile = true
“release a stuck lock”
terraform force-unlock <ID>
“move local state into a new backend”
add the backend block, then terraform init -migrate-state
“keep a secret out of state”
a write-only argument or an ephemeral resource
“default backend”
local: terraform.tfstate in the working directory
“several states for one configuration”
CLI workspaces
“HCP Terraform’s grouping of workspaces”
projects

Modules and many copies: count, for_each and module blocks

The shop now needs a receipt queue in three Regions, eu, us and ap, and the same stack again for staging. Copying blocks works until the copies drift apart. Terraform has two tools for this: many instances of one block, and modules, folders of blocks you call like functions. How do you make many copies, and why does the way you number them decide what gets destroyed?

STEP 01 / 04

A MODULE IS A FOLDER YOU CALL

Fig 10.1The accent box is a module call; its resources live under the module.jobs prefix.

A is a folder of .tf files with input variables and outputs. The root module, the folder you run terraform in, calls one with a module block: module "jobs" uses the folder ./modules/queue. Every resource inside gains the call’s name as a prefix, so the queue’s address becomes module.jobs.aws_sqs_queue.this.

Modules also come from the Terraform Registry. A registry module is a folder too, written by someone else, and terraform init downloads it the way it downloads the AWS provider.

STEP 02 / 04

COUNT NUMBERS COPIES BY POSITION

Fig 10.2The accent rows were never meant to change; they moved up one index and were replaced.

The count meta-argument makes that many copies of a block and numbers them from 0. With count = length(var.regions) and the list ["eu", "us", "ap"], the run created aws_sqs_queue.by_index[0], [1] and [2], each named from count.index.

Then "eu" was removed. Index [0] now meant receipts-us, and a queue’s name can’t change in place, so [0] must be replaced; so must [1], from us to ap. Index [2] is out of range and destroyed. Two queues that should have stayed are deleted and recreated, and the messages in them go too.

QUEUES.TF
variable "regions" {
  default = ["eu", "us", "ap"]
}

resource "aws_sqs_queue" "by_index" {
  count = length(var.regions)
  name  = "receipts-${var.regions[count.index]}"
}
TERRAFORM PLAN, AFTER REMOVING EU (EXCERPT)
# aws_sqs_queue.by_index[0] must be replaced
      ~ name                              = "receipts-eu" -> "receipts-us" # forces replacement
  # aws_sqs_queue.by_index[1] must be replaced
      ~ name                              = "receipts-us" -> "receipts-ap" # forces replacement
  # aws_sqs_queue.by_index[2] will be destroyed
  # (because index [2] is out of range for count)
      - name                              = "receipts-ap" -> null
  # aws_sqs_queue.by_key["eu"] will be destroyed
  # (because key ["eu"] is not in for_each map)
      - name                              = "receipts-by-key-eu" -> null

Plan: 2 to add, 0 to change, 4 to destroy.
STEP 03 / 04

FOR_EACH NAMES COPIES BY KEY

Fig 10.3The accent column changes only the copy you removed.

makes one copy per key of a map or set, and the key becomes part of the address. With for_each = toset(var.regions) the run created aws_sqs_queue.by_key["eu"], ["us"] and ["ap"].

Removing "eu" planned one action for them: by_key["eu"] is destroyed, because key ["eu"] is not in for_each map. The other two keep their addresses and don’t change. The plan above covers both resources and reads Plan: 2 to add, 0 to change, 4 to destroy.: three of the four destroys came from count.

QUEUES.TF, THE FOR_EACH VERSION
resource "aws_sqs_queue" "by_key" {
  for_each = toset(var.regions)
  name     = "receipts-by-key-${each.key}"
}
STEP 04 / 04

A MODULE SEES ONLY THE VALUES YOU PASS IT

Fig 10.4Values go in at hop 1 and come back as outputs at hop 2; nothing else crosses the module boundary.

Inside ./modules/queue, each variable block declares an input, and each output block a value the caller may read. The module sees nothing else of the root module. The call below passes a name, a Region and a timeout per key, and the root reads one copy’s queue ARN as module.jobs["eu"].arn. The queue’s region argument exists on most resources since version 6 of the AWS provider.

A registry module is called by source and version: source = "terraform-aws-modules/sqs/aws" with version = "~> 5.2" (5.2.2 is current). Moving the existing aws_sqs_queue.jobs into a module changes its address, so pair the change with a moved block (chapter 07).

MAIN.TF IN THE ROOT MODULE
module "jobs" {
  source = "./modules/queue"
  for_each = {
    eu = "eu-west-1"
    us = "us-east-1"
    ap = "ap-southeast-1"
  }

  name    = "receipt-jobs-${each.key}"
  region  = each.value
  timeout = 60
}

output "eu_queue_arn" {
  value = module.jobs["eu"].arn
}
MODULES/QUEUE/MAIN.TF
variable "name" {
  type = string
}

variable "region" {
  type = string
}

variable "timeout" {
  type    = number
  default = 60
}

resource "aws_sqs_queue" "this" {
  name                       = var.name
  region                     = var.region
  visibility_timeout_seconds = var.timeout
}

output "arn" {
  value = aws_sqs_queue.this.arn
}

COMMON QUESTIONS

count or for_each?
for_each for anything with a name or a key; count for a resource that exists or doesn’t: count = var.enabled ? 1 : 0.
Should a module have its own provider block?
No. Let the caller pass providers, as providers = { aws = aws.audit }. A module with its own provider block can’t be called with for_each or count.
Can a count resource switch to for_each without being replaced?
Yes, with one moved block per instance, from aws_sqs_queue.by_index[0] to aws_sqs_queue.by_key["eu"], as long as each copy’s arguments stay the same.

WHAT YOU NOW KNOW

  • Removing “eu” from a count list replaced two queues and destroyed a third; with for_each it destroyed only ["eu"].
  • A module is a folder with variables and outputs; its resources live under module.jobs.
  • Pin registry modules with version, and add a moved block when you move a resource into a module.
DEEP DIVE: module sources, variable types and validation, dynamic blocks, how big a module should be, the public module registry

Module sources

source takes a local path such as ./modules/queue, a registry address such as terraform-aws-modules/sqs/aws, or a git URL pinned to a tag, such as git::https://example.com/shop/modules.git//queue?ref=v1.4.0. terraform init downloads every module that isn’t a local path into .terraform/modules/. Since Terraform 1.15, source and version may use variables and locals.

Variable types and validation

A variable can take a structured type, such as object({ name = string, timeout = optional(number, 60) }), where optional fills in a default. A validation block rejects bad values at plan time, for example a timeout over 43,200 seconds, the 12 hours SQS allows. sensitive = true hides a value in plan output, nullable = false refuses null, and deprecated (1.15) warns callers who still set it.

Dynamic blocks

A dynamic block writes one nested block per item of a list or map, inside a single resource. A security group with one ingress block per allowed port is the usual case: dynamic "ingress" { for_each = var.ports … }. Use it sparingly; a resource whose nested blocks all come from loops is hard to read in review.

How big a module should be

Make one module per thing a team deploys together, such as the receipts queue with its dead-letter queue and alarms. Deep nesting makes addresses long, as in module.app.module.jobs.aws_sqs_queue.this, and every later refactor needs a moved block per level. A module that only wraps one resource with the same arguments adds a layer and nothing else.

The public module registry

terraform-aws-modules/sqs/aws is at 5.2.2 and terraform-aws-modules/s3-bucket/aws at 5.18.0 (registry, 20 November 2026). They save typing, and each version can change defaults you never set. Read a module’s resources and variables before you trust it, and pin it with version so an upgrade arrives through a pull request.

ON THE EXAM

“where init downloads modules”
.terraform/modules
“pin a registry module”
the version argument in the module block
“read a value from a child module”
module.<name>.<output>
“scope of a variable declared in a child module”
that module only; the caller passes it as an argument
“many copies, each with a stable identity”
for_each
“repeat a nested block inside one resource”
dynamic

The whole picture

Every part from the ten chapters on one map. The numbers on the map match the rows of the reference table under it.

Find a number on the map, then its row below: what the part does, where it sits and what it decides.
  1. 1configuration

    describes the resources you want

    attached to
    the working directory
    decides on
    nothing: it states the goal
    when wrong
    a plan that creates or destroys what you didn’t expect
  2. 2lock file

    pins the provider version and its checksums

    attached to
    the working directory, in git
    decides on
    which provider build init installs
    when wrong
    two machines planning differently from the same code
  3. 3Terraform Registry

    serves providers and modules

    attached to
    registry.terraform.io
    decides on
    which versions match a constraint
    when wrong
    init failing to find a version
  4. 4AWS provider

    makes every AWS call; owns each resource type’s schema

    attached to
    started by core, over gRPC
    decides on
    which arguments force a replacement
    when wrong
    API errors such as BucketAlreadyOwnedByYou
  5. 5Terraform core

    reads code and state, builds the graph, plans, applies

    attached to
    your laptop or a CI runner
    decides on
    the actions and their order
    when wrong
    a plan nobody read, applied with -auto-approve
  6. 6saved plan

    the reviewed actions, applied exactly

    attached to
    a file beside the code
    decides on
    nothing: it is replayed as written
    when wrong
    Saved plan is stale
  7. 7state

    maps each address to one real object’s ID

    attached to
    a local file, then the S3 backend
    decides on
    what Terraform manages
    when wrong
    resources created twice, or forgotten
  8. 8resources in AWS

    the real bucket, queue and role

    attached to
    account 123456789012, eu-west-1
    decides on
    nothing about Terraform
    when wrong
    drift on the next plan
  9. 9changes outside Terraform

    the console, the CLI and other tools

    attached to
    the same AWS account
    decides on
    nothing Terraform sees until a refresh
    when wrong
    the next apply undoing a hand-made fix
  10. 10import, moved, removed

    change the state through a plan

    attached to
    the configuration
    decides on
    which address points at which object
    when wrong
    a destroy where a rename was meant
  11. 11lifecycle rules

    limit what a plan may do to one resource

    attached to
    inside a resource block
    decides on
    destroy, forget, replacement order, ignored attributes
    when wrong
    Instance cannot be destroyed, or no protection once the block is gone
  12. 12S3 backend and lock file

    one shared, locked, versioned state

    attached to
    bucket shop-tfstate
    decides on
    which run may write the state
    when wrong
    Error acquiring the state lock
  13. 13module

    a folder of blocks called with inputs and outputs

    attached to
    the configuration
    decides on
    the module. prefix on every address inside
    when wrong
    a destroy and create after moving a resource into it
  14. ·data source

    reads something it doesn’t manage

    attached to
    the configuration
    decides on
    nothing: it only reads
    when wrong
    a plan that fails when the lookup finds nothing
  15. ·dependency graph

    orders work by references

    attached to
    inside core
    decides on
    what runs first, 10 at a time
    when wrong
    a cycle error, or a hidden dependency missing depends_on
  16. ·write-only argument

    sends a secret without storing it

    attached to
    a resource argument
    decides on
    nothing: it is never read back
    when wrong
    a password in the state when the plain argument was used
  17. ·count and for_each

    many copies of one block

    attached to
    a resource or module block
    decides on
    each copy’s identity: position or key
    when wrong
    replacements after removing one list item

THREE THINGS TO KEEP

  • Terraform makes AWS match your code, and keeps a record of everything it created so it can find it again.
  • The record decides: a block gone from the code means delete, and a block missing from the record means create.
  • Before you remove or rename anything, read the plan. A deleted or commented-out block deletes the real resource.

That is every part of a Terraform run. Next time a plan wants to destroy something, you will know which part decided it.

Read next. AWS access, for where the credentials the provider signs with come from.