Terraform State - Native S3 Locking

Terraform has many popular mechanisms for storing its state file. While I have grown quite fond of HCP Terraform, there are occasional scenarios where I want to use S3 backend to hold my Terraform state files.

Best practice when sharing a state file among multiple parties is to have a locking mechanism, to avoid concurrent writes from corrupting the Terraform state. This prevents 2 parties from clobbering each other if they happen to be working on the same infrastructure at the same time.

Starting in Terraform v1.10 the S3 backend features S3 native state locking. Prior to this feature state file lock setups required access to a DynamoDB table - which can be completely foregone now!

How to use it?

Lets start by creating a S3 bucket that has the required settings

It is common to create the S3 state file bucket outside of Terraform. However, you can create the bucket with Terraform, its just generally not advised. Example HCL below.

export BUCKET_NAME="<your bucket name>"
export REGION="us-east-1"

aws s3api create-bucket \
    --bucket $BUCKET_NAME \
    --region $REGION

aws s3api put-bucket-versioning \
    --bucket $BUCKET_NAME \
    --versioning-configuration Status=Enabled

aws s3api put-object-lock-configuration \
    --bucket $BUCKET_NAME \
    --object-lock-configuration '{"ObjectLockEnabled": "Enabled"}'        

Using the bucket

Create a new backend.tf file (or add this block to an existing .tf file). Make sure you fill in the bucket name!

Below we use the parameter use_lockfile which is an experimental feature that enforces using the s3 buckets lock file

terraform {
  backend "s3" {
    bucket       = <bucket name>
    key          = "backend/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}        

Wrapping up

For a deep dive on this feature I recommend you read through the initial PR.

Optional: Create bucket using Terraform

resource "aws_s3_bucket" "backend" {
  bucket              = var.bucket_name
  object_lock_enabled = true
}

resource "aws_s3_bucket_versioning" "backend" {
  bucket = aws_s3_bucket.backend.id
  versioning_configuration {
    status = "Enabled"
  }
}