Atlantis Documentation

Atlantis executes terraform plan and apply on its host server. To work, it requires the same provider credentials you would use when running Terraform locally.

Common methods for providing credentials include:

• Cloud Identity/Roles: Use native cloud mechanisms like AWS EC2 Roles or GCE Instance Service Accounts.
• Environment Variables: Set variables like AWS_ACCESS_KEY on the Atlantis server.
• Config Files: Create necessary configuration files (e.g., ~/.aws/credentials) on the Atlantis server.
• Vault: Use the HashiCorp Vault Provider to obtain credentials.
• Deployment-specific mechanisms: Use the specific credential mechanisms provided by the Atlantis Helm Chart or AWS Fargate Module.

Rule of thumb: If you can ssh or exec into the Atlantis server and run terraform commands successfully, Atlantis will work.

For advanced customization not supported by extra_args, you can completely override init, plan, or apply using the run step.

Requirements for custom plan/apply:

• You MUST output the plan using -out $PLANFILE because Atlantis expects plans to be in a specific location.
• For apply, you must use the $PLANFILE environment variable.
• If using workspaces, select the workspace using the $WORKSPACE environment variable.
• Use the output: hide option on a run step if you want to prevent command output from appearing in the Atlantis PR comment.

# atlantis.yaml or repos.yaml
workflows:
  myworkflow:
    plan:
      steps:
      - run:
          command: terraform init -input=false
          output: hide
      - run: terraform workspace select $WORKSPACE
      - run: terraform plan -input=false -refresh -out $PLANFILE
    apply:
      steps:
      - run: terraform apply $PLANFILE

Deploying Atlantis to Google Cloud Run allows for a serverless, auto-scaling architecture. When deploying, use a dedicated service account for least-privilege security and configure a min_instance_count of at least 1 to avoid cold starts and the loss of in-memory ephemeral storage.

Key environment variables for a Redis-backed Cloud Run deployment include:

• ATLANTIS_LOCKING_DB_TYPE: Set to redis.
• ATLANTIS_REDIS_HOST: The host of your Redis instance.
• ATLANTIS_REDIS_DB: The Redis database index (e.g., 0).
• ATLANTIS_DATA_DIR: The path for writable ephemeral storage.
• ATLANTIS_USE_TF_PLUGIN_CACHE: Set to true to optimize provider downloads.

resource "google_cloud_run_v2_service" "atlantis_management" {
  provider             = google-beta
  name                 = "atlantis-management"
  location             = "your-region"
  deletion_protection  = false
  ingress              = "INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER"
  invoker_iam_disabled = true
  launch_stage         = "GA"

  template {
    scaling {
      min_instance_count = 1
      max_instance_count = 1
    }
    execution_environment = "EXECUTION_ENVIRONMENT_GEN2"
    service_account       = google_service_account.atlantis_management.email
    containers {
      image = "ghcr.io/runatlantis/atlantis:v0.35.1"
      resources {
        limits = {
          cpu    = "1"
          memory = "2Gi"
        }
      }
      volume_mounts {
        name       = "atlantis"
        mount_path = "/app/atlantis"
      }
      env {
        name  = "ATLANTIS_PORT"
        value = "8080"
      }
      env {
        name  = "ATLANTIS_DATA_DIR"
        value = "/app/atlantis"
      }
      env {
        name  = "ATLANTIS_USE_TF_PLUGIN_CACHE"
        value = "true"
      }
      env {
        name  = "ATLANTIS_LOCKING_DB_TYPE"
        value = "redis"
      }
      env {
        name  = "ATLANTIS_REDIS_HOST"
        value = google_redis_instance.atlantis.host
      }
      env {
        name  = "ATLANTIS_REDIS_DB"
        value = "0"
      }
      env {
        name  = "ATLANTIS_ATLANTIS_URL"
        value = "https://management.atlantis.acme.com"
      }
      env {
        name  = "ATLANTIS_REPO_CONFIG_JSON"
        value = jsonencode(yamldecode(file("${path.module}/atlantis/management.yaml")))
      }
    }
    vpc_access {
      egress = "ALL_TRAFFIC"
      network_interfaces {
        network    = "your-network-id"
        subnetwork = "your-subnetwork-id"
      }
    }
    volumes {
      name = "atlantis"
      empty_dir {
        medium     = "MEMORY"
        size_limit = "5Gi"
      }
    }
  }
  project = "your-project-id"
}