State & Backends

A remote backend keeps Terraform state in shared, durable storage such as an S3 bucket instead of one laptop's disk. Every engineer and CI job then reads and writes the same state, so runs cannot silently diverge, duplicate resources, or destroy each other's work.

Never commit terraform.tfstate, terraform.tfstate.backup, the .terraform directory, saved plan files, crash logs, or tfvars files holding secrets. A saved plan embeds the prior state plus planned attribute values, so it carries the same plain-text credentials state does.

Importing binds an already-existing object to a resource address in Terraform state. It creates no infrastructure and writes no configuration for you. The terraform import command needs the resource block written first; a Terraform 1.5+ import block runs inside plan and apply.

Terraform sees every declared resource as new and plans to create a second copy of everything, while the existing objects become orphans it can no longer read, change or destroy. Recovery means restoring a snapshot or re-adopting each object into state.

Terraform state binds each configuration address, such as aws_instance.web, to the real object ID the provider returned, and stores that object's last-known attributes plus its recorded dependencies. Without the binding, Terraform cannot tell which cloud objects are its own.

Create the state bucket first with versioning enabled, add a backend "s3" block to the terraform block, then run terraform init -migrate-state to copy the existing state up. Confirm success by running terraform plan and seeing no changes.

Terraform state caches resource attributes exactly as configured or returned, so the generated password sits in plaintext in the state file, its local backup and any saved plan. sensitive = true only redacts CLI output; it never encrypts or omits storage.

Split along blast radius, change cadence and ownership: long-lived networking in one state, fast-moving application resources in another. The payoff is shorter plans, less lock contention, narrower credentials per state, and a mistake that cannot reach the whole estate.

terraform state rm deletes only the state entry: the cloud object keeps running, now managed by nobody. It is right when handing an object to another state or deliberately releasing it from Terraform; since Terraform 1.7 a removed block does the same thing declaratively.

Read the Lock Info block, then prove the run that took the lock is really dead — check the CI job and the named principal — before running terraform force-unlock with that exact lock ID. Force-unlocking a live apply lets a second run race it and lose state writes.

terraform state list prints the resource addresses Terraform is tracking; terraform state show <address> prints that one resource's recorded attributes. Both only read state. The other subcommands, such as mv and rm, rewrite it.

Being readable does not make the format a public interface: it is versioned, internally consistent, and rewritten by Terraform on every run. Hand edits bypass the bookkeeping and corrupt silently, so Terraform provides dedicated state subcommands for every legitimate change.

The producing configuration must declare a root-level output. The consumer adds a terraform_remote_state data source pointing at the producer's backend and reads data.terraform_remote_state.NAME.outputs.KEY. Only declared root outputs are exposed, never arbitrary resource attributes.

Add a moved block with the old address in from and the new address in to. Terraform then rewrites the state mapping during plan and apply instead of destroying and recreating the object. The alternative, terraform state mv, does the same thing imperatively and unreviewably.

The lock is a backend feature, not a Terraform one. The S3 backend writes a .tflock object next to the state (use_lockfile) or, historically, a DynamoDB item; GCS writes a lock object; the local backend takes an OS file lock that only covers one machine.

Each instance in Terraform's state carries a dependencies list of the addresses it referenced at the last apply. For a resource whose block is gone, Terraform works entirely from that recorded entry and reverses the recorded edges to order the destroy.

Backend settings are read at init, before variables, locals or providers are evaluated, so they must be literal values. The workaround is partial configuration: omit the varying arguments and supply them at init with -backend-config files or key=value flags.

Adopt in small slices ordered by blast radius, write or generate configuration for each slice, import it, and treat a plan reporting no changes as the acceptance test before moving on. Never apply a post-import plan that still proposes changes.

-lock=false disables locking entirely, converting a loud failure into a silent race that can strand real resources outside state. Use -lock-timeout so a queued run waits for the lock instead, and serialise the pipeline so only one run per state executes at a time.

Cached attributes are the prior side of every diff, the source for cross-resource references and outputs at plan time, and the only home for values the API never returns. When they are stale, the plan is computed against a fiction and can show no changes while reality differs.

S3 bucket versioning keeps every previous copy of the state object, so recovery means listing object versions, identifying the last good one, and restoring it as the current version. Afterwards run terraform plan: unexpected creates mean resources built after that snapshot need importing.

Server-side encryption protects state only against someone reading the storage underneath the API — stolen media, a mis-scoped bucket listing, an unauthorised backup copy. Any identity allowed to fetch the object gets it decrypted, so authorization, not encryption, is the real control.

Rotate the credential first — that is the only action that revokes access. Copies persist in Git history and clones, prior S3 object versions, local backups and CI artifacts, so removing files cannot restore confidentiality, and terraform state rm only makes Terraform forget the resource.

terraform_remote_state reads the producer's entire state file — simple, but it needs broad read access. A provider data lookup queries the live API by tag or name — looser, but it relies on naming discipline. Publishing to SSM Parameter Store makes the contract explicit and narrowly scoped.

They keep a secret out of state and out of plan files entirely, rather than merely redacting it in output. The tradeoff: a write-only argument is never stored, so Terraform cannot diff it — you bump a paired version argument to make it re-send the value.

Serial is a counter Terraform increments on every state write, so it can tell which snapshot is newer. Lineage is a UUID minted when the state was first created, identifying the line of descent; a mismatch means two unrelated states, and Terraform refuses rather than overwriting.

Ship moved blocks inside the module itself. They travel with the module version, so each consumer's next plan re-keys their own state entries automatically. Keep them for a documented deprecation window and drop them only at a major version boundary.

A self-managed object-storage backend stores state cheaply and keeps everything inside your account, but you build locking, versioning, access control and the pipeline yourself. HCP Terraform provides state, locking, run history, RBAC and optional remote execution as a product, at per-resource cost and outside your network.

Every seam adds a handoff: no single plan shows a cross-cutting change, applies must run in a chosen order, and one edit ripples through several pipelines. Split for blast radius and ownership; stop when routine changes need three states coordinated.