Introducing Atlantis
NOTE: This post was originally written on September 11th, 2017
We’re very excited to announce the open source release of Atlantis! Atlantis is a tool for collaborating on Terraform that’s been in use at Hootsuite for over a year. The core functionality of Atlantis enables developers and operators to run terraform plan and apply directly from Terraform pull requests. Atlantis then comments back on the pull request with the output of the commands:
This is a simple feature, however it has had a massive effect on how our team writes Terraform. By bringing a Terraform workflow to pull requests, Atlantis helped our Ops team collaborate better on Terraform and also enabled our entire development team to write and execute Terraform safely.
Atlantis was built to solve two problems that arose at Hootsuite as we adopted Terraform:
1. Effective Collaboration
What’s the best way to collaborate on Terraform in a team setting?
2. Developers Writing Terraform
How can we enable our developers to write and apply Terraform safely?
Effective Collaboration
When writing Terraform, there are a number of workflows you can follow. The simplest workflow is just using master:
In this workflow, you work on master and run terraform locally. The problem with this workflow is that there is no collaboration or code review. So we start to use pull requests:
We still run terraform plan locally, but once we’re satisfied with the changes we create a pull request for review. When the pull request is approved, we run apply locally.
This workflow is an improvement, but there are still problems. The first problem is that it’s hard to review just the diff on the pull request. To properly review a change, you really need to see the output from terraform plan.
What looks like a small change…
…can have a big plan
The second problem is that now it’s easy for master to get out of sync with what’s actually been applied. This can happen if you merge a pull request without running apply or if the apply has an error halfway through, you forget to fix it and then you merge to master. Now what’s in master isn’t actually what’s running on production. At best, this causes confusion the next time someone runs terraform plan. At worst, it causes an outage when someone assumes that what’s in master is actually running, and depends on it.
With the Atlantis workflow, these problems are solved:
Now it’s easy to review changes because you see the terraform plan output on the pull request.
Pull requests are easy to review since you can see the plan
It’s also easy to ensure that the pull request is terraform apply’d before merging to master because you can see the actual apply output on the pull request.
So, Atlantis makes working on Terraform within an operations team much easier, but how does it help with getting your whole team to write Terraform?
Developers Writing Terraform
Terraform usually starts out being used by the Ops team. As a result of using Terraform, the Ops team becomes much faster at making infrastructure changes, but the way developers request those changes remains the same: they use a ticketing system or chat to ask operations for help, the request goes into a queue and later Ops responds that the task is complete.
Soon however, the Ops team starts to realize that it’s possible for developers to make some of these Terraform changes themselves! There are some problems that arise though:
- Developers don’t have the credentials to actually run Terraform commands
- If you give them credentials, it’s hard to review what is actually being applied
With Atlantis, these problems are solved. All terraform plan and apply commands are run from the pull request. This means developers don’t need to have any credentials to run Terraform locally. Of course, this can be dangerous: how can you ensure developers (who might be new to Terraform) aren’t applying things they shouldn’t? The answer is code reviews and approvals.
Since Atlantis comments back with the plan output directly on the pull request, it’s easy for an operations engineer to review exactly what changes will be applied. And Atlantis can run in require-approval mode, that will require a GitHub pull request approval before allowing apply to be run:
With Atlantis, developers are able to write and apply Terraform safely. They submit pull requests, can run atlantis plan until their change looks good and then get approval from Ops to apply.
Since the introduction of Atlantis at Hootsuite, we’ve had 78 contributors to our Terraform repositories, 58 of whom are developers (75%).
Where we are now
Since the introduction of Atlantis at Hootsuite we’ve grown to 144 Terraform repositories [1] that manage thousands of Amazon resources. Atlantis is used for every single Terraform change throughout our organization.
Getting started with Atlantis
If you’d like to try out Atlantis for your team you can download the latest release from https://github.com/runatlantis/atlantis/releases. If you run atlantis testdrive you can get started in less than 5 minutes. To read more about Atlantis go to https://www.runatlantis.io/.
Check out our video for more information:
