State

Terraform could in theory ask the cloud provider on every run what exists and compare it with the code. It does not, for reasons that the official documentation spells out in its page on the purpose of state. There are four of them.

Source: Terraform Docs — Purpose of Terraform State

The official docs state the central rule in one sentence: the primary purpose of state is to store bindings between objects in a remote system and resource instances declared in your configuration. Terraform expects a one-to-one mapping. If a remote object were bound to two resource instances, the mapping would be ambiguous and Terraform "may behave unexpectedly". Terraform guarantees one-to-one when it creates objects itself, but when you add or remove bindings by other means (terraform import, an import block, terraform state rm, terraform state mv), the guarantee becomes your responsibility. Importing the same bucket into two resource addresses is the textbook way to break it.

State is also the reason a configuration is not enough to describe a deployment. Two copies of the same code with different state files manage two different sets of objects, and the same state file used with two different codebases is a recipe for destroying things. That is why the section on Workspaces, Environments and Project Structure spends so much time on how many states a project should have.

By default Terraform keeps each workspace’s state in a local file named terraform.tfstate, and the previous snapshot in terraform.tfstate.backup, both in the working directory. That needs no configuration, but the official docs list the two reasons it does not scale: it makes collaboration hard, and the state is lost if the file is lost. The recommendation is to store state in HCP Terraform or in a remote backend, and the docs warn against version control or any storage that lacks locking and secure access control, because that risks data loss and the exposure of secrets stored in the state.

Three different files in a working directory have confusingly similar names.

Source: Terraform Docs — State and Terraform Docs — Backends

With a remote backend the state lives in the backend: an S3 object, a Google Cloud Storage object, an Azure blob, a row in PostgreSQL, a Kubernetes secret, or an HCP Terraform workspace. Terraform holds it in memory while it works and does not leave a copy on disk, apart from the backups that the terraform state commands write (see Backups and recovery). The catalogue of backends, partial configuration and migration with terraform init -migrate-state are the subject of Backends and Remote State.

State is a JSON document. The official docs are firm on two points: do not edit it by hand, because the terraform state commands exist to modify it safely, and do not build software on the raw format, because the format "is subject to change in new Terraform versions" even though new versions are generally backward compatible with earlier snapshots. For tools that need to read state, Terraform provides stable JSON views: terraform output -json for root module outputs and terraform show -json for the full latest snapshot. The raw file is nevertheless worth understanding, because you will read it during incidents.

The top level of a state file has seven fields. This list comes from the state file encoder in the Terraform source code (internal/states/statefile, tag v1.17.0), because the format is not a documented interface.

Each entry in resources[].instances[] has its own fields: index_key (for count and for_each), status, deposed (a key present when a replaced object is being kept until its replacement is created, as happens with create_before_destroy), schema_version, attributes, sensitive_attributes, identity_schema_version and identity (the resource identity used by identity-based import), private (opaque provider data), dependencies and create_before_destroy.

Source: Terraform source — version4.go (state file encoder, v1.17.0)

The following document is illustrative. It is abbreviated from what the encoder defines for a covers bucket and a generated database password, with values replaced by placeholders. A real file contains every attribute of every resource, and it contains the real value of every sensitive attribute, which is why this page shows <redacted> instead.

Source: Terraform Docs — State and Terraform source — version4.go

Four properties of this file matter in practice.

For tools, use the supported views instead of parsing the file. terraform show -json prints a values representation (root_module with resources and child_modules, plus outputs) together with a format_version, and the guidance is that consumers should ignore unrecognized properties and reject an unsupported major format_version. The details of those formats belong to Machine-readable Output and Integrations.

Source: Terraform Docs — JSON Output Format

State holds the attributes of every managed object, so it holds every secret that is an attribute of one: the initial password of a database, the private key of a TLS certificate, an API token returned by a provider. The official sensitive-data guide puts it plainly: Terraform state and plan files contain detailed information about your infrastructure, and with local state the file is plain text that includes any secret values defined in your configuration. OpenTofu’s page on sensitive data in state says the same: "treat the state itself as sensitive data."

Two things the sensitive argument does not do are worth repeating, because they are the most common misconception.

What you can do about it falls into four groups, which the official guide orders by how much they protect.

Source: Terraform Docs — Manage sensitive data in your configuration and OpenTofu Docs — Sensitive Data in State

The preferred order is therefore: keep the secret out of the state if the provider supports an ephemeral resource or a write-only argument, otherwise treat the state as the secret it is. The full treatment of ephemeral and write-only values, with the provider arguments that exist today, is in Sensitive Data, Ephemeral Values and Write-only Arguments.

