Terraform with GitOps

# atlantis.yaml — configuration file in repository root
# Tells Atlantis which Terraform projects to manage and how

version: 3

automerge: false          # Do not auto-merge PRs after apply — humans control merges
autodiscover:
  mode: enabled           # Automatically discover projects by finding *.tf files

# Explicit project definitions — override autodiscovery when needed
projects:
  - name: networking
    dir: infrastructure/foundation/networking
    workspace: default
    terraform_version: v1.6.3      # Pin Terraform version per project
    autoplan:
      when_modified:
        - "**/*.tf"                # Re-plan when any .tf file in the directory changes
        - "**/*.tfvars"
      enabled: true

  - name: payments-dev
    dir: infrastructure/services/payments
    workspace: dev
    terraform_version: v1.6.3
    apply_requirements:            # Must be met before atlantis apply is allowed
      - approved                   # PR must have at least 1 GitHub approval
    autoplan:
      when_modified: ["**/*.tf"]
      enabled: true

  - name: payments-prod
    dir: infrastructure/services/payments
    workspace: prod
    terraform_version: v1.6.3
    apply_requirements:
      - approved                   # At least 1 GitHub approval
      - mergeable                  # All required status checks must pass
    workflow: production           # Use the custom workflow defined below
    autoplan:
      enabled: false               # Production: never auto-plan on PR open

# Custom workflows — override the default init/plan/apply commands
workflows:
  production:
    plan:
      steps:
        - env:
            name: AWS_ROLE_ARN
            command: 'echo "arn:aws:iam::PROD_ACCOUNT:role/terraform-deployment-role"'
        - run: aws sts assume-role --role-arn $AWS_ROLE_ARN --role-session-name atlantis-prod
        - init
        - plan:
            extra_args: ["-var-file=environments/prod.tfvars"]
    apply:
      steps:
        - apply

# How Atlantis works in practice — PR lifecycle

# 1. Developer opens PR modifying infrastructure/services/payments/*.tf
# 2. Atlantis webhook fires automatically
# 3. Atlantis runs:
#    terraform init
#    terraform workspace select dev
#    terraform plan -out=atlantis-plan
# 4. Atlantis posts plan output as PR comment:

# ---
# atlantis plan for dir: infrastructure/services/payments workspace: dev
#
# Terraform will perform the following actions:
#   ~ aws_ecs_service.payments
#       + desired_count: 2 -> 3
# Plan: 0 to add, 1 to change, 0 to destroy.
# ---
# To apply this plan, comment: atlantis apply -d infrastructure/services/payments -w dev
# To re-plan: atlantis plan -d infrastructure/services/payments -w dev

# 5. Reviewer reads the plan in the PR and leaves a GitHub approval
# 6. Reviewer (or the developer) comments: atlantis apply
# 7. Atlantis applies the saved plan
# 8. Atlantis posts apply output as PR comment

# Key insight: the entire workflow happens in the PR — not in a separate CI/CD UI
# The developer and reviewer never leave GitHub to see what is being deployed

# HCP Terraform backend — state and runs are managed remotely
terraform {
  cloud {
    organization = "acme-corp"      # HCP Terraform organisation

    workspaces {
      name = "payments-production"  # Each workspace maps to a root module + environment
    }
  }
}

# In HCP Terraform UI or via API:
# - Connect workspace to GitHub repository and directory
# - Configure VCS trigger: run plan on PR, apply on merge
# - Store sensitive variables (AWS credentials, secrets) in workspace variables
# - Set apply method: auto-apply (GitOps) or manual approval (required for prod)
# - Configure run triggers: one workspace triggers another after apply

# HCP Terraform run triggers — chain workspaces in dependency order
# When networking workspace applies → automatically triggers platform workspace plan
# When platform workspace applies → automatically triggers services workspace plan
# This implements the foundation → platform → services dependency order from Lesson 36
# without any custom CI/CD pipeline code

# Spacelift is a similar concept with additional features:
# - Policy as code for run approval (OPA-based)
# - Drift detection with scheduled reconciliation runs
# - Stack dependencies (equivalent to HCP Terraform run triggers)
# - Module registry with private module hosting
# The key difference: Spacelift supports multiple IaC tools — Terraform, Pulumi,
# CloudFormation, Ansible — in a single platform

# The clean boundary — a complete GitOps + Terraform architecture

# Layer 1: Terraform (via Atlantis) manages cloud infrastructure
# Repository: github.com/acme/infrastructure
# Trigger: PR open → auto-plan, PR approval + "atlantis apply" → apply
# Manages: EKS cluster, VPCs, RDS, S3, IAM, ACM certificates

# Layer 2: Terraform (via Atlantis) manages cluster-level Kubernetes config
# Repository: github.com/acme/infrastructure (same repo, different directory)
# Manages: Namespaces, RBAC, StorageClasses, cluster add-ons via Helm
# Trigger: same Atlantis workflow

# Layer 3: ArgoCD manages application workloads
# Repository: github.com/acme/app-manifests
# ArgoCD watches this repo continuously
# Manages: Deployments, Services, Ingresses, HPA for application workloads
# Trigger: Push to main → ArgoCD detects diff → syncs to cluster automatically

# The boundary is clear:
# "Does this change when application code changes?"
#   YES → ArgoCD (image tags, replica counts, environment variables)
#   NO  → Terraform (VPCs, databases, cluster size, IAM roles)

# A common mistake: using ArgoCD to apply Terraform via a Job or runner pod
# This breaks the boundary — Terraform state becomes unmanageable,
# drift detection stops working, and ArgoCD cannot meaningfully diff Terraform state
# Keep ArgoCD for Kubernetes manifests. Use Atlantis or HCP Terraform for Terraform.

# Spacelift drift detection — scheduled reconciliation for Terraform
# This implements the "continuously reconciled" GitOps principle for infrastructure

# Spacelift stack configuration (in Spacelift UI or API):
# - drift_detection: enabled
# - drift_detection_schedule: "0 */6 * * *"  (every 6 hours)
# - drift_detection_reconcile: false          (detect only — do NOT auto-apply)

# When drift is detected:
# 1. Spacelift runs terraform plan against the current state
# 2. If the plan shows changes (drift), Spacelift creates a drift notification
# 3. A human reviews the drift and decides: apply (fix the drift) or ignore
# 4. The notification includes what drifted — a security group rule changed manually,
#    an instance type was modified in the console, a tag was removed

# Why "detect but do not auto-reconcile" for infrastructure:
# Auto-reconciliation on a Kubernetes Deployment is safe — it changes a running pod
# Auto-reconciliation on a database parameter change might cause a restart
# Auto-reconciliation removing a security group rule that was added for an incident
#   could delete the engineer's emergency access mid-incident

# The safer GitOps model for Terraform:
# DETECT drift automatically
# NOTIFY the team
# HUMAN decides to apply or document the deviation

# Full auto-reconcile is appropriate only for:
# - Dev and sandbox environments where drift does not matter
# - Resources where changes are truly zero-risk (tags, descriptions, labels)
# - After thorough testing proves the reconciliation does not cause disruption