Skip to main content
Guides
Spaces

2. Use of Atlantis

Pre-requisites​

  • About terraform

Overview​

Atlantis is an open-source tool designed to automate Terraform operations and streamline infrastructure management workflows. It integrates with version control systems like GitHub, GitLab, and Bitbucket to manage Terraform configurations and execution. By automating Terraform plans and applies based on pull request comments, Atlantis facilitates collaborative and controlled infrastructure changes.

This document describes the integration of GitHub, Atlantis, and Terraform for managing infrastructure updates. In this setup, a GitHub app monitors changes in the deployment repository and triggers events that are received by an Atlantis VM hosted on GCP. Atlantis listens for these events, generates Terraform plans, and applies configurations based on commands issued in GitHub pull request comments. This ensures that Terraform plans and applies are reviewed and executed in a systematic and transparent manner. Basically, Atlantis centralizes the execution of Terraform commands, maintaining state lock and providing detailed logs directly in pull request comments.

Components​

  1. GitHub App - Marketplace Atlantis
    • Purpose: Monitors specific repository events such as pull requests in our case.
    • Functionality: Sends webhook notifications to the Atlantis VM when a pull request is created, updated or on comments in pull request.
  2. Atlantis VM
    • Hosting: Hosted on GCP.
    • Role: Receives webhook notifications, reads Terraform configurations from the repository as it can read deployment repository data ^only , and handles Terraform operations (plan and apply) based on comments.
  3. Terraform
    • Purpose: M
    • anages infrastructure updates based on configurations stored in the repository and state stored in GCP Storage Cloud Bucket with filename default.tfstate.

Configuration​

  1. GitHub App Setup
    • Install the GitHub app on the deployment repository to listen for pull request and issue events.
    • Configure Webhooks: Ensure that the webhook notifications are properly set up to point to the Atlantis VM.
  2. Atlantis VM Configuration
    • Read Access: Ensure that Atlantis has read permissions to access Terraform configurations in the repository.
    • Webhook Handling: Configure Atlantis to process webhook notifications and execute Terraform commands.
  3. Terraform Commands
    • Plan: Generates an execution plan showing proposed changes.
    • Apply: Applies the changes to the infrastructure based on the plan.

Workflow​

  1. Pull Request Creation
    • Action: A contributor creates or updates a pull request in the deployment repository.
    • Trigger: The GitHub app detects the event and sends a webhook notification to the Atlantis VM.
  2. Webhook Notification
    • Action: The Atlantis VM receives the webhook notification containing details of the pull request.
    • Functionality: Atlantis VM uses its read permissions to access the Terraform configuration files in the repository.
  3. Terraform Planning
    • Action: Atlantis reads the Terraform configurations and generates a plan.
    • Output: Atlantis VM comments the Terraform plan on the pull request, allowing contributors to review the proposed changes.
  4. Triggering Terraform Operations
    • Actions:
      • Plan: To trigger a Terraform plan, a reviewer or contributor comments on the pull request with either:
        • atlantis plan
        • atlantis plan -p [environment] (where [environment] can be acceptance or production).
      • Apply: To trigger a Terraform apply, a reviewer or contributor comments with:
        • To apply the changes, the pull request should be approved by at least one of the reviewers first and then below given commands can work.
        • atlantis apply
        • atlantis apply -p [environment] (where [environment] can be acceptance or production).
  5. Execution and Review
    • Action: Atlantis executes the Terraform plan or apply commands based on the comments.
    • Output: The results are commented back on the pull request, informing contributors of the changes made and then the pull request is merged automatically. The auto-merge feature can be disabled from atlantis.yaml in root of deployment repository.

Conclusion​

This setup ensures that Terraform plans and applies are managed in a controlled and reviewable manner, leveraging GitHub for event management and Atlantis for Terraform execution. By integrating these tools, the process becomes automated and transparent, facilitating efficient infrastructure management and collaboration.