Plain language
A remote backend stores state in a shared service. This gives a single source of truth, locking, encryption at rest, versioning, and access control.
terraform {
backend "s3" {
bucket = "acme-tfstate"
key = "network/terraform.tfstate"
region = "us-east-1"
encrypt = true
use_lockfile = true
}
}Built-in backend types in 1.12: local, remote (legacy HCP Terraform), azurerm, consul, cos, gcs, http, kubernetes, oss, pg, s3.
For HCP Terraform, use the cloud block rather than the remote backend (Module 8).
Rules for the backend block
- It goes inside the
terraformblock. Only one backend is allowed per configuration. - It can't use variables, locals, or references. Values must be literals, or be supplied through partial configuration.
- Changing it requires
terraform init.
Partial configuration
Leave some or all settings out of the code and supply them at init time:
terraform {
backend "s3" {
key = "network/terraform.tfstate" # rest supplied at init
}
}terraform init -backend-config=backend-prod.hcl # a file of key = value pairs
terraform init -backend-config="bucket=acme-tfstate" # or individual pairsBackend settings are stored in .terraform/ and in saved plan files. Provide credentials through environment variables or the provider's standard credential chain, not through -backend-config.
Changing backends
| Command | Behavior |
|---|---|
terraform init after changing the backend |
Detects the change and asks whether to copy existing state to the new backend |
terraform init -migrate-state |
Migrates state explicitly. Add -force-copy to skip the prompt. |
terraform init -reconfigure |
Uses the new backend configuration without migrating the existing state |
Moving back from a remote backend to local works the same way: remove the backend block and run terraform init -migrate-state.
Reading another configuration's outputs
The terraform_remote_state data source reads root module outputs from another configuration's state:
data "terraform_remote_state" "network" {
backend = "s3"
config = {
bucket = "acme-tfstate"
key = "network/terraform.tfstate"
region = "us-east-1"
}
}
# usage: data.terraform_remote_state.network.outputs.vpc_id- Only root module outputs are exposed. Resource attributes and child module outputs aren't, unless the root re-exports them.
- The reader must have access to the entire state snapshot, which may contain secrets. HashiCorp suggests alternatives where possible: provider data sources that look up the real object, or, in HCP Terraform, the
tfe_outputsdata source.