Atlantis is a tool that automates Terraform operations through pull requests. It allows developers and operators to collaborate on infrastructure changes without leaving their version control system. Atlantis listens for webhooks from GitHub, GitLab, Bitbucket, or Azure DevOps and runs terraform plan and apply commands based on the pull request comments. Atlantis also provides approvals and feedback for each Terraform change via the version control system.
Atlantis Video Walk-through
Let’s take a look at our setup.
A GitHub account (all the hands-on sections will utilize GitHub’s Codespaces so you won’t need to install anything on your machine)
The Atlantis workflow is a process for developing and deploying software applications using a Git-based workflow.
The default Atlantis workflow depicted in the above image illustrates how Atlantis operates by leveraging merge requests and webhooks from the version control system (VCS).
The developer commits and pushes their code to a development or feature branch, where they have the necessary permissions to make changes.
The developer creates a merge request, signaling that their code changes are ready for review and integration.
The merge request triggers a webhook from the VCS to Atlantis, which initiates a Terraform Plan process.
Atlantis executes the Terraform Plan and displays the output within the comments section of the merge request. This provides visibility to the reviewers and other stakeholders involved in the code review process. The developer or anyone else could run the command Atlantis plan at any point in the merge request comments to get Atlantis to run the terraform plan command.
Once the plan is reviewed and approved by an approver as part of the peer review process, they can trigger the terraform apply command within Atlantis. This is done by typing atlantis apply in a new comment, which again triggers a webhook.
Atlantis executes the terraform apply command, applying the infrastructure changes based on the approved plan.
After the changes are successfully applied, the development branch can be merged into the main branch, integrating the approved code changes into the main codebase.
This workflow ensures that provisioning and verification occur before the code changes are merged, which is particularly useful in a development environment. For a more detailed demonstration, refer to the accompanying video demo.
How does Atlantis work?
Atlantis streamlines the review and execution of Terraform workflows by integrating with the VCS and automating the process. It enhances collaboration, visibility, and version control integration, ensuring a smoother and more controlled Terraform workflow within teams and organizations. Let's take a closer and more detailed look.
Setup: Initially, Atlantis needs to be set up and configured. This involves installing and configuring the Atlantis server, which can be hosted either on-premises or in the cloud. The server is responsible for receiving and processing requests from the VCS and executing Terraform commands.
VCS Integration: Atlantis integrates with a VCS (e.g., GitHub, GitLab, Azure DevOps, or Bitbucket) by creating webhooks or listening for events triggered by pull requests, commits, or branches.
Pull Request Creation: Developers create a pull request in the VCS repository containing the Terraform code changes they want to review and apply.
Event Trigger: The VCS sends an event notification to Atlantis, informing it of the pull request creation.
Workspace Creation: Atlantis creates an isolated workspace for the pull request. This workspace is where Terraform commands will be executed, ensuring that the state of the infrastructure changes is isolated from other workspaces.
Atlantis Configuration: Atlantis reads a configuration file (e.g., atlantis.yaml) in the repository or a default configuration file. This file defines the behavior and settings for Atlantis, such as the Terraform version, backend configuration, and allowed operations.
Command Execution: Atlantis automatically executes Terraform commands based on the pull request event. The commonly used commands include terraform init, terraform plan, terraform apply, and terraform destroy. Atlantis runs these commands within the pull request's workspace, utilizing the appropriate Terraform binary.
Output and Feedback: Atlantis captures the output of the executed Terraform commands, including the plan or apply results. It provides this output within the pull request as comments, making it visible and accessible for reviewers and stakeholders. This allows them to review the proposed infrastructure changes, provide feedback, and discuss any concerns or modifications needed.
Approval Process: Reviewers and stakeholders interact with the pull request, providing feedback, suggestions, or approvals. The discussion takes place within the VCS interface, making it easy for all participants to collaborate and reach a consensus on the changes.
Merge and Deployment: If the changes are approved, the pull request can be merged into the target branch, triggering the deployment of the Terraform changes using standard VCS merge processes. At this point, the Terraform code is typically executed again in the appropriate deployment environment outside of Atlantis.
Cleanup: Once the pull request is merged or closed, Atlantis cleans up the associated workspace, removing any temporary files or state information.
Managing Terraform and Terragrunt Projects
Managing Terraform and Terragrunt involves implementing effective practices and processes to ensure efficient and reliable infrastructure provisioning and management. Here are some key aspects to consider when managing Terraform and Terragrunt:
Code Organization: Proper code organization is essential for managing Terraform and Terragrunt projects. It's recommended to follow modularization techniques to break down the infrastructure code into reusable and maintainable modules. This allows for easier management of infrastructure components and promotes code reuse across projects.
Version Control: Utilize a version control system, such as Git, to track changes to your Terraform and Terragrunt code. Version control enables collaboration, provides a history of modifications, facilitates code reviews, and helps roll back changes if necessary.
Infrastructure State Management: Terraform uses state files to track the current state of the infrastructure. It's crucial to manage these state files appropriately. Consider using a remote backend, such as Amazon S3, Azure Blob Storage, or env0, to store the state files centrally and enable collaboration among team members.
Workspace Management: Terraform workspaces allow you to manage multiple instances of the same infrastructure in parallel, such as staging and production environments. Proper workspace management ensures that changes made in one workspace don't affect others. Define and maintain a clear strategy for workspace creation and usage to avoid conflicts and maintain isolation.
Dependency Management: Terragrunt is often used as a wrapper around Terraform to simplify and enhance its capabilities. Terragrunt provides features like remote state management, dependency handling, and environment-specific configuration. When managing Terraform and Terragrunt, it's important to manage and update Terragrunt versions and dependencies to leverage the latest features and bug fixes.
Testing and Validation: Implement a testing and validation process for your Terraform and Terragrunt code. Use tools like `terraform validate`, `terraform fmt`, and static code analysis tools to ensure proper syntax, formatting, and adherence to best practices. Additionally, consider implementing automated unit tests and integration tests to validate the behavior and correctness of your infrastructure code.
Infrastructure as Code (IaC) Pipelines: Create continuous integration and deployment pipelines to automate the testing and deployment of your Terraform and Terragrunt code. Use CI/CD systems like Jenkins, GitLab CI/CD, or CircleCI to execute validation tests, generate execution plans, and apply changes to the infrastructure. This helps enforce consistent processes, reduce manual errors, and ensure the repeatability of infrastructure deployments.
Change Management and Approval: Establish a change management process to review and approve infrastructure changes. Integrate Terraform and Terragrunt workflows with pull request systems, such as GitHub or GitLab, to facilitate code reviews and ensure proper collaboration and documentation of changes.
Why use Atlantis to Manage Terraform and Terragrunt Projects (Benefits)
Atlantis is a popular automation tool used to manage Terraform and Terragrunt workflows, providing several benefits to teams working with infrastructure-as-code. Here are some key benefits of using Atlantis:
Atlantis enables smooth collaboration among team members by integrating with version control systems (e.g., Git) and providing a centralized platform for code review and feedback. It facilitates a structured and efficient workflow, ensuring that all code changes are reviewed before being applied to the infrastructure.
Infrastructure State Management
Atlantis helps manage the state of Terraform deployments. It handles the isolation and management of Terraform state files, preventing conflicts that can arise when multiple developers simultaneously modify the infrastructure. Atlantis ensures that each pull request or branch has its own isolated workspace, making it easier to review and apply changes without impacting other ongoing work.
Review Process and Feedback
Atlantis integrates with pull request systems, such as GitHub or GitLab, allowing teams to review and discuss Terraform changes directly within the pull request interface. Reviewers can provide feedback, request modifications, and approve changes, ensuring a thorough review process before any modifications are made to the infrastructure.
Atlantis provides a clear overview of the Terraform plan and apply process within the pull request or branch. This helps reviewers and stakeholders understand the intended changes and potential impact on the infrastructure. It also displays the status and output of Terraform commands, making it easier to track the progress and results of infrastructure modifications.
Integration with CI/CD
Atlantis seamlessly integrates with CI/CD systems, enabling continuous integration and deployment of infrastructure changes. It can trigger the execution of Terraform commands as part of the CI/CD pipeline, ensuring that changes are tested and deployed automatically while maintaining visibility and review processes.
Use Cases and Best Practices for Atlantis
Consider using Atlantis when you want to enhance collaboration, automate Terraform workflows, enforce policies, and improve the code review process for your infrastructure-as-code projects. It provides a structured and efficient workflow, enabling better team collaboration and reducing the risk of errors in your infrastructure deployments. Here are some situations where you should consider using Atlantis:
Team Collaboration: If you have multiple team members or developers working on Terraform code changes concurrently, Atlantis can help streamline collaboration. It provides a centralized platform for code review and feedback, ensuring that all code changes go through a standardized review process before being applied to the infrastructure.
Pull Request Management: If you rely on pull requests in your version control system (VCS) for code review and merging, Atlantis can integrate seamlessly with your VCS platform. It allows you to trigger Terraform commands automatically within the context of pull requests, providing reviewers with the necessary information and output to make informed decisions on infrastructure changes.
Automation and Consistency: If you want to automate Terraform workflows and ensure consistency across different environments, Atlantis can help. It automates the execution of Terraform commands, such as initialization, planning, and applying changes, reducing the need for manual intervention and minimizing the chances of human error.
Infrastructure State Management: If you face challenges managing the state of your Terraform deployments, Atlantis can assist in isolating and managing state files. It provides a workspace-based approach, where each pull request or branch has its own isolated workspace and state. This helps prevent conflicts when multiple developers are working on infrastructure changes simultaneously.
Policy Enforcement: If you need to enforce policies and best practices for infrastructure changes, Atlantis can be configured to use conftest policy checking. Here are some common use cases:
Prohibiting the utilization of certain modules
Verifying the attributes of a resource during its creation
Detecting inadvertent resource deletions
Safeguarding against security vulnerabilities, such as the exposure of secure ports to the public
Integration with CI/CD: If you have an existing CI/CD pipeline or workflow for deploying infrastructure changes, Atlantis can be seamlessly integrated. It can trigger Terraform commands as part of the pipeline, ensuring that infrastructure changes are tested, reviewed, and deployed automatically.
Pre-Workflow Hooks: Configure Atlantis to perform pre-workflow hooks to validate code syntax, enforce compliance requirements, and perform security checks. These checks can help catch potential issues before applying changes to the infrastructure. Use tools like tflint, terraform fmt, or custom scripts to ensure code quality and adherence to standards. Consider reading our blog post on IaC scanning tools to be used in pre workflow hooks. Here it is: Which IaC Scanning Tool is the Best?: Comparing Checkov vs tfsec vs Terrascan
How to use Atlantis
Repo Config and Folder Structure
You will need to fork the repo so you get full access to the repo config. Below is the folder structure.
To run Atlantis locally, you can follow the official guide here. You basically need Terraform, Atlantis, and ngrok. These are all installed for you in our Codespace if you follow this guide.
In your Google Cloud project under IAM & Admin, generate a new key under Service Accounts.
This will save a JSON file on your computer. Save this to a JSON file called gcp-secret-key.json which should be added to your .gitignore file. There is a sample file in this repo called gcp-secret-key-example.json. You can save it there and rename it to gcp-secret-key.json.
Make sure the correct path is specified in the GOOGLE_APPLICATION_CREDENTIALS environment variable instart.sh.
Now open a new terminal tab in Codespaces and run the script below to deploy atlantis:
The application should now run on port 4141 and you can access it by clicking on the globe icon under the PORTS tab in Codespaces.
Server Side Configuration
Below is the Atlantis server-side configuration in the start.sh file.
REPO_ALLOWLIST="github.com/samgabrail/env0-atlantis-gcp" #GitHub example: REPO_ALLOWLIST="github.com/runatlantis/atlantis"
# Any environment variables required for auth
atlantis server \
Add a Developer to our Repo
Now let's invite a developer to our repo so they can run a pull request to a dev branch.
Make sure to make the main branch protected.
You can now make a change as a developer in a dev branch and then create a pull request. This will automatically run a Terraform plan. If satisfied, you can then run atlantis apply which will apply the changes. Then the owner of the repo can now approve the pull request and the dev branch will get merged with the main branch.
You can view the terraform plan output within the pull request comments or if you click on details in GitHub, you will see the output in the Atlantis UI.
Atlantis Limitations and Challenges
Let's discuss some of the limitations and challenges of Atlantis.
Overcoming Terraform Challenges: When Atlantis Isn't Enough
While Atlantis can be effective for smaller organizations, it may present challenges when scaling to meet more advanced requirements. Take a look at the checklist below and if you find yourself checking off more than half of the items there, then you’ve probably hit the limitations of Atlantis and it’s time to look for an alternative.
Self-Hosting and Community Support: Atlantis is an open-source tool that requires self-hosting, management, and ongoing support from your team. Reliance on the community for support and updates means that you may need to invest more effort into maintaining and troubleshooting the tool, rather than relying on a dedicated vendor for support and maintenance.
Lack of Concurrency: Atlantis operates in a single-threaded manner, which can become a bottleneck when managing larger environments. Without the ability to process multiple tasks concurrently, the execution of Terraform commands and infrastructure changes may experience delays and reduced performance.
Limited High Availability: Out of the box, Atlantis does not provide built-in high availability features. This can pose a challenge for organizations that require a resilient and highly available infrastructure for their Terraform workflows. Setting up and maintaining high availability for Atlantis would require additional configuration and infrastructure management.
Workflow Inflexibility: Atlantis necessitates creating a pull or merge request every time you want to run a Terraform plan. This can lead to a rigid workflow, potentially impeding agility and efficiency for teams that prefer more flexible ways of executing Terraform commands.
Verbose Git Output: Atlantis dumps its output in comments within the Git repository, which can make it difficult to follow and understand the sequence of events and changes. This verbosity may hinder clarity and make troubleshooting and analysis more challenging.
Manual Backend Configuration: To securely store state files, Atlantis requires configuring your own remote backend. This adds an additional setup and management overhead for ensuring proper state file storage and access controls.
Lack of access control: Anyone who stumbles upon your Atlantis instance can disable apply commands.
Consider these limitations when evaluating whether Atlantis is suitable for scaling your Terraform workflows. If your organization requires advanced features such as concurrency, high availability, flexible workflows, streamlined output, and professional support, you may need to explore alternative solutions such as env0, or evaluate managed services that offer these capabilities. Let’s take a look at some of these now.
Beyond Atlantis: How env0 Helps You Scale Your Terraform Workflows
As an alternative to Atlantis, you can use env0 to run Terraform commands from pull/merge request comments, just like Atlantis, with improved capabilities. env0 is a full IaC management solution that can adapt to your existing workflow and offer some improved workflows as well.
Sam Gabrail is the President of TeKanAid Solutions Inc., an IT training company focused on DevOps. Sam enjoys creating content to help practitioners upskill in DevOps principles and cloud-native technologies.