Configuring a Remote Backend

Moving state off laptops takes one declaration inside the existing terraform block:

terraform {
  required_version = ">= 1.6.0"

  backend "s3" {
    bucket         = "acme-tfstate-prod"
    key            = "network/terraform.tfstate"
    region         = "eu-west-1"
    dynamodb_table = "tfstate-locks"
    encrypt        = true
  }
}

The block has two halves, and conflating them is the first conceptual stumble. The backend type — here s3, but also azurerm, gcs, http, remote, kubernetes, and others — selects the storage implementation and which provider plugin (if any) backs it. The arguments configure that implementation. This is not a provider configuration: the S3 backend talks to S3 with ambient credentials (environment variables, shared config, instance profile) and never reads your provider "aws" block. A team can therefore point state at a dedicated account or bucket with completely separate credentials from the ones managing resources — separation that most security reviews eventually demand.

A constraint that surprises everyone once: backend arguments must be literals. No variables, no locals, no data references, no expressions beyond literal values. The reason is bootstrapping — the backend is read before the configuration graph exists, so there is nothing to evaluate against. key = "${var.env}/terraform.tfstate" fails outright, and the error sends people to the partial-configuration pattern covered in Partial Backend Configuration. It also means the backend block is deliberately minimal: one block per environment's shape, with the varying values (bucket names, keys) supplied at init.

Each argument's role in the S3 case, because they recur in every backend discussion:

Two operational notes close the loop. The key is how stacks share a bucket safely — network/terraform.tfstate and app/terraform.tfstate are different objects in one bucket, so a whole estate can use a single well-governed bucket. And adding or changing a backend later is not an edit-and-forget operation: the next terraform init performs the migration, and understanding that flow — including what happens to the local file — is the next chapter's subject.

One asymmetry is worth internalizing before your first init against a real bucket: backend credentials are resolved independently of provider credentials, through the AWS SDK's own chain — environment variables, shared config and SSO profiles, container or instance roles — because the backend block is not provider configuration. A developer whose SSO grants ec2:* for resource work will find terraform init fail with access denied on the state bucket, while terraform plan would have succeeded had state already been reachable. In CI, the runner's role needs state-plane permissions — s3:GetObject/PutObject/DeleteObject on the bucket and, when locking is on, dynamodb:PutItem/GetItem/DeleteItem on the lock table — scoped independently from the deploy permissions. Two credential paths, two permission sets, one command sequence: this separation is the feature that lets state live in a different account, and the trap that produces the most confusing access-denied errors of any Terraform setup. (Recent releases also add S3-native locking via use_lockfile, removing the DynamoDB requirement; the DynamoDB pairing remains the widely deployed, well-documented default.)

You add the backend "s3" block to a repository whose state currently lives in a local terraform.tfstate, and run terraform init. Before anything is downloaded or written, Terraform stops and asks:

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.

Do you want to copy existing state to the new backend?
  Enter yes or no.

Answer yes and the local state file is copied into the new backend, byte for byte, with its serial and lineage intact — no resources are touched, no plan runs, nothing is created or destroyed. A state migration is a storage operation, not an infrastructure operation, and that is exactly why it is safe to do during business hours. Answer no and the backend is configured but empty: the next plan sees an empty baseline and cheerfully proposes to create your entire estate — the ephemeral-CI failure from Limitations of Local State Files, on demand. "No" is correct only when you intend to import or start fresh.

On backends that support workspaces (S3 does), init also asks which workspace to start in — default unless you deliberately select or create another. Your existing state becomes the state of that workspace.

The same machinery handles every later backend change, so know the three flags by heart:

terraform init -reconfigure       # accept new backend settings WITHOUT migrating state
terraform init -migrate-state     # force the migration flow (prompt, then copy)
terraform init -backend=false     # init providers/modules only; do not touch the backend

-reconfigure is the everyday one: you changed a lock table name or a key prefix and want Terraform to use the existing state already in that backend, not to copy anything. The subtle trap is the default behavior: with changed backend settings and no flag, init prompts to migrate, and a hurried yes at 6 p.m. can copy the current state to a new location while the old copy remains — after which two stores each hold "the" state. Confirm which store your next plan actually reads (terraform init prints the configured backend; terraform state list works against it) before declaring the migration done.

Verification belongs in the same sitting as the migration. After init reports success, run terraform state list — a populated list proves the backend now holds your state — and a bare terraform plan to confirm no unexpected changes appear. Two working-copy files change meaning in the process, and both are worth knowing before an incident: .terraform/terraform.tfstate is not your state — it holds the directory's backend connection metadata, including any credentials supplied at init, which is one reason the whole .terraform directory stays out of version control — and the root terraform.tfstate is no longer consulted once the backend is configured. Harmless as leftovers, both are confusing during a 2 a.m. debug, so archive the root file after a successful migration.

One safety property worth stating plainly for incident contexts: none of this changes infrastructure. Init configures and migrates storage; only plan and apply touch real objects. Teams that fear backend migrations keep avoiding them and stay exposed to the far worse failures of local state — an avoidable fear, given what init actually does.

Where the migrated file lands — and the guarantees it gets there — depends on the storage service behind the backend type, which is the honest way to choose one.

A remote backend is a division of labor, and knowing which side of the line each guarantee falls on is what turns configuration into operations.

The storage service guarantees durability and usually encryption at rest. S3 objects are stored redundantly across devices with a durability design measured in nines; GCS and Azure Blob make equivalent promises. Encryption at rest is on by default in all three — with platform-managed keys — and every serious backend lets you bring your own: kms_key_id in the S3 backend, encryption_key in azurerm, CMEK in GCS. Bring-your-own-key matters when compliance says the platform operator must not be able to read your data, and it also gives you an off-switch: destroy the key, and the state becomes unreadable to everyone, including a compromised account with bucket access. The key's policy then joins the access model — the principal writing state needs encrypt and decrypt rights on that key — so an over-tight key policy surfaces as backend failures that bucket-policy debugging will never explain.

On locking, calibrate the promise precisely: "this backend supports locking" means the store rejects a second conditional write while a lock is held, and the guarantee is only as strong as the primitive behind it. That is why the lock configuration deserves the same review attention as the bucket policy; a backend without real locking is acceptable only for single-operator stacks where you accept the race.

You own access control, locking configuration, and secret hygiene. The bucket's policy, who may GetObject and PutObject, whether the lock table is writable by the whole org or only the platform team, whether CI assumes a scoped role — none of that arrives with the backend block. This is the partition interviewers probe: "isn't S3 state secure?" — durable and encrypted at rest, yes; access-controlled exactly as much as its IAM policy says, which is your design task.

Backend types roughly sort by who operates the storage:

The remote option deserves one note: HCP Terraform is a managed state-and-run service — state storage, locking, remote operations, and run history come as a product, at the price of putting your state in a vendor's custody and paying for the privilege. Plenty of teams run s3 for state and keep CI doing the executing; others want the audit trail a managed service provides. Neither is the default answer — the default answer is "who is responsible when this breaks at 2 a.m.?"

Whatever you pick, the workflow after setup is identical: init once per checkout, then plan and apply as before — except now every teammate and every CI run reads and writes the same locked store, which was the entire point. S3 paired with DynamoDB locking is the most common AWS answer by a wide margin, and it has enough specific detail — versioning, keys, the lock table's exact schema — to deserve its own topic: S3 Bucket and DynamoDB Locking Backend.