Atlantis serves as a tool for automating Terraform operations via pull requests. This tool facilitates collaboration between developers and operators in making infrastructure adjustments directly within their version control system. By responding to webhooks from GitHub, GitLab, Bitbucket, or Azure DevOps, Atlantis executes a terraform plan and applies commands in response to pull request comments.

‍

Additionally, Atlantis offers approvals and feedback for each Terraform change, all seamlessly integrated with the version control system.Atlantis Video Walk-throughvideoOur ConfigurationNow, let's get into our setup.

Atlantis Setup and Overview

The Default Atlantis Workflow

The default Atlantis workflow outlines the method for creating and deploying software applications. This approach centers around a Git-based workflow, ensuring efficient development and deployment processes.

The image above illustrates how Atlantis operates by utilizing merge requests and webhooks from the version control system (VCS). But, let us explain in a bit more detail.

Developer Commit and Push:

The developer commits and pushes code changes to a development or feature branch, where they possess the necessary permissions.

Merge Request Creation:

A merge request is initiated by the developer, indicating that their code changes are ready for review and integration.

Webhook Trigger:

The merge request triggers a webhook from the VCS to Atlantis, initiating a Terraform Plan process.

Terraform Plan Execution:

Atlantis executes the Terraform Plan and showcases the output within the comments section of the merge request. The command Atlantis plan can be used in the comments for manual execution.

Approval and Terraform Apply:

After plan approval, an approver triggers the terraform apply command within Atlantis by typing atlantis apply in a new comment, initiating another webhook.

Infrastructure Changes Application:

Atlantis executes the terraform apply command, implementing the approved infrastructure changes.

Merge into Main Branch:

Following successful application, the development branch can be merged into the main branch, integrating the approved code changes into the main codebase.This workflow ensures a structured process where provisioning and verification occur before merging code changes, particularly beneficial in a development environment.

The Inner Working of Atlantis

Atlantis simplifies the review and execution of Terraform workflows through seamless integration with Version Control Systems (VCS), automating critical processes. This enhances collaboration, visibility, and version control integration, ensuring a streamlined Terraform workflow within teams and organizations. Let's delve into a more detailed understanding:

‍

Setup:

Atlantis requires an initial setup and configuration. This involves installing and configuring the Atlantis server, which can be hosted on-premises or in the cloud. The server is pivotal, responsible for receiving and processing VCS requests and executing Terraform commands.

‍

VCS Integration:

Atlantis smoothly combines with different Version Control Systems (VCS) like GitHub, GitLab, Azure DevOps, or Bitbucket. This integration is accomplished by establishing webhooks or monitoring events initiated by pull requests, commits, or branches.

‍

Pull Request Creation:

Developers initiate a pull request in the VCS repository, encapsulating the Terraform code changes they wish to review and apply.

‍

Event Trigger:

The VCS notifies Atlantis of the pull request creation, triggering an event that initiates the workflow.

‍

Workspace Creation:

Atlantis dynamically creates an isolated workspace dedicated to the pull request. This ensures that Terraform commands are executed within a confined environment, isolating the state of infrastructure changes from other workspaces.

‍

Atlantis Configuration:

Atlantis reads configuration details from a file (e.g., atlantis.yaml) within the repository or a default configuration file. This file defines Atlantis's behavior and settings, specifying aspects like the Terraform version, backend configuration, and permitted operations.

‍

Command Execution:

Atlantis automates the execution of Terraform commands based on the pull request event. Commands terraform init, terraform plan, terraform apply, and terraform destroy are usually used for this. Atlantis performs these commands within the pull request's workspace, utilizing the appropriate Terraform binary.

‍

Output and Feedback:

Atlantis captures the output of executed Terraform commands, including plan or apply results. This output is presented within the pull request as comments, offering visibility to reviewers and stakeholders. This facilitates the review of proposed infrastructure changes, allowing for feedback, discussions, and modifications.

‍

Approval Process:

Reviewers and stakeholders engage with the pull request, providing feedback, suggestions, or approvals. The discussion unfolds within the VCS interface, ensuring easy collaboration and consensus-building on the proposed changes.

‍

Merge and Deployment:

Upon approval, the pull request is merged into the target branch, triggering the deployment of Terraform changes through standard VCS merge processes. Typically, the Terraform code is executed again in the designated deployment environment outside of Atlantis.

‍

Cleanup:

Post-merge or closure of the pull request, Atlantis conducts cleanup, removing associated workspaces and temporary files, ensuring a tidy environment, and eliminating state information.

Terraform and Terragrunt Projects: Effective Management

Managing Terraform and Terragrunt involves implementing best practices to ensure efficient and reliable infrastructure provisioning and management. Here are key aspects to consider:

‍

Code Organization:

Proper code organization is crucial. Follow modularization techniques to break down infrastructure code into reusable and maintainable modules. This simplifies management and encourages code reuse across projects.

‍

Version Control:

Utilize a version control system like Git to track changes in Terraform and Terragrunt code. Version control supports collaboration, provides a history of modifications, facilitates code reviews, and aids in rolling back changes if needed.