Rules that follow from this, and that apply to the Bookshelf project:

If the backend supports it, Terraform locks the state for every operation that could write it, so that two runs cannot modify the same state at once. The lock is taken automatically, silently, and released when the operation ends. If acquiring the lock fails, Terraform stops. If it takes longer than expected, Terraform prints a status message.

Source: Terraform Docs — State Locking and Terraform Docs — terraform force-unlock

The lock ID acts as a nonce: the command refuses to unlock anything other than the lock whose ID you supply, which prevents unlocking the wrong lock by mistake. The documentation of the state locking page has a blunt warning about the command: be very careful, because unlocking while someone else holds the lock can produce multiple writers, and it should be used only to remove your own lock in the case where automatic unlocking failed. How the lock behaves "is dependent on the backend being used", and for local state files another process cannot unlock them.

The following console session is illustrative; the exact wording differs between versions and backends.

Source: Terraform Docs — terraform force-unlock

The safe procedure for a stuck lock is therefore: read the lock information, check with the person or the pipeline that holds it, confirm that its process is really gone, and only then force-unlock. After a crash, check the state before the next apply, because an interrupted apply may have created objects that the state does not yet record. The way to recover those objects is described in Recovering from a failed apply.

Not every backend locks. local locks the file locally; s3 locks with a lock file next to the state when use_lockfile = true, which became generally available in Terraform 1.11 and deprecated the DynamoDB arguments (dynamodb_table); gcs, azurerm, pg, kubernetes and HCP Terraform lock natively, while http depends on the server. The list per backend, with the arguments, is kept in one place: Backends and Remote State.

HCP Terraform goes further than a lock: it queues runs per workspace, so two runs for the same workspace are serialized, and it can detect an attempt to create a new plan while another is waiting for approval. See HCP Terraform and Terraform Enterprise.

The terraform state command group has seven subcommands in the 1.17 documentation: identities, list, mv, pull, replace-provider, rm and show. (The command also has a push, documented on its own page; it is missing from the command index, but exists.) The read-only ones do not write a backup. The documentation recommends combining their output with Unix tools, since it was designed to be friendly to grep and awk.

Source: Terraform Docs — terraform state commands; state list; state show; state identities; state pull

Addresses use the resource addressing syntax: aws_s3_bucket.covers, aws_instance.web[0], module.catalog_api, module.catalog_api.module.network.aws_subnet.private["eu-west-1a"]. Brackets and quotes have a meaning in shells, so quote the address with single quotes in Unix shells; PowerShell and cmd.exe need different escaping, and the documentation of state show shows all three.

Source: Terraform Docs — terraform state list; the sample output is illustrative and abbreviated, derived from the examples on the state show and state identities pages.

terraform show and terraform output are the other inspection commands. terraform show without arguments prints the whole current state in human-readable form, terraform show -json prints it for programs, and terraform output -json prints the root outputs. The distinction between state show and show is simple: state show takes one resource address; show prints all of it, or a saved plan.

Identities are worth a sentence of their own. A resource identity is a set of attributes that uniquely identifies a remote object in a provider’s terms, such as a bucket name and a region, and is stored beside the resource’s attributes in the state (identity_schema_version and identity in the file). It is what makes identity-based import blocks possible. state identities is a read-only way to see the values Terraform has recorded. Not all providers and resource types implement identities yet, and a resource that does not is simply left out of the output. The import side is covered in Import and Query.

Changing state does not change infrastructure. It changes what Terraform believes about infrastructure, and that is exactly why it is dangerous: a wrong edit makes the next plan destroy or duplicate something real. The tool gives you five commands for it, plus two configuration-driven alternatives that are preferred whenever they apply.

Source: state mv; state rm; state replace-provider; state push

Configuration-driven blocks have replaced most of what state mv, state rm and terraform import were used for. The rule of thumb is to prefer the block, because it is reviewed in the pull request, planned before it is applied, and applied identically by everyone.

Source: Terraform Docs — Refactor Terraform state, Remove a resource from state and terraform state rm

The pair moved and removed is documented on Refactoring: moved, removed and import, and the import block and terraform query on Import and Query. What matters here is the model: all of them are ways to edit the bindings of the state, and they differ in whether the edit is declared in the configuration and planned or performed directly and immediately. A removed block with destroy = true is the only form of "remove from state" that also destroys the object, and OpenTofu supports the same block with the same meaning (see Terraform and OpenTofu differences).

