S3 Native State Locking in Terraform

Overview

Starting from Terraform 1.10.0, you can now manage state file (.tfstate) locking using only an S3 bucket as your backend storage, without requiring DynamoDB. This is a significant improvement that simplifies infrastructure management and reduces operational overhead.

Architecture for S3 Native State Locking

1 Before this feature was introduced, you needed to configure and manage a DynamoDB table for state file locking. With the new S3 Native State Locking feature, DynamoDB is completely eliminated, making the infrastructure more intuitive and reducing operational complexity.

Prerequisites

  • Terraform CLI (v1.10.0 or higher)
  • AWS account with S3 bucket access
  • Basic understanding of Terraform state management

Important Notes

Version Requirements

  • S3 Native State Locking is only available in Terraform v1.10.0 and above
  • Using an older version of Terraform CLI will not support this feature

Configuration Steps

1. Update Terraform Version

If you’re using tfenv, you can install and switch to Terraform 1.10.4:

# Install Terraform 1.10.4
tfenv install 1.10.4
tfenv use 1.10.4

# Verify the version
terraform version

2. Configure Backend

Update your backend.tf file to use the new locking mechanism:

terraform {
  backend "s3" {
    encrypt = true
    region  = "ap-northeast-2"
    acl     = "bucket-owner-full-control"
    bucket  = "your-bucket-name"
    key     = "path/to/terraform.tfstate"

    # Enable S3 native state locking
    # S3 state lock feature is only available in Terraform CLI version 1.10.0 and above.
    use_lockfile = true
  }
}

Note: The use_lockfile option is currently experimental (as of January 22, 2025) and may undergo significant changes in future releases.

3. Initialize Terraform

After updating the backend configuration, reinitialize Terraform:

terraform init -reconfigure

How It Works

The new locking mechanism:

  • Creates a lock file (e.g., terraform.tfstate.tflock) alongside your state file
  • Uses Amazon S3’s Conditional Writes feature for locking
  • Automatically manages lock file creation and deletion
  • Doesn’t require S3 Object Lock feature to be enabled

Verification

You can verify the locking mechanism by:

  1. Running terraform plan or terraform apply
  2. Checking the S3 bucket for the lock file:
aws s3 ls s3://your-bucket-name/path/to/state/

You should see:

  • terraform.tfstate - Your state file
  • terraform.tfstate.tflock - The lock file (created during operations)

2

After the operation completes, the lock file will be automatically deleted.

Benefits

  1. Simplified Infrastructure: No need to manage DynamoDB tables
  2. Reduced Costs: Eliminates DynamoDB costs
  3. Better Maintainability: Fewer components to manage
  4. Native Integration: Direct integration with S3

Conclusion

S3 Native State Locking is a significant improvement in Terraform’s state management capabilities. It simplifies the infrastructure while maintaining the same level of safety for concurrent operations. As this feature matures, it will likely become the standard approach for state locking in Terraform.

Remember to stay updated with the latest Terraform version to take advantage of this and other new features.