In this article, we will learn the integration of Atlantis with GitHub and Terraform.

Atlantis Integration with Github and Terraform

Terraform and GitHub has played an important role in our DevOps job and its simplex structure has made complex commands run in a simpler way making Terraform more flexible and a popular tool.

Have you ever faced challenges like managing your multiple projects/repos in Terraform, facing difficulty while enforcing peer review, versioning control and too many sets of privileged credentials, even if we have click-up, Gmail, slackenvironment integrated with each other OR when you have already deployed the code and after the review is done, we face challenges in altering them?😟Then you should definitely try this solution called Atlantis❗️

Atlantis helps you to run commands using GitOps where you can merge Atlantis, create a Pull Request, get approvals and also run the terraform commands so that your entire team is aware of what changes are being made to the infrastructure.

To deploy Atlantis, you need to know the basics of Terraform,Kubernetes,Helm,GitHub, andWebhook Relay.

By the end of this blog, you will be able to know what is Atlantis, how to deploy it inGoogle Kubernetes Engine (GKE)using Helm, how to use Atlantis and why Atlantis is preferred more️?

So, let's start with what is Atlantis?

Atlantis is an open-source technology that allows the engineer/approver to review the changes in the infrastructure as well as evaluate that the proposed change is the actual change that will be executed on your infrastructure before applying it. Atlantis used withTerraform can be used as a CICD for Infrastructure as Code (IAC).

Atlantis is compatible with GitHub,GitLab, Bitbucket Cloud,and Azure DevOps.

Atlantis Overview

How does Atlantis work with Terraform?

Atlantis is an automation application that responds toTerraformpull requests via web callback or webhooks and automates the terraform init, plan, and apply the workflow.

The following sequence diagram illustrates the sequence of actions described above:

Sequence diagram for Atlantis

When you need to review the code before making any final changes, you can just do an “Atlantis plan” and check for the infrastructure changes.

It runs a terraform plan and comments with the output back on the pull request. And after your evaluation has been done, you can just comment “Atlantis apply” on the pull request, and Atlantis will run terraform apply and comment back with the output.

The Atlantis installation process then adds hooks to the repository which allows communication to the Atlantis server during the Pull Request (PR) process.

You don’t need heavy packages and large VM’s to deploy Atlantis, it can be done in acontainer or a small virtual machine— the only requirement is that the Terraform instance should communicate with both your version control (e.g., GitHub) and infrastructure (e.g.,AWS/GCP/Azure) you’re changing.

Once Atlantis is configured for a particular repository, it then executes as follows:

A developer generates a feature branch in git, builds some changes, andcreates a Pull Request (GitHub) or Merge Request (GitLab).
The developer writes “Atlantis plan” in a Pull Request (PR) comment.
Atlantis locallyruns terraform plansvia the installedwebhooks. If there are no other Pull Requests in progress, Atlantis adds the resulting plan as a comment to the Merge Request and if there are any other Pull Requests in progress, the resulting command fails as we can’t assure that the plan will be valid once applied.
The developer checks if the plan executes, provides the output as expected, andadds reviewers to the Merge Request.
Once the Pull Request has been approved by the approver, the developer writes “Atlantis apply” to apply in a PR comment. This will trigger Atlantis to run terraform apply and then the changes will be deployed to your infrastructure.

The command fails if theMerge Requesthas not been approved.

Having known the process of Atlantis, let's check how to deploy Atlantis and make use of it. There are many ways via which you can deploy Atlantis, but in this blog, we are using GKE and GitHub. You can refer to theirofficial docfor more deployment options.

Deploying Atlantis on Google Kubernetes Engine Using Helm

Pre-requisites:

Kubernetesenvironment and kubectl configured on your machine. For this blog, I am using GKE Cluster, but you can also use Mini Kube or EKS
HelmCLI — a Kubernetes package manager.
Webhook Relay account— webhook forwarding solution to our internal Kubernetes environment.
GitHubOrganizational Account
Git host access credentials— Make sure you save the access token; we will need it in the next step.
GitHub Secret— Make sure you save the secret; we will need it in the next step.
Webhook Relay operator— Make sure you save the Relay Key and Relay secret; we will need it in the next step.

There are multiple ways for deploying Atlantis, the official document for the same is in thislink

Let's follow the GitHub Deployment on GKE:

Create a namespace


kubectl create namespace atlantis

2. Switch context to Atlantis namespace


kubectl config set-context $(kubectl config current-context) --namespace=atlantis

3. Add repositories


helm repo add stable https://kubernetes-charts.storage.googleapis.com

4. Update helm repository


helm repo update

5. Use the following command to run Atlantis


