Skip to main content

Cloud and deployment · Advanced · 18 min

How to Store Terraform 1.17 State Remotely in an S3 Bucket

By Padding · Updated 15 Nov 2026
Terraform 1.17 · AWS S3

You will create a private, versioned and encrypted S3 bucket for Terraform state, point Terraform 1.17 at it with native S3 locking, move an existing local state into it, and delete the bucket correctly when you finish.

On this page

Terraform keeps a record of what it has built, called the state. By default that record is a file named terraform.tfstate in your working folder. That is fine on your own laptop and a problem for everything else. A teammate cannot see it, a CI job does not have it, and if the laptop dies the link between your code and your real infrastructure goes with it. The file can also hold secrets in plain text.

A remote backend stores the state somewhere shared and safe. For AWS users the usual choice is an S3 bucket. In this tutorial you create that bucket with the settings that matter (private, versioned, encrypted), turn on S3's own locking so two people cannot apply at once, move an existing local state into it, and tear it all down.

This costs money, though not much. A state file is a few kilobytes, so storage and requests for a small team usually cost well under a dollar a month. S3 bills for every version of every object you keep, and a bucket you forget about keeps costing. See aws.amazon.com/s3/pricing/ for current prices, set a budget alert in AWS Billing, and do the last step when you are done.

Step 1 · Set a name and a region

The bucket name must be unique across all of AWS, so build it from your account number. eu-west-1 is only an example region:

Bash
export AWS_REGION=eu-west-1
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
export BUCKET=tfstate-$ACCOUNT_ID-demo
echo "$BUCKET in $AWS_REGION"

Keep this terminal open until the end. The variables disappear when it closes.

Step 2 · Create the bucket and lock it down

The bucket that holds your state cannot itself be created by the Terraform that uses it, since that Terraform needs the bucket to exist first. Create it once with the AWS CLI. Outside us-east-1, S3 needs the region repeated as a location constraint; if your region is us-east-1, leave out the --create-bucket-configuration line and its backslash:

Bash
aws s3api create-bucket --bucket "$BUCKET" --region "$AWS_REGION" \
  --create-bucket-configuration LocationConstraint="$AWS_REGION"

Now apply three protections. First, block every form of public access:

Bash
aws s3api put-public-access-block --bucket "$BUCKET" \
  --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

Second, turn on versioning. Every write keeps the previous copy, so a bad apply or an accidental delete can be undone by restoring an older version. The Terraform documentation recommends this for state buckets:

Bash
aws s3api put-bucket-versioning --bucket "$BUCKET" \
  --versioning-configuration Status=Enabled

Third, set default encryption, so state is encrypted at rest even if a client forgets to ask. This uses S3-managed keys (SSE-S3). If your organisation requires its own keys, use a KMS key instead and give Terraform permission to use it:

Bash
aws s3api put-bucket-encryption --bucket "$BUCKET" \
  --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"},"BucketKeyEnabled":true}]}'

Versioning keeps every old copy forever unless you say otherwise, and state files change on every apply. Add a lifecycle rule that deletes versions 90 days after they stop being the current one. The current state is never touched by this rule:

Bash
aws s3api put-bucket-lifecycle-configuration --bucket "$BUCKET" \
  --lifecycle-configuration '{"Rules":[{"ID":"expire-old-state-versions","Status":"Enabled","Filter":{"Prefix":""},"NoncurrentVersionExpiration":{"NoncurrentDays":90}}]}'

Check it worked

Read the settings back:

Bash
aws s3api get-public-access-block --bucket "$BUCKET"
aws s3api get-bucket-versioning --bucket "$BUCKET"
aws s3api get-bucket-encryption --bucket "$BUCKET"

The first shows all four settings as true, the second shows "Status": "Enabled", and the third shows AES256.

Troubleshooting

BucketAlreadyExists means someone else has that name; add something of your own to it. IllegalLocationConstraintException means the region in --create-bucket-configuration does not match --region. AccessDenied on any of these means your user lacks the S3 permission for that action, so ask whoever manages your AWS account.

Step 3 · Create a small project with local state

You need something to store. Make a folder with a configuration that creates no cloud resources, so the only thing at stake is the state:

Bash
mkdir tf-remote-demo
cd tf-remote-demo
cat > main.tf <<'HCL'
terraform {
  required_version = ">= 1.17.0"

  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.9"
    }
  }
}

