Locks and Concurrency

Terrateam’s locks and concurrency feature ensures that changes to your infrastructure are safely applied by preventing concurrent modifications to the same resources. Locks guarantee that only a single change to a resource can be applied in a pull request at any given time, avoiding conflicts and maintaining consistency between your Terraform configuration and the real-world state of your infrastructure.

Why are locks important?

Suppose Alice and Bob both open pull requests that modify the same Terraform resource. Without locks, both could apply their changes independently, leading to a situation where the real infrastructure state no longer matches the code in your main branch. Locks prevent this by ensuring only one change can be applied at a time.

    
flowchart TD
  T1["Alice"] --> A1["Alice PR<br>plan"]
  T2["Bob"] --> B1["Bob PR<br>plan"]

  A2["Alice PR<br>apply (acquire lock)"]
  A3["Alice PR<br>infra update"]
  A4["Alice PR<br>release lock"]

  B2["Bob PR<br>apply (blocked)"]
  B3["Bob PR<br>re-plan"]
  B4["Bob PR<br>apply (acquire lock)"]
  B5["Bob PR<br>infra update"]
  B6["Bob PR<br>release lock"]

  A1 --> A2 --> A3 --> A4 --> B3
  B1 --> B2
  B3 --> B4 --> B5 --> B6

Concurrent Collaboration

When multiple team members are working on the same Terraform project, locks play a crucial role in coordinating their efforts and preventing conflicting changes.

Coordination

When a team member applies a change to a resource in a pull request, Terrateam acquires a lock on that resource. This lock ensures that no other team member can concurrently apply changes to the same resource, preventing conflicts and inconsistencies.

Invalidation

If a team member attempts to apply a change to a resource that is already locked by another apply operation, Terrateam will deny the change. Once the lock is released, the change can be re-planned and applied.

Consistency

By preventing concurrent modifications to the same resources, locks help maintain consistency between your Terraform configuration and the actual state of your infrastructure.

What is a Lock?

A lock is a mechanism that ensures only a single change to a resource can be applied in a pull request at any given time. When a lock is acquired on a resource, changes to that resource in other pull requests cannot be concurrently applied.

When is a Lock Acquired?

By default, a lock is acquired when executing an apply operation or merging a pull request without applying the changes. The lock is acquired on the dirspaces targeted in the pull request.

When is a Lock Not Acquired?

If a pull request is created but never applied or merged, no lock is acquired. Locks are only acquired when executing an apply or merging a pull request without applying the changes.

Example: Locking in Action

Consider a pull request with changes in dir1 and dir2 (using only the default workspace):

    
flowchart TD
  PR["PR opened: changes in <br>dir1, dir2"]
  Plan["terrateam plan"]
  Apply["terrateam apply dir:dir1"]
  Locks["Locks acquired: <br>(dir1, default), (dir2, default)"]
  PR --> Plan --> Apply --> Locks

The pull request now owns locks on the following dirspaces:

(dir1, default)
(dir2, default)

When is a Lock Released?

A lock is released when a change has been both applied and merged.

Unlocking

In certain scenarios, you may want to force an unlock. To explicitly remove a lock, comment terrateam unlock in the pull request that owns the lock.

Executing terrateam unlock only applies to locks acquired prior to performing the unlock.
Performing a merge or apply after an unlock will acquire any necessary locks again.

Locking Policies

The lock_policy option instructs Terrateam under what situations it should acquire a lock. It can be set as a top-level key in your Terrateam configuration file, which applies to every directory, and it can be set on an individual workflow entry, which overrides the top-level value for the directories that match that workflow.

Policy	Description	Recommended Use Case
`strict`	Acquire a lock if a user comments `terrateam apply` or the change is merged. Lock is released when the other action is performed.	Production environments (default)
`apply`	Acquire a lock only if the directory has been applied in Terrateam. Lock is released once the change is merged.	Standard apply/merge workflows
`merge`	Acquire a lock only if the directory has been merged. Lock is released when the change is applied.	Dev/playground branches
`none`	Never acquire a lock.	Special cases, not recommended

For example, to make apply the policy for the whole repository while keeping strict for production directories:

lock_policy: apply

workflows:
  - tag_query: dir:production
    lock_policy: strict

Best Practices

When working with locks in a team environment, consider the following best practices:

Communicate and coordinate with your team members when working on shared resources to avoid conflicts and delays.
Regularly review the lock status and address any long-standing locks that may be blocking other team members’ progress.
If necessary, use Terrateam’s override mechanisms (e.g., terrateam unlock) judiciously and with caution, ensuring that all team members are aware of the implications.
Establish clear guidelines and processes within your team for managing locks, resolving conflicts, and ensuring smooth collaboration.