In this article, we will look into how to setup and use Atlantis for Terraform Pull Request Automation in Linux. According to Official website, Atlantis is an advanced application for automating Terraform via pull requests. It is deployed as a standalone application into your infrastructure. It is so secure that no third-party will be able to access your credentials.
Atlantis listens for all the popular version control like GitHub, GitLab or Bitbucket webhooks about Terraform pull requests. It then runs terraform plan and comments with the output back on the pull request. Then if you want to apply the changes then you can comment atlantis apply on the pull request and Atlantis will run terraform apply and comment back with the output. We will go through an example to understand the concept further in below section.
How to Setup and Use Atlantis for Terraform Pull Request Automation
Step 1: Prerequisites
a) You should have a running Linux Server.
b) You should have
unzip utility installed in your Server.
c) You should have
root access to run privileged commands in your Server.
Step 2: Update Your Server
Before installing a new package, it is always a good idea to check for any latest available updates by using
yum update or
dnf update command. If any of the packages needs upgradation then you can run yum upgrade or dnf upgrade to upgrade the packages.
[root@cyberithub ~]# yum update Loaded plugins: fastestmirror, langpacks Loading mirror speeds from cached hostfile * base: centos-hcm.viettelidc.com.vn * extras: centos-hcm.viettelidc.com.vn * updates: centos-hcm.viettelidc.com.vn Resolving Dependencies --> Running transaction check ---> Package bind-export-libs.x86_64 32:9.11.4-26.P2.el7_9.8 will be updated ---> Package bind-export-libs.x86_64 32:9.11.4-26.P2.el7_9.9 will be an update ---> Package bind-libs.x86_64 32:9.11.4-26.P2.el7_9.8 will be updated ---> Package bind-libs.x86_64 32:9.11.4-26.P2.el7_9.9 will be an update ---> Package bind-libs-lite.x86_64 32:9.11.4-26.P2.el7_9.8 will be updated ---> Package bind-libs-lite.x86_64 32:9.11.4-26.P2.el7_9.9 will be an update ........................
Step 3: Install Terraform
To install terraform from Hashicorp repo, you need to follow below steps.
a) Install yum-config-manager
First you need to install yum-config-manager using
yum install -y yum-utils command. Since I already have the latest version installed so it does not look for any further updates.
[root@cyberithub ~]# yum install -y yum-utils Loaded plugins: fastestmirror, langpacks Loading mirror speeds from cached hostfile * base: centos-hcm.viettelidc.com.vn * extras: centos-hcm.viettelidc.com.vn * updates: centos-hcm.viettelidc.com.vn Package yum-utils-1.1.31-54.el7_8.noarch already installed and latest version Nothing to do
b) Add Hashicorp Repo
Next step is to add the Hashicorp repo using below
[root@cyberithub ~]# yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo Loaded plugins: fastestmirror, langpacks adding repo from: https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo grabbing file https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo to /etc/yum.repos.d/hashicorp.repo repo saved to /etc/yum.repos.d/hashicorp.repo
c) Install Terraform
Then install terraform from the recently added repo using
yum -y install terraform command as shown below.
[root@cyberithub ~]# yum -y install terraform Loaded plugins: fastestmirror, langpacks Loading mirror speeds from cached hostfile * base: centos-hcm.viettelidc.com.vn * extras: centos-hcm.viettelidc.com.vn * updates: centos-hcm.viettelidc.com.vn Resolving Dependencies --> Running transaction check ---> Package terraform.x86_64 0:1.1.7-1 will be installed --> Finished Dependency Resolution Dependencies Resolved ============================================================================================================================================================= Package Arch Version Repository Size ============================================================================================================================================================= Installing: terraform x86_64 1.1.7-1 hashicorp 12 M Transaction Summary ============================================================================================================================================================= Install 1 Package Total download size: 12 M Installed size: 60 M Downloading packages: warning: /var/cache/yum/x86_64/7/hashicorp/packages/terraform-1.1.7-1.x86_64.rpm: Header V4 RSA/SHA512 Signature, key ID a3219f7b: NOKEY 10 MB 00:00:00 ETA Public key for terraform-1.1.7-1.x86_64.rpm is not installed terraform-1.1.7-1.x86_64.rpm | 12 MB 00:00:07 Retrieving key from https://rpm.releases.hashicorp.com/gpg Importing GPG key 0xA3219F7B: Userid : "HashiCorp Security (HashiCorp Package Signing) <email@example.com>" Fingerprint: e8a0 32e0 94d8 eb4e a189 d270 da41 8c88 a321 9f7b From : https://rpm.releases.hashicorp.com/gpg Running transaction check Running transaction test Transaction test succeeded Running transaction Installing : terraform-1.1.7-1.x86_64 1/1 Verifying : terraform-1.1.7-1.x86_64 1/1 Installed: terraform.x86_64 0:1.1.7-1 Complete!
Step 4: Install Ngrok
Ngrok to be installed in the System. It is available as snap package in Snap store so to install this snap we can use
snap install ngrok command as shown below.
[root@cyberithub ~]# snap install ngrok 2022-03-16T02:48:14-04:00 INFO Waiting for automatic snapd restart... ngrok 2.3.40 from Kyle Wenholz (kyle-ngrok) installed
Step 5: Install Git
Atlantis need git utility to clone the repo hence we can install this utility by using
yum install git command as shown below.
[root@cyberithub ~]# yum install git Loaded plugins: fastestmirror, langpacks Loading mirror speeds from cached hostfile * base: centos-hcm.viettelidc.com.vn * epel: mirrors.thzhost.com * extras: centos-hcm.viettelidc.com.vn * updates: centos-hcm.viettelidc.com.vn Resolving Dependencies --> Running transaction check ---> Package git.x86_64 0:184.108.40.206-23.el7_8 will be installed --> Processing Dependency: perl-Git = 220.127.116.11-23.el7_8 for package: git-18.104.22.168-23.el7_8.x86_64 --> Processing Dependency: perl(Term::ReadKey) for package: git-22.214.171.124-23.el7_8.x86_64 --> Processing Dependency: perl(Git) for package: git-126.96.36.199-23.el7_8.x86_64 --> Processing Dependency: perl(Error) for package: git-188.8.131.52-23.el7_8.x86_64 --> Running transaction check ---> Package perl-Error.noarch 1:0.17020-2.el7 will be installed ---> Package perl-Git.noarch 0:184.108.40.206-23.el7_8 will be installed ---> Package perl-TermReadKey.x86_64 0:2.30-20.el7 will be installed --> Finished Dependency Resolution .....................................
Step 6: Download Atlantis
You can go to GitHub website and download the latest atlantis version by using any file transfer tool like
wget as shown below. It will download the zip package in the current local directory.
[root@cyberithub ~]# wget -q https://github.com/runatlantis/atlantis/releases/download/v0.19.2/atlantis_linux_amd64.zip [root@cyberithub ~]# ls -lrt atlantis_linux_amd64.zip -rw-r--r--. 1 root root 8776711 Mar 11 08:55 atlantis_linux_amd64.zip
Step 7: Unzip Package
Next step is to extract the package by using
unzip utility as shown below. You can either extract to current location or to some specific directory.
[root@cyberithub ~]# unzip atlantis_linux_amd64.zip Archive: atlantis_linux_amd64.zip inflating: atlantis
Step 8: Copy Binary File
You can either copy the binary file to some standard binary location which is visible to the System or you can just put it into some directory and export to make it visible across the System. Here we are just copying the binary file to
[root@cyberithub ~]# cp atlantis /usr/bin/
Step 9: Check Version
You can check the working of atlantis binary utility by using
atlantis version command as shown below.
[root@cyberithub ~]# atlantis version atlantis 0.19.2
Step 10: Generate Token
a) Login to GitHub
You need to open GitHub Sign In Page and login using your Username or email address and Password as shown below. If you don't have any GitHub account then you can first Create an account and then login.
b) Go to Settings
Once logged in, you can go to top right corner and open
Settings from there as highlighted below.
c) Go to Developer settings -> Personal Access Tokens
In the settings, you can find
Developer settings on the left side column. Click on it and then you will see below option where you need to click on
Personal access tokens. You will see an option to
Generate new token. Click on it to fill the details.
d) Generate new token
Here you can provide Note as
atlantis and select scopes for
repo only. You can also change the Expiration date of your token but as of now I will leave it as default and then click on
Generate Token. After this, you will see a token generated which you need to copy and keep it handy to use in next step.
Step 11: Setup Atlantis
Now we need to setup Atlantis on a test repo so that we can try it out. For that you just need to run
atlantis testdrive command as shown below. It will first ask you provide
github.com username which is
cyberithub in our case. You can provide your account username here. Then
Press Enter to proceed.
Next it will ask you to provide GitHub Access Token to fork a new project for you. Here you can paste the token which you have copied in the previous step. Remember that token will remain hidden so you won't be able to see the pasted items. Then
Press Enter to proceed and now wait till a pull request is created in GitHub and Atlantis shows in running state as shown below.
[root@cyberithub ~]# atlantis testdrive Welcome to Atlantis testdrive! This mode sets up Atlantis on a test repo so you can try it out. We will - fork an example terraform project to your username - install terraform (if not already in your PATH) - install ngrok so we can expose Atlantis to GitHub - start Atlantis Press Ctrl-c at any time to exit github.com username: cyberithub To continue, we need you to create a GitHub personal access token with "repo" scope so we can fork an example terraform project. Follow these instructions to create a token (we don't store any tokens): https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token - use "atlantis" for the token description - add "repo" scope - copy the access token GitHub access token (will be hidden): => forking repo => fork completed! => terraform found in $PATH! => downloading ngrok => downloaded ngrok successfully! => creating secure tunnel => started tunnel! => starting atlantis server ⠹ => atlantis server is now securely exposed at https://1106-49-37-74-25.ngrok.io => creating atlantis webhook => atlantis webhook created! => creating a new pull request => pull request created! => opening pull request atlantis is running [press Ctrl-c to exit] ⠇
Step 12: Run atlantis plan
You can now come back to your GitHub account and see there is an example project created for you along with a pull request. You can go to that
Project and click on
Conversation. Here you can come on bottom and write
atlantis plan in the comment section and then click on
Comment. This will start running
terraform plan on the background.
Once successful, it will show you output like below where it will show you the resources plan which is going to get created after applying this plan.
Step 13: Run atlantis apply
To apply the plan shown in the previous step, you can run
atlantis apply -d . in the comment box section as shown below and then Click on
Comment. This will start creating the resources based on the plan on the background.
Once it is completed, it will show you the output like below.
Step 14: Merge Pull Request
Now you can
merge the pull request as shown below. Then you can also delete the example branch if you would like to.