Module 6: Terraform State Management

Lesson 6.3: Remote State with the Backend Block

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.

HCL
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 terraform block. 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:

HCL
terraform {
  backend "s3" {
    key = "network/terraform.tfstate" # rest supplied at init
  }
}
Shell
terraform init -backend-config=backend-prod.hcl          # a file of key = value pairs
terraform init -backend-config="bucket=acme-tfstate"     # or individual pairs

Backend 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:

HCL
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_outputs data source.