Setting Up Atlantis PR Automation with Terramate.md

Guide: Setting Up Atlantis PR Automation with Terramate

This concise guide will walk you through setting up Atlantis for pull request (PR) automation in combination with Terramate, facilitating a more collaborative and automated workflow for managing infrastructure as code (IaC) via GitHub. We assume a working knowledge of Terraform, GitHub, and basic CI/CD principles. Overview

Integrating Atlantis with Terramate enhances your team's ability to review, plan, and apply Terraform changes directly from GitHub PRs. This process ensures infrastructure changes are executed securely and efficiently, with all changes codified and subject to peer review. Prerequisites

• Terraform, Terramate, and Atlantis installed.
• A GitHub account and repository for your infrastructure code.
• aws-vault for managing AWS credentials securely (used in this setup).
• Ngrok for exposing your local development environment to the internet.

Configuration Steps

1. Prepare Configuration Files

Create a directory named terramate-atlantis and within it, two configuration files: atlantis.yaml and repos.yaml.

atlantis.yaml:

version: 3
projects:
  - name: poc
    dir: .
    workspace: poc
    workflow: terramate
    autoplan:
      enabled: true

repos.yaml

repos:
- id: "/.*/"
  workflow: terramate
  allowed_overrides: [apply_requirements, workflow]
  allow_custom_workflows: true

workflows:
  terramate:
    plan:
      steps:
        - run: terramate fmt --check
        - run: terraform fmt -recursive -check -diff
        - run: terramate generate
        - run: terramate list --changed
        - run: terramate run  --changed -- terraform init -lock-timeout=5m
        - run: terramate run  --changed -- terraform validate
        - run: terramate run  --changed -- terraform plan -out out.tfplan -lock=false
    
    apply:
      steps:
        - run: terramate run -- terraform apply -auto-approve out.tfplan

2. Set Up Ngrok

Use Ngrok to forward your Atlantis server's port (default 4141) to the internet, capturing the provided URL for later use.

ngrok http 4141

3. Configure GitHub Repository

• Fork or use an existing GitHub repository for your Terraform code.
• Webhook Setup: In your GitHub repository settings, add a webhook pointing to your Ngrok URL appended with /events (e.g., https://1234abcd.ngrok.io/events). This ensures Atlantis receives notifications for push and pull_request events.

4. Run Atlantis Server

Execute the Atlantis server command within an aws-vault session to ensure secure AWS access:

aws-vault exec <aws-profile> -- atlantis server \
  --atlantis-url="<Ngrok URL>" \
  --gh-user="<GitHub Username>" \
  --gh-token="<GitHub Personal Access Token>" \
  --gh-webhook-secret="<Webhook Secret>" \
  --repo-allowlist="github.com/<GitHub Username>/*,github.com/<GitHub Username>/terramate-aws/" \
  --repo-config=repos.yaml \
  --config=atlantis.yaml \
  --checkout-depth=0 \
  --checkout-strategy=merge

Ensure to replace placeholders with your actual information, including the Ngrok URL, GitHub username, personal access token, and the AWS profile name used with aws-vault.

Workflow Overview

1. Branch and PR: Create a new branch, make changes, and open a PR in your GitHub repository.
2. Plan and Review: Comment atlantis plan in the PR to execute the planning phase. Review the generated plan within the PR comments.
3. Apply Changes: After review, comment atlantis apply to apply the Terraform changes.

By following these steps, you set up a secure and automated workflow for managing infrastructure changes, leveraging Atlantis for automation and Terramate for enhancing Terraform's capabilities. This approach facilitates a collaborative review process, ensuring all changes are thoroughly vetted before application.