‍

Infrastructure State Management:

Terraform uses state files to track the current infrastructure state. Manage these files appropriately. Consider a remote backend (e.g., Amazon S3, Azure Blob Storage, or env0) to centrally store state files, promoting collaboration among team members.

‍

Workspace Management:

Leverage Terraform workspaces to handle multiple instances of the same infrastructure concurrently (e.g., staging and production environments). Effective workspace management prevents changes in one workspace from affecting others. Develop a clear strategy for workspace creation and usage to avoid conflicts and maintain isolation.

‍

Dependency Management:

Terragrunt, acting as a wrapper for Terraform, enhances capabilities with features like remote state management and dependency handling. When managing Terraform and Terragrunt, keep Terragrunt versions and dependencies updated to leverage the latest features and bug fixes.

‍

Testing and Validation:

Implement a thorough testing and validation process for Terraform and Terragrunt code. Utilize tools such as terraform validate, terraform fmt, and static code analysis tools to ensure proper syntax, formatting, and adherence to best practices. Additionally, consider incorporating automated unit tests and integration tests to validate infrastructure code behavior and correctness.

‍

Infrastructure as Code (IaC) Pipelines:

Create pipelines for continuous integration and deployment (CI/CD) to automate the deployment and testing of Terraform and Terragrunt code. For performing validation tests, creating execution plans, and implementing infrastructure changes, use continuous integration and delivery (CI/CD) platforms like CircleCI, Jenkins, or GitLab CI/CD.

By using this method, infrastructure installations are guaranteed to be repeatable, standardized processes are ensured, and manual error is reduced.

‍

Change Management and Approval:

Define a change management process to verify, review, and approve infrastructure changes. Integrate Terraform and Terragrunt workflows with pull request systems such as GitHub or GitLab for code reviews, promoting collaboration and proper documentation of changes.

Atlantis for Terraform and Terragrunt Projects: Benefits

Atlantis is a popular automation tool for managing Terraform and Terragrunt workflows for enterprises that use infrastructure-as-code.

• Collaboration:  Atlantis streamlines collaboration by providing a centralized platform for feedback and reviews.
• Infrastructure state management: Since it handles isolation and management of Terraform state files, it prevents conflicts that can happen as a side effect of multiple developers changing the infrastructure.
• Feedback and review:  It allows teams to discuss and review changes directly from the request pull interface.
• Visibility: Atlantis offers a bird's eye view of the Terraform plan, thereby helping reviewers understand the changes made to the infrastructure, as well as their impact.
• CI/CD integration: Due to its seamless integration with CI and CD, it enables continuous deployment of infrastructure changes.

When Should You Use Atlantis?

Consider Atlantis when aiming to boost teamwork, streamline Terraform workflows, uphold policies, and enhance the code review process in your infrastructure-as-code projects. Atlantis establishes a well-organized and effective workflow, fostering improved collaboration among team members and mitigating the risk of errors in infrastructure deployments.

Here's how Atlantis can help you: 

Team Collaboration Enhancement: If multiple team members or developers are simultaneously making changes to Terraform code, Atlantis can simplify collaboration. It acts as a centralized platform for code review, ensuring that all code alterations undergo a standardized review process before impacting the infrastructure.

‍

Pull Request Streamlining: For those relying on pull requests in their version control system (VCS) for code review and merging, Atlantis seamlessly integrates with VCS platforms. It enables the automatic triggering of Terraform commands within the context of pull requests, supplying reviewers with essential information and output to make well-informed decisions about infrastructure changes.

‍

Workflow Automation and Consistency: If there's a desire to automate Terraform workflows and maintain consistency across various environments, Atlantis is a valuable tool. It automates Terraform command execution, including initialization, planning, and applying changes, diminishing the need for manual intervention and minimizing the likelihood of human error.

‍

Efficient Infrastructure State Management: For those grappling with challenges related to managing the state of Terraform deployments, Atlantis helps in isolating and managing state files. The workspace-based approach ensures that each pull request or branch has its dedicated workspace and state, preventing conflicts when multiple developers concurrently work on infrastructure changes.

‍

Policy Enforcemen: tIn cases where policies and best practices for infrastructure changes must be enforced, Atlantis can be configured to use conftest policy checking. Common use cases include prohibiting the use of specific modules, verifying attributes of a resource during creation, detecting inadvertent resource deletions, and safeguarding against security vulnerabilities, such as exposing secure ports to the public.

‍

Integration with CI/CD Pipelines: For those with existing CI/CD pipelines or workflows handling infrastructure changes, Atlantis seamlessly integrates into the existing setup. It functions as a trigger for Terraform commands within the pipeline, ensuring that infrastructure alterations undergo automatic testing, review, and deployment.

‍

Pre-Workflow Hooks: Configure Atlantis to execute pre-workflow hooks, validate code syntax, enforce compliance requirements, and conduct security checks. These checks serve to identify potential issues before implementing changes to the infrastructure. Utilize tools such as tflint, terraform fmt, or custom scripts to uphold code quality and compliance with standards.

A Quick Guide to Using Atlantis

