Cheat Sheet 6: State Management
Local backend (the default)
- Files:
terraform.tfstate,terraform.tfstate.backup(previous version), andterraform.tfstate.d/<ws>/for CLI workspaces. backend "local" { path = "…" }sets the path explicitly.-state=works for local only.- Locks with OS file locks, on the same machine only. Not suited to teams: no sharing, plaintext secrets on disk, easy to lose. Never commit state.
Locking
- Automatic on any state-writing operation. Backend support varies.
- S3:
use_lockfile = true(DynamoDB locking is deprecated) · azurerm blob lease · gcs · pg advisory locks · consul · kubernetes · http (optional) · HCP Terraform built in. -lock-timeout=60swaits.-lock=falseskips locking (avoid).terraform force-unlock LOCK_IDclears a stuck lock only when nothing is running.
Remote backends
terraform { backend "TYPE" { … } }. One per configuration. Literal values only.- Built-in types: local, remote, azurerm, consul, cos, gcs, http, kubernetes, oss, pg, s3. Use the
cloudblock for HCP Terraform. - Partial configuration:
init -backend-config=file.hclor-backend-config="k=v". Provide credentials through environment variables, because backend settings are stored in.terraform/and in plan files. - Changing backends:
init(prompts) ·-migrate-state(copies; add-force-copyto skip the prompt) ·-reconfigure(no copy). terraform_remote_stateexposes root outputs only at.outputs.NAME, needs full state read access, and takes aworkspaceargument. Alternatives: provider data sources,tfe_outputs.
Drift
- A normal plan refreshes, reports "changed outside of Terraform," and proposes reverting to the configuration.
plan -refresh-onlyreviews drift.apply -refresh-onlywrites state only, so update the code if you want to keep the change.terraform refreshis deprecated (it'sapply -refresh-only -auto-approve, with no review).- An object deleted outside Terraform drops from state on refresh, and the plan recreates it.
ignore_changesis for attributes another system owns.
State changes: prefer config blocks, which are plannable and reviewable
| Need | Block | CLI alternative |
|---|---|---|
| Rename or move | moved { from, to } |
state mv |
| Forget without destroying | removed { from; lifecycle { destroy = false } } (1.7+) |
state rm |
| Adopt an existing object | import { to, id } |
terraform import |
| Recreate | apply -replace=ADDR |
taint (deprecated) |
state rmwith the block still in configuration → the next plan creates a duplicate.- Don't hand-edit state, because of serial and lineage, locking, and the missing audit trail.
state pullandpushare for disaster recovery only.
CLI workspaces
workspace list/show/new/select [-or-create]/delete [-force].defaultcan't be deleted.terraform.workspaceandTF_WORKSPACE.- Multiple states, one configuration, one backend, with no separate credentials or permissions.
- ≠ HCP Terraform workspaces, which have their own state, variables, permissions, runs, and policies.
Module 6 self-check
Module 6 self-check.
- Coverage: 6a (lesson 6.1, Lab 6A step 1, Q1), 6b (lesson 6.2, Lab 6A step 5, Q2–Q3), 6c (lessons 6.3 and 6.5, Lab 6A steps 2–7, Q4–Q6, Q10), and 6d (lesson 6.4, Lab 6B, Q7–Q9).
- HCL:
backend "pg" {}withPG_CONN_STR,terraform_remote_statewithbackend,workspace, andconfig, themovedblock, and theremovedblock withlifecycle { destroy = false }all follow documented syntax for 1.7+ and 1.12. Alignment matchesfmt. - Flagged uncertainty:
- Lab 6A notes that
pgadvisory locks release when the session ends, soforce-unlockisn't demonstrated live rather than faked. - Lesson 6.4 tells learners to set
destroyexplicitly inremovedblocks instead of relying on a default. - The
statestable name in thepgbackend is the documented default schema layout. If your provider version differs,\dt terraform_remote_state.*in psql shows the actual table.
- Lab 6A notes that
- Answers: rechecked against documented locking, migration, refresh-only, and workspace behavior.