{"id":637,"date":"2025-03-25T04:23:18","date_gmt":"2025-03-25T04:23:18","guid":{"rendered":"https:\/\/blog.ngocha.biz\/?p=637"},"modified":"2025-03-25T04:23:18","modified_gmt":"2025-03-25T04:23:18","slug":"terraform-state-locking-with-s3","status":"publish","type":"post","link":"https:\/\/blog.ngocha.biz\/?p=637","title":{"rendered":"Terraform State Locking with S3 Without DynamoDB"},"content":{"rendered":"

In this blog we will look at,<\/p>\n

    \n
  1. Need for Terraform State Locking<\/li>\n
  2. State Locking With DynamoDB<\/li>\n
  3. State Locking with S3 without DynamoDB<\/li>\n
  4. When to use DynamoDB and when to use s3 state locking.<\/li>\n<\/ol>\n

    Before we get into the details, let’s understand some basics.<\/p>\n

    So what is state lock?<\/p>\n

    When we look at real-world Terraform implementations, most Terraform infrastructure deployments happen through CI\/CD systems.<\/p>\n

    This means that, at any given point in time, the same Terraform state could be accessed by different CI\/CD jobs. Also, multiple developers could access the same state file during the development process.<\/p>\n

    If multiple terraform process uses the same state file, it could lead to conflicts and inconsistencies in the state file<\/strong>. (race conditions).<\/p>\n

    So we need state locking to ensure one terraform process modifies the resource at a time.<\/p>\n

    It is like putting a “do not disturb<\/strong>” sign on your state file.<\/p>\n

    Organisations usually store the Terraform state file in an Amazon S3 bucket. This provides a central place that’s durable and accessible for the team<\/p>\n

    Along with S3, a DynamoDB table is set up to manage locks.<\/p>\n

    State Locking With DynamoDB<\/h2>\n

    In AWS environment, the standard approach is using DynamoDB for state locking<\/a>.<\/p>\n

    Here is how DynamoDB<\/strong> state locking works.<\/p>\n

      \n
    1. When Terraform wants to modify a resource, it acquires a lock in DynamoDB<\/strong> by creating an entry in DynamoDB<\/strong> table with a specific lock ID (e.g., \u201clock-abc123\u201d).<\/li>\n
    2. If the lock is successful, terraform gets access to the state file from s3<\/li>\n
    3. Once all the resource modifications are done, Terraform updates the state file and releases the DynamoDB<\/strong> lock.<\/li>\n<\/ol>\n

      For example, when developer X<\/strong> executes the terraform code, DynamoDB will lock the state, and developer Y<\/strong> should wait until the execution is completed.<\/p>\n

      Also, DynamoDB has a timeout period to prevent permanent lock-outs<\/strong>. This is helpful in cases where a lock is acquired by terraform, and it holds the lock due to abnormal process termination.<\/p>\n

      The following image shows the Terraform s3 backend workflow with DynamoDB locking feature.<\/p>\n

      \"\"<\/figure>\n

      State Locking With s3 Lockfile ( Experimental Feature)<\/h2>\n

      With S3 now supporting conditional writes<\/strong><\/a>, it can handle concurrency and state locking.<\/p>\n

      Conditional writes allow S3 to prevent overwrites unless certain conditions are met. This ensures stronger consistency when multiple processes attempt to update the same S3 object.<\/p><\/blockquote>\n

      For example:<\/p>\n

      – You can update an object only if it has not changed since the last read.<\/p><\/blockquote>\n

      – This prevents race conditions where two Terraform processes might overwrite the same state file.<\/p><\/blockquote>\n

      The Terraform backend configuration that uses DynamoDB for state looks like this:<\/p>\n

      \"\"<\/figure>\n

      You can replace DynamoDB with an s3 lock using use_lockfile<\/code> a flag as shown below. (introduced as experimental in Terraform 1.10<\/a>)<\/p>\n

      \"\"<\/figure>\n

      You can copy and add the below backend block in your Terraform code to use the S3 lock.<\/p>\n

      terraform {\n  backend \"s3\" {\n    bucket = \"my-terraform-state-bucket\"\n    key    = \"terraform\/state.tfstate\"\n    region = \"us-west-1\"\n    use_lockfile = true\n   }\n}<\/code><\/pre>\n
      In the above block, update your bucket name, key structure, and region.<\/p>\n
      Here is how it works.<\/p>\n
      Terraform creates a .tflock<\/code> file in S3 before modifying the state to prevent conflicts.<\/p>\n
      It checks for an existing lock and waits or fails if another process is running. S3\u2019s conditional writes<\/strong> enforce locking.<\/p>\n
      When you apply the Terraform script, you can see a .tflock file<\/code> in S3, as shown below.<\/p>\n
      \"\"<\/figure>\n
      Once done, Terraform deletes the lock file.<\/p>\n
      If another user tries to apply, they will get an error similar as shown below.<\/p>\n
      \"\"<\/figure>\n
      Best Practices<\/h2>\n
      Following are some of the best practices you can follow while using s3 as remote state storage.<\/p>\n
        \n
      1. Enable Versioning on the S3 Bucket: <\/strong>Turn on versioning for the S3 bucket. This keeps track of all changes to the state file, allowing you to recover previous versions if something goes wrong<\/li>\n
      2. Set Up Proper Access Controls:<\/strong> Use AWS IAM policies to restrict who can read or write to the S3 bucket and DynamoDB table. This ensures that only authorized team members can make changes.<\/li>\n
      3. Encrypt the State File:<\/strong> Enable encryption for the state file stored in S3. This protects sensitive information from unauthorized access.<\/li>\n
      4. Handle Locking Issues Carefully: <\/strong>If a Terraform process ends unexpectedly, it might leave a lock in place. Terraform provides a command to manually remove such locks, but use it cautiously to avoid conflicts.\u200b<\/li>\n
      5. Organize State Files Clearly:<\/strong> For different projects or environments (like development and production), use separate state files. This reduces the risk of accidental changes affecting the wrong environment.<\/li>\n<\/ol>\n
        Conclusion<\/h2>\n
        Replacing DynamoDB with use_lockfile<\/code> simplifies your Terraform setup but comes with some trade-offs. Also, it is an experimental feature.<\/p>\n
        So when should you consider using use_lockfile?<\/code><\/p>\n