Terraform Meets GitOps: Setting Up Atlantis on AWS for Automated Infrastructure Management

Introduction

Infrastructure automation is a crucial part of modern DevOps workflows, enabling teams to manage cloud resources efficiently using Infrastructure as Code (IaC). Terraform is a widely used IaC tool, and when paired with Atlantis, it provides a seamless, GitHub-driven workflow for managing infrastructure changes.

Atlantis integrates Terraform with version control systems like GitHub, GitLab, and Bitbucket, automating Terraform execution when pull requests (PRs) are created. This guide will walk you through setting up Atlantis on an AWS EC2 instance and integrating it with GitHub for an optimized Terraform automation experience.

Prerequisites

• AWS EC2 Instance: Running Amazon Linux 3, with ports 4000 and 22 open.
• AWS IAM User: With full access to S3 and EC2.
• GitHub Account: With a private repository for Terraform code.
• Basic Knowledge: Familiarity with Linux commands, Terraform, and GitHub workflows.
• Required Tools: An SSH client to connect to your EC2 instance and AWS CLI for resource management.

Setting Up the EC2 Instance

1. Launch an EC2 Instance

1. Log in to AWS Console and navigate to EC2.
2. Click Launch Instance and choose Amazon Linux 3 as the AMI.
3. Select an Instance Type (e.g., t2.micro or higher).
4. Configure Security Group to allow inbound traffic on:
   • SSH (22)
   • Atlantis (4000)
5. Launch the instance and download the key pair for SSH access.

EC2 SG

2. Connect to the Instance

SSH into the EC2 instance:

ssh -i your-key.pem ec2-user@your-ec2-public-ip

Update system packages:

sudo yum update -y

Installing and Configuring Atlantis on Amazon Linux 3

1. Install Docker

sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker

Verify Docker installation:

docker --version

Docker Version

2. Generate a GitHub Access Token

1. Go to GitHub > Settings > Developer Settings > Personal Access Tokens or click here
2. Click Generate new token (classic).
   

   Generate New Token

   Now, Enter the name and set the Expiration of the Token –

   

   Token Name and Expiration

   Enable scopes:

   1. repo (repository access)
   2. admin:repo_hook (webhook permissions)
      

      Select scopes

3. Click Generate token and copy it (GitHub will not show it again).
   

   Generate Token

   

   Token

3. Run the Atlantis Docker Container

sudo vi Dockerfile

Paste the following content:

FROM ghcr.io/runatlantis/atlantis:latest

USER root
RUN apk add --no-cache aws-cli

# Ensure the 'atlantis' user exists before changing ownership
RUN id atlantis || adduser -D atlantis

RUN mkdir -p /home/atlantis/.aws
RUN touch /home/atlantis/.aws/credentials

RUN chown -R atlantis:atlantis /home/atlantis/

USER atlantis

Dockerfile

Save the file and build the Atlantis image:

docker build -t atlantis .

Atlantis Docker image

Run the Atlantis container:

docker run -itd -p 4000:4141 --name atlantis atlantis server --automerge --autoplan-modules --gh-user=<github-account-username> --gh-token=<github-usr-access-token> --repo-allowlist=<list of allowed repos>

Atlantis container creation

Configuring AWS in Atlantis Docker Container

To allow Atlantis to interact with AWS, create an IAM user with S3 and EC2 full access:

• Go to AWS IAM > Users > Create User.
• Attach AmazonS3FullAccess and AmazonEC2FullAccess policies.
• Generate and save the Access Key and Secret Key.

Next, configure AWS credentials inside the Atlantis Docker container by running the following command on your EC2 instance:

docker exec -it atlantis /bin/sh

Once inside the container, open the AWS credentials file for editing:

vi /home/atlantis/.aws/credentials

Add the following lines to the credentials file and save it:

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

Replace the placeholders with your IAM user credentials:

YOUR_ACCESS_KEY: Access key ID of the AWS IAM user.
YOUR_SECRET_KEY: Secret access key ID of the AWS IAM user.

Important Security Note: Storing AWS access keys directly on an EC2 instance is not recommended for production environments due to security risks. This setup is demonstrated here for educational purposes only. In a real-world scenario, consider using AWS IAM roles with EC2 instance profiles or AWS Secrets Manager to securely manage credentials.

Note: If you have multiple AWS profiles, you can add additional profile entries in the credentials file and specify them in your Terraform configuration.

Configuring Webhooks in GitHub Repository

Webhooks allow Atlantis to react to pull request events and apply Terraform changes automatically. Follow these steps to set up a webhook in your GitHub repository:

1. 1. Open your GitHub repository that contains your Terraform code.
   2. Go to Settings → Webhooks.
   3. Click Add webhook.
   4. Set the Payload URL to:

http://your-ec2-public-ip:4000/events

1. Set Content type to application/json.
   
2. Select Let me select individual events and check the following options:
   • Issue comments
   • Pull request reviews
   • Pull requests
   • Pushes
     

     Events Selection

3. Ensure that Active is checked.
   
4. Click Add webhook.

Now, every time a pull request is created, updated, or merged, Atlantis will receive an event and execute the relevant Terraform workflow.

Running Terraform Workflow with Atlantis

1. 1. Create a new pull request in GitHub.
      

      Create Pull Request

   2. Atlantis will automatically run terraform plan.
      

      Atlantis plan

      
      We can use the Show output option to see the output of the terraform plan command –

      

      Output of Terraform Plan

   3. To apply changes, comment:

atlantis apply -d .

Terraform apply

1. Once applied, You can check AWS Console for created resources.
   

   AWS Resource

Conclusion

By using Terraform with Atlantis and GitHub, teams can automate infrastructure updates while maintaining security, efficiency, and teamwork. With Atlantis, changes go through a pull request process, ensuring they are reviewed and approved before being deployed.

One of the key benefits of Atlantis is that it locks the state file while a pull request is open. This helps keep things secure by preventing multiple users from making changes at the same time, reducing the risk of state file issues.

FAQs

• How does Atlantis compare to Terraform Cloud? – Atlantis is self-hosted and free, while Terraform Cloud has associated costs.
• Is Atlantis suitable for large infrastructures? – Yes, it supports multi-repository environments.
• Can I integrate Atlantis with CI/CD tools? – Yes, it can be integrated with Jenkins, GitHub Actions, etc.
• How do I troubleshoot Atlantis setup issues? – Check logs using docker logs atlantis.
• Is Atlantis secure? – Yes, when properly configured with IAM policies and security groups.