Explain Terraform state locking in detail. What happens during a lock, how do you handle lock issues, and what are the risks of not using locking?

Question

Accepted Answer

State locking prevents multiple Terraform processes from modifying the same state simultaneously. Without locking, concurrent operations can corrupt state, create duplicate resources, or cause data loss.

When you run terraform plan or terraform apply, Terraform attempts to acquire a lock on the state before reading or modifying it. If successful, Terraform holds the lock until the operation completes, then releases it.

For AWS with an S3 backend, locking uses DynamoDB. Terraform creates a lock record in the specified DynamoDB table with a unique ID. The record includes the operation, who is running it, when it started, and other metadata. Other Terraform processes check for this record and wait if one exists.

During a lock, several things happen in sequence. First, Terraform attempts to write a lock record to DynamoDB. If the record already exists, Terraform waits or exits with an error depending on the operation. Second, Terraform reads the state file from S3. Third, Terraform performs the requested operation, modifying resources as needed. Fourth, Terraform writes the updated state back to S3. Finally, Terraform deletes the lock record from DynamoDB.

If the lock fails to release, perhaps due to a crashed process or network issue, subsequent operations will fail with a lock error. The error message includes the lock ID and information about who holds it.

To handle lock issues, you have several options. First, wait for the lock to expire if your backend supports automatic expiration. Second, contact the person holding the lock to confirm they are not running an operation. Third, use terraform force-unlock with the lock ID to manually release it. This command is dangerous and should only be used when you are certain no operation is in progress.

Force-unlock risks include state corruption if an operation is actually running, lost changes if the locking process was about to write state, and potential resource duplication if the apply is interrupted midway.

The risks of not using locking are severe. Race conditions can occur when two people apply at the same time. Both might read the same initial state, plan changes, and attempt to create the same resources. This can result in duplicate infrastructure, failed operations, or state that does not match reality.

State corruption is another risk. If two processes write state simultaneously, one write might overwrite the other, losing track of resources. These orphaned resources continue running and incurring costs but are invisible to Terraform.

Best practices for state locking include always configuring a lock table for team environments, monitoring for long-held locks that might indicate stuck processes, training team members to never force-unlock without investigation, and using timeouts in CI/CD pipelines so failed jobs do not hold locks indefinitely.

Some backends like Terraform Cloud handle locking automatically with additional features like run queuing. If you are using S3, ensure your DynamoDB table has appropriate capacity for your team size.