Backend Configuration

mkdir terraform-lesson-16
cd terraform-lesson-16
touch versions.tf variables.tf main.tf outputs.tf backend-dev.hcl backend-prod.hcl .gitignore

variable "environment" {
  description = "Deployment environment — controls resource naming and sizing"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be dev, staging, or prod."
  }
}

variable "region" {
  description = "AWS region"
  type        = string
  default     = "us-east-1"
}

# A simple resource to demonstrate multi-environment deployment
resource "aws_s3_bucket" "app" {
  bucket = "lesson16-app-${var.environment}-${data.aws_caller_identity.current.account_id}"

  tags = {
    Name        = "lesson16-app-${var.environment}"
    Environment = var.environment
    ManagedBy   = "Terraform"
  }
}

# Data source — current AWS account for unique bucket naming
data "aws_caller_identity" "current" {}

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  # Partial backend configuration — static values only
  # The key (state file path) is supplied at terraform init time via -backend-config
  # This allows the same codebase to deploy to dev, staging, and prod
  # without editing this file between deployments
  backend "s3" {
    bucket         = "acme-terraform-state-123456789012"  # Static — same for all environments
    region         = "us-east-1"                           # Static — same for all environments
    encrypt        = true                                  # Static — always true
    dynamodb_table = "terraform-state-lock"               # Static — same for all environments
    # key is intentionally omitted — supplied at init time
  }
}

provider "aws" {
  region = var.region
}

# backend-dev.hcl — backend configuration overrides for the dev environment
# Passed to terraform init via: terraform init -backend-config=backend-dev.hcl
# This file CAN be committed to Git — it contains no secrets

key = "lesson-16/dev/terraform.tfstate"  # Unique state path for dev

# backend-prod.hcl — backend configuration overrides for the prod environment
# Passed to terraform init via: terraform init -backend-config=backend-prod.hcl

key = "lesson-16/prod/terraform.tfstate"  # Unique state path for prod

# Deploy to dev — init with dev backend config, apply with dev variable
terraform init -backend-config=backend-dev.hcl
terraform apply -var="environment=dev"

# Deploy to prod — reconfigure backend to point at prod state, apply with prod variable
terraform init -reconfigure -backend-config=backend-prod.hcl
terraform apply -var="environment=prod"

# Pass individual backend arguments as key=value pairs
# Multiple flags combine — all are merged into the final backend configuration
terraform init \
  -backend-config="key=lesson-16/staging/terraform.tfstate" \
  -backend-config="bucket=acme-terraform-state-123456789012" \
  -backend-config="region=us-east-1"

# In a CI/CD pipeline — environment variables drive the key path
# The pipeline sets ENV before running Terraform
export ENV="staging"

terraform init \
  -backend-config="key=lesson-16/${ENV}/terraform.tfstate" \
  -reconfigure

# .github/workflows/terraform.yml
# Complete GitHub Actions workflow for Terraform deployment
# This is YAML — not HCL — but the Terraform commands inside are identical

name: Terraform Deploy

on:
  push:
    branches: [main]   # Deploy to prod on every merge to main
  pull_request:
    branches: [main]   # Plan-only on pull requests — no apply

jobs:
  terraform:
    runs-on: ubuntu-latest
    environment: ${{ github.ref == 'refs/heads/main' && 'production' || 'preview' }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "~> 1.6"

      - name: Terraform Init
        env:
          # AWS credentials from GitHub secrets — never hardcoded
          AWS_ACCESS_KEY_ID:     ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          terraform init \
            -input=false \
            -backend-config="key=lesson-16/${{ github.ref == 'refs/heads/main' && 'prod' || 'dev' }}/terraform.tfstate"

      - name: Terraform Plan
        env:
          AWS_ACCESS_KEY_ID:     ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          # Sensitive Terraform variables injected as TF_VAR_ environment variables
          TF_VAR_db_password:    ${{ secrets.DB_PASSWORD }}
        run: |
          terraform plan \
            -input=false \
            -var="environment=${{ github.ref == 'refs/heads/main' && 'prod' || 'dev' }}" \
            -out=tfplan

      - name: Terraform Apply
        # Only apply on pushes to main — not on pull requests
        if: github.ref == 'refs/heads/main'
        env:
          AWS_ACCESS_KEY_ID:     ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          TF_VAR_db_password:    ${{ secrets.DB_PASSWORD }}
        run: |
          terraform apply \
            -input=false \
            -auto-approve \
            tfplan   # Apply the exact plan reviewed in the previous step

# Azure backend — equivalent of S3 + DynamoDB for Azure-based teams
# Blob leases provide native locking — no separate locking resource needed

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }

  backend "azurerm" {
    resource_group_name  = "rg-terraform-state"          # Resource group for the storage account
    storage_account_name = "acmeterraformstate"           # Must be globally unique, 3-24 chars
    container_name       = "tfstate"                      # Blob container — like a folder
    key                  = "PROJECT/ENV/terraform.tfstate" # Unique path — override at init time

    # Authentication — use Azure CLI credentials locally, managed identity in CI/CD
    # use_azure_cli_auth = true  # Uncomment for local development
    # use_msi           = true   # Uncomment for Azure-hosted CI/CD (managed identity)
  }
}

provider "azurerm" {
  features {}  # Required empty features block for azurerm provider
}

# GCS backend — for GCP-based teams
# Object locking is native to GCS — no separate locking resource needed

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
  }

  backend "gcs" {
    bucket = "acme-terraform-state"   # GCS bucket name — must exist before terraform init
    prefix = "lesson-16/dev"          # Prefix = folder path within the bucket
    # State file stored at: gs://acme-terraform-state/lesson-16/dev/default.tfstate
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}