Folder Structure and Repository Config

For full access to the repository configuration, you will have to fork the repository. The hierarchy of the folders is shown below.

Setting Up and Installing Atlantis

To use Atlantis locally, you can refer to the official instructions. In essence, you'll needTerraform, Atlantis, and ngrok. By following the steps outlined in this guide, all of these components will be automatically installed for you in your Codespace environment.

Google Credentials

Create a new key in Service Accounts under IAM & Admin in your Google Cloud project.

To store the JSON file on your computer, save it as "gcp-secret-key.json." Ensure that this file is included in your .gitignore to maintain security. Within this repository, you'll find a sample file named "gcp-secret-key-example.json." Save your JSON file there and rename it to "gcp-secret-key.json."Verify that the correct path is indicated in the GOOGLE_APPLICATION_CREDENTIALS environment variable within the "start.sh" file.

<pre class="codeWrap"><code>export GOOGLE_APPLICATION_CREDENTIALS="./gcp-secret-key.json"</code></pre>

Launch the Atlantis Server

To deploy Atlantis, open a new Codespaces terminal tab and execute the script below.

<pre class="codeWrap"><code>./start.sh</code></pre>

You can now run the application by clicking on the globe icon under the PORTS tab in Codespaces.

Server Side

Atlantis server-side settings are shown below(the start.sh file).

<pre class="codeWrap"><code> #!/usr/bin/bash
URL="https://{YOUR_HOSTNAME}.ngrok.io"
SECRET="{YOUR_RANDOM_STRING}"
TOKEN="{YOUR_TOKEN}"
USERNAME="samgabrail"
REPO_ALLOWLIST="github.com/samgabrail/env0-atlantis-gcp" #GitHub example: REPO_ALLOWLIST="github.com/runatlantis/atlantis"
*Any environment variables required for auth
export GOOGLE_APPLICATION_CREDENTIALS="path-to-json-file"

atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST"
</code></pre>

Including a Developer in Our Repo

For a developer to submit a pull request to a dev branch, let's invite them to join our repo.

It is important to protect the main branch.

Using Atlantis

Now, as a developer, you have the capability to implement changes in the development branch and subsequently initiate a pull request. This action will trigger an automatic execution of a Terraform plan. If content with the plan, you can proceed to execute "atlantis apply," which will implement the modifications.

‍

Subsequently, the repository owner can give approval to the pull request, leading to the merging of the development branch with the main branch.To inspect the Terraform plan results, you can either check the comments in the pull request or, by navigating to GitHub and clicking on "details," access the output through the Atlantis UI.

‍

Atlantis Constraints and Issues

Addressing Terraform Challenges: When Atlantis Falls Short

While Atlantis proves effective for smaller organizations, it could encounter hurdles when attempting to scale for more advanced needs. Take a look at the checklist below, and if you find yourself ticking off more than half of the items, you've likely reached Atlantis' limitations and should explore alternative solutions.

‍

Self-Hosting and Community Reliance: Atlantis, being an open-source tool, demands self-hosting, management, and ongoing support from your team. Depending on the community for support and updates means investing extra effort in maintaining and troubleshooting the tool, rather than relying on dedicated vendor support.

‍

Concurrency Limitations: Atlantis operates in a single-threaded manner, potentially becoming a bottleneck when managing larger environments. The inability to process multiple tasks concurrently may result in delays and diminished performance during the execution of Terraform commands and infrastructure changes.

‍

Limited High Availability: Atlantis lacks built-in high availability features out of the box. This proves challenging for organizations needing a resilient and highly available infrastructure for Terraform workflows. Achieving high availability for Atlantis demands additional configuration and infrastructure management.

‍

Workflow Rigidity: Atlantis requires creating a pull or merge request each time you wish to run a Terraform plan. This rigid workflow could impede agility and efficiency for teams favoring more flexible approaches to executing Terraform commands.

‍

Verbose Git Output: Atlantis deposits its output in Git repository comments, potentially complicating the understanding of events and changes. This verbosity poses challenges to clarity, making troubleshooting and analysis more difficult.

‍

Manual Backend Configuration: For secure state file storage, Atlantis mandates configuring your remote backend. This introduces extra setup and management overhead to ensure proper state file storage and access controls.

‍

Access Control Absence: Anyone encountering your Atlantis instance can disable apply commands, indicating a lack of access control.

When determining Atlantis' suitability for scaling your Terraform workflows, it's essential to factor in these limitations. If your organization demands advanced features like concurrency, high availability, flexible workflows, streamlined output, and professional support, exploring alternative solutions becomes imperative.

Options such as env0 or managed services that provide these capabilities should be considered. Let's delve into some of these alternatives now.

Exploring env0: Enhancing Your Terraform Workflows Beyond Atlantis

If you're in need of an alternative to Atlantis, consider using env0 for executing Terraform commands through pull/merge request comments. Much like Atlantis, env0 boasts enhanced capabilities. As a comprehensive Infrastructure as Code (IaC) management solution, env0 can seamlessly integrate into your existing workflow while introducing some improved processes.