resource "random_pet" "name" {
  length = 2
}

output "pet" {
  value = random_pet.name.id
}
HCL
terraform init
terraform apply

Type yes when asked. The state is now a local file, terraform.tfstate, and terraform output pet prints the generated name. Remember it, since it should be the same after the move.

Step 4 · Point Terraform at the bucket

Add a backend block. Create backend.tf next to main.tf, replacing the bucket name and region with your own values:

HCL
terraform {
  backend "s3" {
    bucket       = "tfstate-123456789012-demo"
    key          = "demo/terraform.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true
  }
}

What each line does:

  • key is the object path of the state inside the bucket. Give every project its own key, such as network/terraform.tfstate, so projects do not share state.
  • encrypt = true makes Terraform request server-side encryption for the state and lock objects on each write, on top of the bucket default.
  • use_lockfile = true turns on S3 native locking. Terraform writes a small lock object next to the state, named like the key with .tflock added, and refuses to run if another process holds it. The older approach used a DynamoDB table. The Terraform 1.17 documentation marks dynamodb_table as deprecated and to be removed in a future minor version, so new setups should not create a table.

A backend block cannot use variables. The bucket name is not a secret, so writing it in the file is fine. Never write AWS access keys here: Terraform finds credentials the same way the AWS CLI does, from your signed-in profile or environment.

Step 5 · Move the state

Run init again. Terraform sees the new backend and asks whether to copy the existing state:

Bash
terraform init -migrate-state

Answer yes when it asks to copy the state to the new backend. Keep the old local file until you have checked the result, because it is your only copy if something is wrong.

Check it worked

List the bucket and compare the output:

Bash
aws s3 ls "s3://$BUCKET/demo/"
terraform output pet
terraform plan

The listing shows terraform.tfstate. The name from terraform output pet is the one you noted earlier, and the plan reports No changes. The .tflock object is not listed while nothing is running, because Terraform removes it when a run finishes.

Once you are sure, delete the old local state files so nobody uses them by mistake:

Bash
rm terraform.tfstate terraform.tfstate.backup

If a run is killed and leaves a lock behind, Terraform tells you the lock ID. Clear it with terraform force-unlock <lock-id>, and only after you are certain nobody is running.

Step 6 · Grant the least permission

Do not hand every teammate full S3 access. The Terraform documentation lists what the backend needs. With use_lockfile on, the policy for a user or role is this one, with your bucket name and key in place of the examples:

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::tfstate-123456789012-demo"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::tfstate-123456789012-demo/demo/terraform.tfstate"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::tfstate-123456789012-demo/demo/terraform.tfstate.tflock"
    }
  ]
}

The lock object needs s3:DeleteObject because Terraform removes it at the end of every run. The state object does not, because Terraform never deletes it. If you use a KMS key, the principal also needs kms:Encrypt, kms:Decrypt and kms:GenerateDataKey on that key. Attach the policy to an IAM role your people assume, and never share one user's keys.

Step 7 · Tear it all down

Delete things in this order. Warning: the last commands delete your state history permanently. Do them only when nothing uses this state.

First let Terraform remove what it manages. This project only generated a name, so nothing in AWS is affected:

Bash
terraform destroy

A versioned bucket cannot be deleted while it holds any version or delete marker, and aws s3 rb --force only removes current objects. List every version and marker, then delete them in one call. State buckets are small, and delete-objects takes up to 1,000 keys at a time. If the bucket has no versions at all, the list is empty and delete-objects fails with a malformed-request error. In that case skip it and go straight to delete-bucket:

Bash
aws s3api list-object-versions --bucket "$BUCKET" --output json \
  | jq '{Objects: ([.Versions[]?, .DeleteMarkers[]?] | map({Key: .Key, VersionId: .VersionId})), Quiet: true}' \
  > delete.json
aws s3api delete-objects --bucket "$BUCKET" --delete file://delete.json
aws s3api delete-bucket --bucket "$BUCKET" --region "$AWS_REGION"
rm delete.json

Check it worked

Bash
aws s3api head-bucket --bucket "$BUCKET"

It fails with a 404 or Not Found error, because the bucket no longer exists. Then remove the project folder, since its backend now points nowhere:

Bash
cd ..
rm -rf tf-remote-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.