In this lab, we'll use Terraform to deploy an EC2 instance preconfigured with Atlantis' Dockerfile. We'll then connect to the EC2 instance, install Atlantis using the Docker image method, and set up webhook integration with our GitLab repository.The access token will allow Atlantis to access the repository, while the webhook configuration will define the events that Atlantis will monitor. Finally, we'll create a pull request to observe Atlantis in action.
Follow the step-by-step below to complete this Lab, hope you enjoy and learn something new from this!
We have pre configured and provisioned EC2 instnce and Gitlab setup already to save time in playground session. So no need to perform Gitlab setup and based on playground links you can directly connect Gitlab and follow the Token integration and Webhook integration.
2.1 Once you start click the below link giving your correct user name details it will display all your access links .
Lab environment: https://lab.devopsplayground.org/
Example:
2.1.1 Log into your GitLab instance with provided login details. You will find user and password details in VSCODE link under the file called gitlab_cred.txt.
Login Page of Gitlab
2.1.2 Create a new repo within Gitlab
2.1.3 Fill out the name of the repo as per your requirement
2.1.4 First we need to create an access token for Atlantis to use
2.1.5 Name the token "atlantis" to clearly indicate its purpose to team members understand. Assign it the Developer role and select the "api" to grant the required permissions.
2.1.6 Once created, ensure to make a note of the token and save it for future reference to setup variables.
2.2.1 Next we have to create and configure Webhook
2.2.2 Before you create a webhook with atlantis IP you have to enable Network outbound requests.
Note: This step required when you have only single EC2 server and installed both Atlantis and Gitlab ,then to communicate both of them actually required it but in our demo atlantis and Gitlab has installed seperately so we can skip steps 2.2.2 and 2.2.3 .
2.2.3 Click save changes and go to project settings Webhook option.
and then follow the below stpes to configure webhook setup and webhook secret.
- URL: http://ec2-atlantis-server-public-ip:4000/events
- Name: alantis-webhook (It is optional and can be anything you want)
- Secret Token: atlantis123 (This token will be used for the Docker run command later, so should make a note of it)
- Trigger:
- Push Events
- Comments
- Merge Request Events
- Keep SSL enabled
2.2.3.a For URL you can look at in atlantis-instance.txt
You can see webhook logs here.
2.2.4 Set up repo URL and hostname environment variables and make sure that REPO URL DOES NOT contain http.
At the same time make sure hostname should contain http.
Note: All setting up the environmenet variable steps should be performed in Atlantis Server.
2.2.5 Set the environment variable using the below provided commands:
export ACCESS_TOKEN=YOUR_TOKEN
e.g. export ACCESS_TOKEN=glpat-abc123def456
2.2.6 To check if you have assigned the value correctly, run 'echo $ACCESS_TOKEN'. This should return the token you just generated.
2.2.7 Now set the environment variable for webhook secret as well. The secret will be defined by your own and make a note of it to export all the four environment variables together to avoid confusion.
export WEBHOOK_SECRET=YOUR_WEBHOOK_SECRET
Repo URL:
export REPO_URL=YOUR_REPO_URL
e.g. export REPO_URL=<panda-name>.devopsplayground.org/root/atlantis-demo
Hostname:
export HOSTNAME=YOUR_HOSTNAME
e.g. export HOSTNAME=http://<panda-name>.devopsplayground.org
Reaching this point indicates that you have successfully configured Atlantis to accept connections and events from Gitlab. Next section we will be launching Atlantis with the environment variables we defined earlier.
In this section, we will be installing Atlantis from within the CLI using Docker. There should be a Dockerfile created already which will install the latest version of Atlantis. Commands below will build a image named atlantis with the Dockerfile supplied and run the atlantis service on port 4000:4141. The environment we been assigning is used here to configure atlantis on where to connect and give atlantis the access to our repo.
3.1 To execute docker file to swith to working directory -/home/playground/workdir/
Then build a atlantis docker image using the below command.
cd ~/workdir
sudo docker build -t atlantis .
sudo docker run -itd -p 4000:4141 --name atlantis atlantis server --automerge --autoplan-modules --gitlab-user=root --gitlab-token=$ACCESS_TOKEN --repo-allowlist=$REPO_URL --gitlab-webhook-secret=$WEBHOOK_SECRET --gitlab-hostname=$HOSTNAME
3.1.a Here I'm splitting the command to understand in better way.
Run Atlantis Docker Container: sudo docker run -itd -p 4000:4141 --name atlantis atlantis server Runs the Atlantis Docker container in detached mode, exposing port 4000 locally and mapping it to port 4141 within the container, with the container named "atlantis".
Automation Options: --automerge --autoplan-modules Enables automatic merging of pull requests and module-level autoplanning for Terraform changes.
GitLab Configuration: --gitlab-user=root --gitlab-token=$ACCESS_TOKEN Specifies the GitLab user (root in this case) and provides the GitLab access token for authentication.
Repository Allowlist: --repo-allowlist=$REPO_URL Specifies the repository URL(s) that Atlantis should allow operations on.
Webhook Configuration: --gitlab-webhook-secret=$WEBHOOK_SECRET --gitlab-hostname=$HOSTNAME Provides the GitLab webhook secret for secure communication and sets the GitLab hostname for webhook handling.
3.1.2 Once Atlantis service is started, you can access it by going to your atlantis ip on port 4000
Next we need to provide Atlantis access to AWS by providing the AWS User Access key and Secret Access Key. IAM user is provided with minimum required permissions for Atlantis to work here.This step required when you are using any provider related resources but in our demo we are using some fake provider resources so we can skip these steps from 3.1.3 to 3.1.7.
3.1.3 To get AWS accesskey and secret key values grep it with the below command in Atlantis server
env |grep AWS
3.1.4 The below exec command allows you to run commands within an already deployed container which is atlantis container.
sudo docker exec -it atlantis /bin/sh
3.1.5 Then with the Vim editor we update the credentials within .aws folder
vi /home/atlantis/.aws/credentials
3.1.6 Press I within the Vim editor to go into input mode and paste in the block below:
[default]
aws_access_key_id = "ACCESS_KEY"
aws_secret_access_key = "SECRET_ACCESS_KEY"
3.1.7 Once that is done, we press ESC to exit the input mode and press :wq to save the changes (w for write and q for quit)
Everything should be fully set up and ready to output your terraform plan onto pull request for everyone who has access to your repo to see.
4.1 First create a testing branch and try to copy main.tf and terraform.tfvars content for testing Terraform infrastructure and have Atlantis output plan. You can get these sample terraform main.tf and terraform.tfvars infra files availble under test-atlantis folder.
4.1.a Also for terraform provider token you can get it in VSCODE link under the file called terraform-token.txt
4.1.b Once files uploaded then you can create merge request
4.1.2 To run Terraform plan, we need to submit atlantis plan in the comment. We know it is working by the Eyes emote reacted on our atlantis plan comment. You can change the emote which is used by atlantis within configuration file.
From atlantis homepage, you can see all the previous plans/apply with an screenshot attached showing the native terraform output
Once the plan is done and without error, the output will be commented within the pull request/merge request
Atlantis doesn't just support linear workspaces but you can configure within the atlantis.yaml file to accept multiple workspaces
Within the atlantis.yaml file will look something like this.
Create atlantis.yaml file in your testing branch and copy the content from atlantis-automation Github repository for qucik and easy testing.
version: 3
automerge: true
abort_on_execution_order_fail: true
autodiscover:
mode: auto
projects:
- name: atlantis-dev
branch: /main/
dir: ./terraform
workspace: dev
terraform_version: v1.6.1
autoplan:
enabled: false
- name: atlantis-prod
branch: /main/
dir: ./terraform
workspace: prod
terraform_version: v1.6.1
autoplan:
enabled: false
5.1 The above config defines 2 projects, atlantis-dev and atlantis-prod. This simulates the Dev environment and Prod environment. To tell Atlantis which workspace you want to use, you can use the -w flag during the atlantis plan or if you have defined a project within the atlantis.yaml, you can use the -p flag instead and it will pick up the configuration defined within the yaml file.
atlantis plan -w dev
5.1.2 Make sure that workspaces are properly cleaned up after the completion of pull requests, helping to maintain a clean and manageable infrastructure environment.
5.1.3 Using the -destroy Flag you can destroy your atlantis resources
Example 5.1.3a To perform a destructive plan that will destroy resources you can use the -destroy flag like this:
atlantis plan -- -destroy
5.1.3b To perform a destructive plan at directory level use the below command.
atlantis plan -d dir -- -destroy
NOTE
The -destroy flag generates a destroy plan, If this plan is applied it can result in data loss or service disruptions. Ensure that you have thoroughly reviewed your Terraform configuration and intend to remove the specified resources before using this flag.
Atlantis destroy plan output from Gitlab page
Destroy output from Atlantis web page view below.
5.1.4 To delete all the resources use the below command.
atlantis apply -- -destroy
5.1.5 Resources deletion output view from Gitlab PR
5.1.6 Resources deletion output view from Atlantis web page.
Thank you
