How Terraform state lock works?

Play this article

Hola!! 🙋🏻‍♂️

𝗧𝗼𝗽𝗶𝗰 — State Lock Mechanism ⚙️
𝗦𝗲𝗿𝗶𝗲𝘀 — “Do you know” 💡

Here we will not discuss the setup of state management in terraform. There are quite a few amazing blogs out there on this topic and here is a comprehensive one 👇

State Locking Mechanism with S3 and DynamoDb

Prerequisites -

What are — State Management, Remote Backend & State Locking?

In this blog, we will see how exactly state locking happens. What kind of data gets stored in DynamoDB?

To illustrate this process, consider the following scenario with two projects: “project-1” and “project-2.” Both projects have their Terraform configurations, including and files with the same backend.

Execution Sequence:

  1. Project-1: We initiate terraform apply from "project-1," which includes making infrastructure changes.

  2. State Lock Acquired: While “project-1” is running, it acquires a state lock to ensure exclusive access to its state.

  3. When we run terraform apply, the first thing it does is start acquiring state lock. So that no other developer can make the changes at the same time.

  4. We will stop here to intentionally create the situation in order to understand the process.

  5. Project-2: Meanwhile, we start a terraform plan in "project-2" for their own set of infrastructure modifications.

  6. Lock Request by Project-2: “Project-2” attempts to acquire a state lock but encounters an “Error acquiring the state lock” because it cannot proceed until the lock held by “project-1” is released.

  7. DynamoDB Table: Let’s see what actual data is getting stored in dynamoDB during the process.

    The first item contains this

    This LockID: Digest (key) contains a checksum or hash (as you can see the value above☝️) of the state file content. It ensures that only one Terraform instance can change the state at a time (to prevent conflicts and race conditions).

  8. Project-1 Completion: Once “project-1” completes its apply operation, it releases the state lock, allowing “project-2” to proceed with its terraform plan and, subsequently, apply its changes.

    You will get this message at the end.

    Now run terraform plan in project-2

    First, as we know, it will acquire a state lock and as of now, there is no state lock in use so this will get locked. Then it will execute the command without getting any error and release the lock after the execution as you can see above.☝️

    Let’s check the dynamoDB table once again.

    As we can see, it will automatically delete the second item containing the locked state's metadata as there is no lock state in use. Only the hash value will be shown.

  9. S3 Bucket: This will contain the traditional terraform state .tfstate file. Developers can update this without conflicts and drifts using state locking.

Bonus Tip: 💡

It is highly recommended that you enable Bucket Versioning while creating an S3 bucket to allow for state recovery in the case of accidental deletions and human error.

Thanks for reading our blog. Feel free to hit me up for any AWS/DevOps/Open Source-related discussions.

Manoj Kumar — LinkedIn.

Poonam Pawar — LinkedIn