helm upgrade --install atlantis stable/atlantis --version 3.12.2 \  --set=github.user=GitHub-Username \  --set=github.token=******* \  --set=github.secret=***** \  --set=service.type=ClusterIP \  --set=ingress.enabled=false \  --set=orgWhitelist="github.com/atlantis/*"

Here, the variables are:

github.user — your GitHub username
github.token— your GitHub personal access token
github.secret — shared secret that will have to be shared with Atlantis
service.type— making sure Atlantis is not exposed as aNode Port service
ingress.enabled—We have set it to false, i.e. disabled ingress
orgWhitelist — which repositories should be processed

Install Atlantis using Helm

6. Get the status of the pod and service


kubectl get podskubectl get svc

7. Export your Webhook Operator


export RELAY_KEY=xxxxxxxxxxxxexport RELAY_SECRET=xxxxx

8. Add the webhook relay operator to your helm repository and update the helm repo


helm repo add webhookrelay https://charts.webhookrelay.com


helm repo update

9. Install Helm


helm upgrade --install webhookrelay-operator webhookrelay/webhookrelay-operator \  --set credentials.key=$RELAY_KEY \  --set credentials.secret=$RELAY_SECRET

Install Webhook Relay Operator

10. We should now see two pods running in our Atlantis namespace:

11. Next step is to configure webhook forwarding to the Atlantis service:

Use vim to create a new yaml file & press i to insert the following deployment file and :wq! to save theatlantis-cr.yamlfile


apiVersion: forward.webhookrelay.com/v1kind: WebhookRelayForwardmetadata:  name: forward-to-atlantisspec:  buckets:  - name: github-to-atlantis    inputs:    - name: public-endpoint      description: "Endpoint for GitHub"      responseBody: "OK"      responseStatusCode: 200    outputs:    - name: atlantis-pod      destination:

12. Create the deployment using the apply command


kubectl apply -f atlantis-cr.yaml

13. We should now see three pods running in our atlantis namespace:


kubectl get podskubectl get svc

Pod and Service Status

To check the public webhooks URL refer thislinkand copy the Atlantis bucket URL

Webhook Relay URL

14. Go toGitHub→ Your Repo → Settings →WebhooksSet payload URL to the bucket URL and make sure to add/eventsin the end. Set the content type toapplication/JSON;set thesecretto webhook secret got in point no.7.

Check the following checkboxes ✅

✔️Pushes

✔️Pull request reviews

✔️Issue comments

✔️Pull requests

Make sure theActive checkboxremains checked and click on Save.

Manage Webhooks in GitHub

You can also refer toGitHub Repository, where you can Clone the repo in your local system and run Terraform Commands, and configure Atlantis.

Once Atlantis is configured, you can try it out on GitHub by creating a Pull Request and commenting on the Atlantis plan and Atlantis apply.

Benefits of Atlantis:

Manage Multiple Projects⚡️ We have to manage multiple projects in AWS/GCP/Azure and other clouds. A singlePull Requestcan run terraform plans in each directory in which it will copy and paste the planned output into the PR comment, and then apply locally before merging the Pull Request. Automating that process with Atlantis immediately improves productivity and thus we can manage multiple projects at the same time.
No More “It worked on my machine”👻We always end up with this quote that “it worked on my machine”, it should work on yours as well, here we don’t need to do anything locally, everything can be tested on a single platform.
Increased Audit Trail:🔏 Each pull request which has been raised, holds detailed logs of what infrastructure changes were made when the changes were made, who made the change, and who approved it.
Secure Workflow:🔐 Atlantis can be configured to require a Pull Request (PR) to be approved and merged before the changes can be applied. Atlantis can add an extra layer of protection that prevents engineers from accidentally applying changes before they’re approved by the approver
Reduction ofIAM Permissionsprovided to Engineers:✋ We are often required to provide highly privileged credentials to perform Terraform actions, and the greater the number of principals you have with privileged access, there is a higher chance of attacking risks.
Formalize the delivery process:👍 Atlantis makes sure that it locks the directory/workspace until the pull request is merged or the lock is deleted by manual intervention. This makes sure that changes are applied in the order as they are expected.

Limitations

Atlantis excels at all the things that we have seen till now, like the terraform init / plan / apply workflow, but it is not designed to handle more complex tasks, like importing terraform resources or running terraform state commands. Those operations still require manual intervention as of now.
Atlantis lets us work efficiently and effectively, increasing productivity. We do not have to wait for opening a pull request, executing terraform commands. We are now able to make infrastructure changes to n number of environments in analogy.

Note: If you’re new to Atlantis, you can runTest Drive of Atlantiswhere you can test the Atlantis working using the Atlantis executable files. Also, you can go through theofficial walkthroughof Atlantis to gain more insights.

Hopefully, this post has provided some valuable tips and information about Atlantis. Stay tuned to get more blogs and feel free to reach me on LinkedIn if you have any concerns.