Terraform state locking as referred from Terraform State Locking documentation is a feature where Terraform will lock your state for all operations that could write state. This prevents others from acquiring the lock and potentially corrupting your state. Please remember not all backends support locking as mentioned in the Terraform State Locking documentation.

If we deploy infrastructure in Amazon Web Services (AWS), one of the backend that we can use is S3. As referred to S3 State Locking documentation, state locking is an opt-in feature in S3 backend. Previously, state locking only can be enabled via DynamoDB. But since Terraform v1.11.0, Terraform S3 native state locking is generally available, so that we can enable state locking in S3 or DynamoDB. However, as stated in S3 State Locking documentation, DynamoDB based locking is deprecated and will be removed in a future minor version.

In this blog, I will explain how to migrate Terraform state locking from DynamoDB to S3 native state locking. In the example, I will run Terraform workflow both from CI/CD and local workstation, only for demo purpose. I use Amazon CodeCatalyst to run my Terraform workflow in CI/CD pipeline. But you may use other CI/CD tool or maybe running locally just to follow along how S3 state locking works with some adjustment on your side.

Disclaimer: All contents written in this blog are solely my personal opinion and doesn’t represent my employer opinion

Prerequisites

Here are the prerequisites that needed to follow configurations discussed in this blog:

1. AWS account

2. Preconfigured S3 bucket and DynamoDB table that will be used for Terraform backend migration

Configuration steps

Reconfigure and migrate Terraform state

1. As an example, I have existing Terraform backend configuration with DynamoDB state locking as referred with argument dynamodb_table

terraform {
  backend "s3" {
    bucket         = "my-tfbucket"
    key            = "path/to/terraform.tfstate"
    region         = "ap-southeast-1"
    dynamodb_table = "my-tflocks"
    encrypt        = true
  }
}

2. Then I changed the structure of Terraform backend. I removed argument dynamodb_table and added argument use_lockfile and I set the value to true

terraform {
  backend "s3" {
    bucket       = "my-tfbucket"
    key          = "path/to/terraform.tfstate"
    region       = "ap-southeast-1"
    encrypt      = true
    use_lockfile = true
  }
}

3. Run terraform init to trigger backend changes after using S3 native state locking. In my case, I run it on my local with reason this just one time activity and I prefer to make it simple. But if you want to trigger the changes with different method, for example run in CI/CD, you may try it as well

4. First run of terraform init may be failed with error that stated that backend configuration is changed

✗ terraform init
Initializing the backend...
Initializing modules...
╷
│ Error: Backend configuration changed
│ 
│ A change in the backend configuration has been detected, which may require migrating existing state.
│ 
│ If you wish to attempt automatic migration of the state, use "terraform init -migrate-state".
│ If you wish to store the current configuration with no changes to the state, use "terraform init -reconfigure".

5. Re-run terraform init, add args -reconfigure so that terraform will reconfigure and migrate your backend with new configuration that used S3 native state locking

✗ terraform init -reconfigure
Initializing the backend...

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.
Initializing modules...
Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Using previously-installed hashicorp/aws v5.47.0

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

6. For full context of code example, you can check this file inside this directory

Test Terraform S3 state locking

In this blog, I simulate Terraform S3 state locking by running multiple Terraform plan in the same period. One is ran in CI/CD, in my case is Amazon CodeCatalyst. And the other one is ran from my local to simplify testing process. But you may test with different test case and in real environment, more likely We will experience running multiple Terraform plan from multiple CI/CD pipelines.

1. Here is the example when I ran terraform plan in my CI/CD but in the same time I also ran terraform plan from my local workstation. Terraform plan will be failed

2. Terraform plan got error message: Error acquiring the state lock

Error: Error acquiring the state lock

Error message: operation error S3: PutObject, https response error
StatusCode: 412, RequestID: 12345ABCDE, HostID:
1a2b/3c4d/5e==,
api error PreconditionFailed: At least one of the pre-conditions you
specified did not hold
Lock Info:
ID:        1a2b3c4d5e-3ec1-1f71-9cdd-1a2b3c4d5e
Path:      path/to/terraform.tfstate
Operation: OperationTypePlan
Who:       lanandra@Luthfis-MacBook-Pro.local
Version:   1.11.2
Created:   2025-03-22 18:56:18.872219 +0000 UTC
Info:


Terraform acquires a state lock to protect the state from being written
by multiple users at the same time. Please resolve the issue above and try
again. For most commands, you can disable locking with the "-lock=false"
flag, but this is not recommended.

3. In this case, We can verify that Terraform state locking in S3 has been working as it will prevent multiple terraform plan run and overriding the state in the same period

Summary

We have reached the last section of this blog. Here are some key takeaways that can be summarized:

1. Terraform state locking is a feature where Terraform will lock your state for all operations that could write state and prevent others from acquiring the lock and potentially corrupting your state

2. If we are using S3 as our Terraform backend, previously state locking only support DynamoDB but since Terraform v1.11.0, state locking also support S3 native state locking

3. DynamoDB based locking is deprecated and will be removed in a future minor version

Please comment if you have any suggestions, critiques, or thoughts.

Hope this article will benefit you. Thank you!