Terraform is a great Tool to provision Infrastructure with different Providers. When using Terraform you are describing your Infrastructure using a declarative Language (HCL). There are sevaral Advantages of using Terraform but Today we will focus on using Terraform with Atlantis. Usually Terraform will be used in Combination with a Remote State (for example an encrypted S3 Bucket) to store its last known State and create Diffs against. The following three Commands are the most important Terraform Operations: init, plan and apply.

Working with Terraform locally against a productive State is not recommended, especially when working in a Team. Instead, working with Change Requests using a Version Control System makes it easy for Teams to review and integrate new Changes.

After changing some Terraform Code you want to be able to see the actual Difference you are creating by introducing your Change. Atlantis can be used to plan Terraform Changes and enables you to use a CLI-like Tool in Comments to get Changes merged. Atlantis is deployed as Webhook Server waiting for new Events from a Version Control System (for example comments, pushes or releases).

Benefits

There are sevaral Advantages by using Atlantis:

1. Using Comments in your Pull Requests to Plan and Apply Changes
2. Support for Terraform Workspaces to distinguish between Environments
3. Workflow Definitions to customize to your Needs or execute other Scripts
4. Restrictions on Repository-Level Configurations (Approvals, Workflows)
5. Debug failed Runs or Migrate State (Terraform CLI proxy)
6. No need for custom handwritten and error-prone scripts
7. Integrated Locking of Workspaces and Modules
8. Rollout Changes from a Branch and let Atlantis Auto-Merge the Branch upon Success
9. Simple UI to manage Locks and view open Change Requests
10. Optional Persistent Storage as Plugin Cache and Store for local_files
11. Can be used with GitHub, GitLab and Bitbucket
12. Independent on the Cloud Provider used

Recommendations

We are using Atlantis and Terraform for a while here are some of our Recommendations on how to use it:

1. Take Time inspecting the Plan

Before you instruct Atlantis to apply a new Plan, inspect and validate the Plan properly. Once Atlantis starts applying your Changes the global State of Terraform changes and the current Workspace will be locked. Failed Rollouts need immediate Attention. Plans on other Branches might revert partially applied Changes or even fail during Refresh. It is recommended to wait for at least one Approval before applying the Plan. This can be achieved by setting approved Apply Requirement for the Atlantis Server Configuration.

2. Branch Rollouts

Rolling out Changes from a Branch avoids Situation where Master Branches become invalid. Applying Plans before merging ensures your Master is always eligible to be applied (Disaster Recovery or Detect Diffs in current Infrastructure) and represents the current desired State. We recommend to enable Auto-Merge of Branches upon successful Apply to immediately reflect Changes to State and Infrastructure in your master (main) Branch.

3. Enable Status Checks

Atlantis comes with an “Autoplan” Feature which allows you to automatically plan Changes. To ensure that Atlantis creates a Plan for Terraform Code Changes require atlantis/plan Status Check (might differ on other Platforms). Making sure the Branch is valid to be applied can be achieved by adding mergable Apply Requirement to Atlantis. This Way you can define required Status Checks to validate Changes. Atlantis will reject all Apply-Runs until all Status Checks have been passed.

You can decide on your own whether you want Plan only Changes against a specific Environment/Workspace or All at the same Time. These Configurations are done using the Repo Level Config in your Repositories atlantis.yaml.

4. Prevent Access to State Backend

Terraform State contains all Secrets in Plain Text. Manipulating the State manually can also lead to unintended Sideeffects which can become very challenging to resolve. Also note that Terraform State is pinned to the specific Terraform Version currently used. Prevent Humans from writing to the State Backend directly to avoid unintended Version-Upgrades and any Changes outside of your Version Control System.

Upon successful Apply-Run Atlantis shows all Terraform Outputs, but also hides Outputs marked as sensitive. You might find it useful to allow Developers to retrieve Secrets using terraform output. When using an S3 Bucket on AWS for example only grant Read Access (s3:GetObject) to Humans with MFA enabled. You can also consider to use encrypted values as Terraform Outputs. These wont need a sensitive flag and can be decrypted by your Team using PGP Keys. We recommend to take a look at Keybase.

5. Configure Atlantis Server

The Atlantis Server will be your primary Operator to execute Terraform and is also the “gate-keeper” for Changes to your Infrastructure. This includes Permissions of your CI System to apply Changes. Therefore we recommend to properly secure and setup your Atlantis Server, define Workflows and connect your Workflows to corresponding State Backends. Configure then your Repository to use the Server defined Workflow from the atlantis.yaml Repo Config. You should also make sure to include a Webhook Secret to sign your Webhook Requests.

Try it out

You can try it out now by using our managed Atlantis Offer. Using our managed Solution saves you Time implementing Terraform and Atlantis and includes Maintenance for the Atlantis Server itself as well as a trusted TLS Connection and Repository Configuration (Webhook, Branch Protection, …).

You can also deploy it yourself:

• Deploy to AWS ECS
• Deploy to Kubernetes using Helm

Read Deployment Config for more Options.