What Terraform state records, how a backend stores it, and why state storage needs security and collaboration controls.
Terraform state records the bindings between resource instances in configuration and the remote objects Terraform manages. A backend determines where that state is stored and supplies the interface Terraform uses to read and write it. Providers communicate with cloud or service APIs; backends handle state, so they should not be confused. HashiCorp’s state documentation and backend overview define these boundaries.
| Concept | Responsibility |
|---|---|
| State | Identifies managed remote objects, retains metadata, and caches values Terraform needs for planning. |
| Provider | Creates, reads, updates, and deletes remote objects through a service API. |
| Backend | Stores state and may support locking. |
| Workspace | Selects a distinct state instance, subject to backend behavior. |
Terraform uses the local backend by default, storing the selected workspace’s state in a local terraform.tfstate file unless configured otherwise. The local backend can be appropriate for a short-lived personal experiment, but it makes shared operations and recovery dependent on one machine. A lost local state file can leave Terraform unable to identify what it manages.
State is JSON, but do not edit it directly. Use Terraform’s state-aware commands only when there is a well-understood maintenance need, and make a backup first. State may contain sensitive values, so exclude terraform.tfstate, its backups, .terraform/, and saved plans from version control. Commit .terraform.lock.hcl, which is a provider dependency lock file, not state.
A configuration can define one backend inside the top-level terraform block. This generic example names an S3 backend; the actual bucket, encryption, access control, and locking capabilities must be designed for the organization and Terraform version in use.
1terraform {
2 backend "s3" {
3 bucket = "example-terraform-state"
4 key = "networking/terraform.tfstate"
5 region = "ca-central-1"
6 }
7}
Backend blocks cannot refer to normal Terraform named values such as input variables or data-source attributes. Keep backend credentials out of the configuration; use the authentication method supported by the chosen backend. Re-run terraform init after a backend change and follow its migration prompts deliberately rather than treating a backend move as a routine formatting change.
Choose a remote backend or HCP Terraform for shared or important infrastructure so state has appropriate access control, backup, and collaboration behavior. Inspect the documentation for the exact backend: remote storage does not automatically mean that it provides locking, encryption, or every operational feature needed by a team.