Terraform Remote State with S3: Backend Configuration Example

If you need the full overview of Terraform state, start with Terraform State Explained: Remote State, Locking, Backends and Best Practices. This page is narrower: it focuses on using an AWS S3 backend for remote Terraform state.

Why use remote state in S3?

Local state is fine for short-lived testing, but once a Terraform project becomes shared or important, you need a central backend. S3 is a common choice on AWS because it is durable, easy to secure, and straightforward to integrate with CI pipelines.

• One shared source of truth for your Terraform runs.
• Better access control than passing local state files around.
• A cleaner operational model for team workflows.

Minimal backend block

Your Terraform configuration normally includes only the backend type, while account-specific values are injected from a backend config file or CI variables.

terraform {
  backend "s3" {}
}

Example backend configuration

bucket = "my-terraform-state-bucket"
key    = "networking/prod/terraform.tfstate"
region = "eu-west-1"

This pattern keeps the reusable Terraform code clean while letting you point different environments at different backend locations.

Initialize or migrate the backend

When you first introduce a backend, initialize Terraform with the backend configuration file:

terraform init -backend-config=backend.conf

If you are moving an existing configuration from one backend location to another, prefer:

terraform init -migrate-state

Use -reconfigure when you need Terraform to forget cached backend settings and read the configuration again without trying to move state automatically.

Common mistakes to avoid

• Hardcoding credentials into backend configuration files.
• Running Terraform from multiple places without an agreed workflow.
• Changing backend settings without backing up the existing state.
• Assuming the state file is harmless text. It may contain sensitive values.

When to use a different guide

• For the full explanation of state, backends, locking, and commands, use the main Terraform state guide.
• For moving state between AWS accounts, use Move Terraform State Between AWS Accounts.
• For plan-file review workflows, use Terraform Plan -out.

This page is intentionally focused on the S3 backend setup so it complements the main Terraform state guide rather than duplicating it.