docs: safely disable atlantis locking

[nitrocode]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request. Searching for pre-existing feature requests helps us consolidate datapoints for identical requirements into a single place, thank you!
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.
• If you are interested in working on this issue or have submitted a pull request, please leave a comment.

---

• [x] I'd be willing to implement this feature (contributing guide)

Describe the user story

Atlantis locking is probably the least favorite feature among devs and blocks users often. I'm sure it's useful as a default. It would be good to know the configuration needed to safely disable it without compromising the workflow.

Describe the solution you'd like

Document what configuration is needed to safely disable locking without compromising workflows

Can atlantis locking be safely disabled if using the following?

• merge checkout strategy (branch will always be merged with the default branch prior to plan/apply)
• terraform state locking such as with dynamodb
• skipping state lock on plan and not skipping it on apply

Workflow scenario: simultaneous plan

• since planning at the same time is safe, -lock=false can be set in a custom workflow for plan

Workflow scenario: simultaneous apply

• 2 PRs try to apply
• due to terraform state locking, only one is able to apply

Workflow scenario: stale plan

• PR 1 checks out dir global
  • PR adds tag env to some resource
  • atlantis uses merge strategy to merge code from main to feature branch
  • atlantis auto plans
• PR 2 checks out the same dir and workspace
  • PR changes instance type to t3.small
  • atlantis uses merge strategy to merge code from main to feature branch
  • atlantis auto plans
• PR 2 is approved and atlantis apply comment applies the tf and merges PR 2 to main

• PR 1 plan is now stale

  If atlantis apply is run on pr 1 now, the plan should say that it is stale and the plan needs to be rerun.

  Error: Saved plan is stale

  A new atlantis plan or commit will trigger the merge from main before auto planning

One caveat worth exploring from @apparentlymart

https://gist.github.com/apparentlymart/657885e730d1e5abc6ea#stale-plan-files

One particular case where Terraform encourages mistakes is that when plan produces an empty diff the tfplan file is not updated to reflect that empty diff, leaving behind the result of some previous plan. However, since Terraform exited successfully the user (or some automated system looking at the exit status) is often tempted to run terraform apply tfplan anyway, at which point the stale plan is re-applied.

This method would also allow HA out of the box without having to use a separate redis cluster for locking (see https://github.com/runatlantis/atlantis/pull/2491).

Describe the drawbacks of your solution

No idea which PRs are modifying the same project

Describe alternatives you've considered

None

[nitrocode]

Some users like @brandon-fryslie have been able to disable locking successfully.

https://github.com/runatlantis/atlantis/pull/3649#issuecomment-1887037135

[nitrocode]

I disabled locking successfully since Jan 2024 and have not noticed any issues.

[brandon-fryslie]

I disabled both Atlantis and Terraform locks in dev (init/plan only) and have seen 0 problems whatsoever. The repo has multiple PRs per day. I was keeping on top of it, but I took some time off and there are 30+ open PRs now. Just to give you an idea of how much traffic this repo gets. If there were issues we'd likely have seen them.

We also have Atlantis parallelization enabled (using a "fake workflow" hack, by setting the workflow in Atlantis config then overriding the built-in commands for init/plan/apply to skip workflow switching. this gives us the folder structure needed for Atlantis parallelization without requiring us to use tf workflows). It's not uncommon to have a PR run 20-30 Atlantis projects. And no issues with locks disabled on both Atlantis and Terraform, for non-destructive operations.

Obviously you'll want locks enabled for apply and anything else that could possibly change state or resources.

[nitrocode]

Very cool. I can say the same still, no issues after 7 months. Devs are very happy and PRs get merged quickly and painlessly.

I'll add a document for this in the website.

[nitrocode]

cc: @jamengual @GenPage