Terraform Remote State and Backends

Why a remote backend?

With local state, only one laptop knows what exists. A backend stores state in a shared place, and locking stops two people applying at the same time and corrupting it.

AWS S3 backend

terraform {
  backend "s3" {
    bucket       = "acme-terraform-state"
    key          = "shop/prod/terraform.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true   # native S3 locking (Terraform 1.10+); no DynamoDB table needed
  }
}

Turn on versioning for the state bucket so you can recover an older state, and restrict who can read it.

Azure and Google Cloud

terraform {
  backend "azurerm" {
    resource_group_name  = "tfstate"
    storage_account_name = "acmetfstate"
    container_name       = "state"
    key                  = "shop/prod.tfstate"
  }
}

terraform {
  backend "gcs" {
    bucket = "acme-terraform-state"
    prefix = "shop/prod"
  }
}

Both lock automatically. HCP Terraform (formerly Terraform Cloud) stores state, locks it and runs plans in the cloud, using a cloud { … } block instead of a backend.

Changing backends

After changing the backend block, run terraform init -migrate-state; Terraform copies the existing state to the new location.

Sharing values between configurations

A network configuration can publish outputs that an application configuration reads with the terraform_remote_state data source:

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "acme-terraform-state"
    key    = "network/prod/terraform.tfstate"
    region = "eu-west-1"
  }
}

resource "aws_instance" "app" {
  subnet_id = data.terraform_remote_state.network.outputs.private_subnet_ids[0]
  # ...
}