The same state mv is also the technique for splitting a large state. The official refactoring guide recommends planning the split by volatility, by whether resources are stateful or stateless, and by team ownership, and documents two ways to migrate resources between state files: the pair state rm and import (which re-creates the binding in the destination), or state mv -state-out, which writes to a second local file. After the split, share values between the pieces with terraform_remote_state, a data source, or a store such as SSM or Key Vault. See Backends and Remote State.

Terraform protects its state in several overlapping ways. Understanding which one applies to your backend tells you what you can recover.

Source: Terraform Docs — S3 backend, GCS backend, state commands and the OpenTofu v1.13 CHANGELOG

The recovery routine depends on what was lost.

Drift is any difference between what the state records and what actually exists, introduced outside Terraform: an engineer changes a security group in the console during an incident, a scaling policy resizes a group, another automation modifies a tag. Terraform’s normal plan already reconciles drift in one direction: before computing changes it refreshes the state, reading every managed object, and then plans to bring reality back to the configuration. Drift therefore shows up as a proposed change, and it is overwritten if you apply.

That is not always what you want. Sometimes the manual change was intentional and the right move is to update the code or to accept the new value into the state without touching the object. For that, Terraform offers the refresh-only planning mode.

Source: Terraform Docs — terraform plan, terraform refresh and Terraform v1.17 CHANGELOG

The reason refresh was deprecated is explicit in the documentation: with misconfigured provider credentials, Terraform "may be misled into thinking that all of the managed objects have been deleted", and an automatic refresh would then remove every tracked object from the state without any prompt. apply -refresh-only has the same effect on the state but with a confirmation, so you can notice that the whole infrastructure appears to be gone. The mode was introduced in Terraform 0.15.4.

A drift review for the Bookshelf covers bucket looks like the following. The output is illustrative, abbreviated from the format Terraform prints for refresh-only plans.

Source: Terraform Docs — terraform plan (refresh-only mode); the console text is illustrative and abbreviated, not a verbatim copy.

You then have three choices: accept it (terraform apply -refresh-only), codify it (add owner to the code, so that the plan is clean), or reverse it (a normal terraform apply). The same decision, made on a schedule, is the heart of drift detection: HCP Terraform offers health assessments that run a refresh-only check on a schedule, and a pipeline can simply run terraform plan -refresh-only -detailed-exitcode nightly and alert on exit code 2. Exit code 2 of -detailed-exitcode means a diff exists, as with a normal plan; see CI/CD and Automation and HCP Terraform and Terraform Enterprise.

To avoid drift that you do not want to see, use lifecycle { ignore_changes = [...] } for attributes that another system legitimately owns, which is described in Lifecycle, Validation and Checks. A check block with a scoped data source is a way to be warned when an external condition stops being true.

Three other sources of confusion are commonly mistaken for drift:

The following diagram puts the pieces together for one terraform apply with a remote, locking backend: where the lock is taken, where the refresh happens, and when the state is written.

Source: Terraform Docs — State and State Locking; the sequence is a simplified original drawing.

The sequence makes several practical rules visible. A plan that is saved and applied later (-out and then apply plan.tfplan) is rejected if the state has changed since the plan was made, because the plan records the state it was based on (Terraform reports a stale plan); that is the reason saved plans are the safe way to separate review from execution in a pipeline. The write happens after each object, not at the end, which is why a failed apply leaves a consistent partial result. And read-only commands such as plan also take the lock (except with -lock=false), because they may refresh and, in refresh-only mode, write.

Source: Terraform v1.17 CHANGELOG, v1.16, v1.15, v1.11, v1.7 and v1.1

Deprecated and legacy items to know when you read older material: terraform refresh (use -refresh-only); the -state, -state-out and -backup options of the local backend (documented as legacy features preserved for compatibility; use the path argument of the backend, and note that the state-flag deprecation is tracked in the version table of the CLI page, CLI Essentials); the S3 backend arguments dynamodb_table and related (deprecated in favor of use_lockfile); and the use of terraform state rm and terraform import where a removed or import block can do the job.

State is the area where the two tools are most compatible and, since the fork, most different in one respect: protection of the file.

Source: OpenTofu Docs — tofu state, OpenTofu Docs — State, State and Plan Encryption, tofu force-unlock and the OpenTofu v1.13 CHANGELOG

The state chapters of the books covered by this section remain conceptually correct: the file is JSON, serial and lineage exist, drift is the difference between state and reality. What is out of date: