6 State Management

This chapter explains why Terraform is a stateful system and what that means in practice. State links configuration to real-world resources using stable identifiers, avoiding fragile discovery heuristics and enabling faster plans, richer features, and simpler provider development. Keeping state also unlocks “state-only” workflows where resources exist purely in state to generate data or logic (for example, random values, TLS assets, null/terraform_data helpers). The tradeoff is that teams must manage state as critical data: it accelerates iteration and supports advanced patterns, but it must be stored, protected, and operated with care.

The chapter details three pillars for state backends—reliability, security, and availability—and shows how local state is for development only. It surveys built-in backends (S3, GCS, AzureRM, Consul, PostgreSQL, Kubernetes, HTTP, and cloud/TACOS options), calls out essentials like encryption, locking, auditing, and backups, and covers backend configuration patterns, partial configs, environment-based auth, and the Cloud block (including remote execution and workspace behavior differences between vendors and Terraform/OpenTofu). It dissects state’s JSON structure (version, terraform_version, serial, lineage, resources, outputs, checks), explains migrations and upgrades, and clarifies the two flavors of “workspaces,” emphasizing where confusion commonly arises.

For day‑to‑day operations, the chapter recommends backing up with state pull/push, using code-first moves and removals (moved/removed blocks), falling back to CLI tools for specific cases, and treating manual edits as a last resort. It classifies state drift causes (accidental or intentional manual changes, expected external/automated changes, and Terraform/back-end faults) and suggests responses like refresh-only plans, lifecycle ignore_changes, imports, and strong operational hygiene. For cross-project composition, it presents terraform_remote_state (with defaults), guidance to keep lookups at the root or in thin adapters, and alternatives such as provider data sources or explicit variables. It closes with practical patterns for state-only providers: Random (keepers and sensitive outputs), Time (static/offset/rotating/sleep), Null, and the built-in terraform_data as a modern, provider-free replacement for testing flows, triggering replacements, and orchestrating provisioners.

Basic Backend Configuration Requirements

Types of State Drift

An example of how organization structure can mirror module ownership.

• Terraform uses State to reduce complexity, improve performance, and provide functionality such as remote state viewing and state only resources.
• When working with teams a centralized state storage solution is essential, and this is provided by Terraform Backends.
• Terraform Backends are generally chosen from technology teams are already using, or through the use of specialized Terraform CICD tools.
• State Drift occurs when the Terraform state does not match the real world infrastructure.
• State can be accessed across projects, allowing the outputs from one project to be used in another project.
• State only resources enable the use of data, such as the time or even random numbers, to be generated in a Terraform centric way.

FAQ