Collaborative Terraform with Atlantis

1. Collaborative Terraform
with Atlantis
2023-06-30 @ Let’s Code meetup

2. Introduction
Ferenc Kovács
DevOps guy from Budapest, Hungary
Infrastructure Tech Lead at IBM Budapest Lab
FLOSS enthusiast

3. What is Terraform?
“Terraform is an infrastructure as code
tool that lets you build, change, and
version cloud and on-prem resources
safely and efficiently.”

4. No but really, what is Terraform?
“Random” IaC code executed on
someone’s laptop, then not properly
merged to git.

5. What is the problem with local apply?
- Prone to “works on my machine” issues
- Diverging tf and provider versions.
- Diverging tf/environment vars.
- Lack of visibility/auditability
- Who applied what/when and what was the
output/error?
- People need access to the remote state.
- People need credentials for the providers.

6. What is the problem with local apply?
- Even if you do code reviews in Github it is
cumbersome to copy/paste plan outputs and
apply can always fail regardless(we are
dependent not just our code correctness but
the state/availability of the provider APIs).

7. The solution
We need a predictable, trusted and audited
environment where terraform actions can be
executed and preferably integrated with VCS.

8. Terraform Cloud/Enterprise
- It’s a solution from Hashicorp, it is tightly integrated with
terraform itself.
- Allows you to use remote terraform execution and it
allows you to centrally manage the env
variables/secrets.
- Requires you to store the remote state there, but they
have a self-hosted Enterprise install($$$).
- The free-tier plan is really nice, if you have max 5
people using it and you don’t mind using a closed
source third party solution.

9. Env0
- It is a more complex solution, supports most of the
available IaC tools (TF, CF, Pulumi, etc.).
- This is also a closed source 3rd party, but as part of
their Business/Enterprise offering they also provide
Self-hosted agents which allows you to keep your
workload and secrets on-prem.
- They have nice documentation comparing their offering
to TF Cloud and Atlantis.
- No free plan, only free-trial.

10. Garden.io
- It is a more complex solution, supports most of the
available IaC tools (TF, CF, Pulumi, etc.).
- It makes it possible to declare all of your heterogen
stack declaration/pipelines in an uniform way and chain
them together. Creating a new environment from a
single command.
- The Garden core tool is open-source, but the
centralized execution environment is a paid (closed
source) feature.
- They also have a self-hosted Enterprise offering.

11. Scalr
- They only focus on Terraform, much simpler than Env0
or Garden.
- They also provide local agents as part of the enterprise
offering, but you can’t host your secrets for yourself.
- They have a free plan of 50 runs per month, max 50
users and max 100 workspaces.

12. Spacelift
- It is a more complex solution, supports most of the
available IaC tools (TF, CF, Pulumi, etc.).
- This is also a closed source 3rd party, but as part of
their Enterprise offering they also provide a hybrid-saas
and a self-hosted option which allows you to keep your
workload and secrets on-prem.
- They have nice documentation comparing their offering
to TF Cloud and Atlantis.
- They have a forever free plan for 2 users.

13. But what about Atlantis?
- https://runatlantis.io/
- It is mostly for Terraform (but stuff like Terragrunt and
cdktf are also supported).
- It is a truly open-source solution, with a permissive
Apache license.
- Because it’s open-source there is a bunch of integration
with all kind of tools and services.
- It has an extendable workflow system, and if something
is still lacking you can send a Pull Request.
- But you have to configure and host it for yourself.

14. (Average)Atlantis workflow
1. You create a Pull Request with your changes.
2. You “atlantis plan” (if autoplan is not enabled), atlantis
executes terraform init & plan and comments the result
to the PR. You iterate until your plan is successful and
looks good.
3. Somebody reviews and approves your PR.
4. You “atlantis apply” (if autoapply is not enabled), atlantis
executes terraform apply and comments the result to
the PR. You iterate until your apply is successful.
5. Merge the PR.

15. Atlantis workflow behind the scenes

16. Supported Installation Methods
● Docker container
● Helm chart
● Kubernetes Manifest
● Kubernetes Kustomize
● Terraform module for AWS Fargate
● Terraform module for GCE
● Terraform module for Azure (but helm chart also works)
● Roll your own (it’s just running a single binary, really)
● For dev/test purposes you can also just run it and
expose with Ngrok (but don’t forget restricting it).

17. Supported VCSs
● Github/Github enterprise, with user+pat or with Github
App integration
● Gitlab/Gitlab enterprise with pat
● Bitbucket Cloud with pat
● Bitbucket Server with pat
● Azure Devops with pat

18. Terraform version support
● Atlantis will honor the required_version in your
workspace, but you can also explicitly specify a default
and a workspace specific terraform version in your
atlantis.yaml.
● Atlantis will resolve and install your providers/plugins as
it would happen if you manually executed terraform init.
● From personal experience if you decide to
change/bump your version constraints mid-plan you will
need to discard your current plan and plan again.

19. Atlantis locking
Atlantis introduces an additional lock mechanism, any
terraform workspace which have an active Atlantis plan will
be locked, so concurrent Pull Requests won’t be able to
plan for the same workspace until the previous plan is
either applied or discarded.
You can discard plans from the github PR or from the
atlantis UI.

20. Customizing Atlantis
1. You can have global configuration options which can be
set through arguments/config file values or environment
variables passed to the Atlantis binary.
2. For repository specific settings you can use a
Server-Side Repo Config.
3. You can also have an atlantis.yaml file in the root of
your terraform repositories, which can modify atlantis
behavior on a repo or workspace level.

21. Repo structures
● You can have a terraform workspace in your repo.
● You can have multiple workspaces as top level
directories in your repo.
● You can have workspace directories in a tree-like
structure.
● You can declare relations between your workspaces in
atlantis.yaml, and atlantis will help you to cascade the
plans between workspaces.
● You can have multiple repositories managed by a single
Atlantis instance.

22. Command Requirements
● Atlantis supports the following requirements:
○ Approved
○ Mergeable
○ UnDiverged
● You can use these as to specify when can plan, apply
and import execute.
● By default after the apply requirement are met (plan is
green, PR is approved, etc.) anybody who can comment
can atlantis apply, you can change this with
gh-team-allowlist.

23. Security
● Make sure to read through the security documentation:
○ https://www.runatlantis.io/docs/security.html
● Follow your company’s Security Standards and consider
Atlantis as a critical production asset.
● Use webhook secrets and you can also additionally
firewall atlantis to restrict webhook access from your
VCS only.
● You can also put a WAF in front of it just in case.

24. Thanks for your attention!
Slides will be here:
http://www.slideshare.net/Tyrael
If you have any questions:
tyrael@tyrael.hu
@Tyr43l