Advanced

# multi-cloud/main.tf
# => Multi-cloud configuration using provider aliases

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"   # => AWS provider from Terraform registry
      version = "~> 5.0"          # => Accept 5.x releases, reject 6.x
    }
    azurerm = {
      source  = "hashicorp/azurerm" # => Azure provider from Terraform registry
      version = "~> 3.0"            # => Accept 3.x releases
    }
    google = {
      source  = "hashicorp/google"  # => GCP provider from Terraform registry
      version = "~> 5.0"            # => Accept 5.x releases
    }
  }
}

provider "aws" {
  region = "us-east-1"              # => Primary AWS region
  # => Credentials from AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars
}

provider "aws" {
  alias  = "eu"                     # => Alias distinguishes this from default
  region = "eu-west-1"              # => Secondary region for AWS EU workloads
  # => Usage: provider = aws.eu in resource blocks
}

provider "azurerm" {
  features {}                       # => Required empty block for Azure provider
  subscription_id = var.azure_subscription_id
  # => Azure subscription to deploy into
}

provider "google" {
  project = var.gcp_project_id      # => GCP project identifier
  region  = "us-central1"           # => Default region for GCP resources
}

# AWS S3 bucket in primary region
resource "aws_s3_bucket" "primary" {
  bucket = "my-app-primary-data"    # => Bucket name (globally unique)
  # => Uses default aws provider (us-east-1)
}

# AWS S3 bucket in EU region (using alias)
resource "aws_s3_bucket" "eu_backup" {
  provider = aws.eu                 # => Override provider for this resource
  bucket   = "my-app-eu-backup"     # => Bucket in eu-west-1
  # => provider = aws.eu routes to the aliased provider block
}

# Azure blob storage for compliance
resource "azurerm_storage_account" "compliance" {
  name                     = "myappcompliancedata"
  resource_group_name      = var.azure_rg_name
  location                 = "West Europe"          # => Azure region
  account_tier             = "Standard"             # => Storage tier (Standard/Premium)
  account_replication_type = "GRS"                  # => Geo-redundant replication
  # => GRS replicates data to paired Azure region automatically
}

# GCP Cloud Storage for analytics
resource "google_storage_bucket" "analytics" {
  name     = "my-app-analytics-${var.gcp_project_id}"
  location = "US"                   # => Multi-region bucket for redundancy
  # => Appending project ID ensures globally unique name
}

# backend/main.tf
# => Terraform Cloud backend configuration

terraform {
  cloud {
    organization = "my-org"         # => Terraform Cloud organization name
    # => Must match your organization in app.terraform.io

    workspaces {
      name = "production-infra"     # => Specific workspace name
      # => Workspace holds state, variables, and run history
      # => Alternative: tags = ["production"] selects by tag
    }
  }

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

# Variables stored in Terraform Cloud (not in code)
# => In Terraform Cloud UI: workspace → Variables tab
# => Sensitive variables (AWS credentials) marked sensitive, never shown in logs
# => Non-sensitive variables visible to all workspace members

variable "environment" {
  type        = string              # => String variable type
  description = "Deployment environment (staging/production)"
  # => Set in Terraform Cloud workspace variables
}

variable "instance_count" {
  type        = number              # => Number type for validation
  description = "Number of application instances"
  default     = 2                   # => Override in workspace variables
}

resource "aws_instance" "app" {
  count         = var.instance_count  # => Creates multiple instances
  ami           = data.aws_ami.amazon_linux.id
  instance_type = "t3.medium"

  tags = {
    Environment = var.environment     # => Tag from workspace variable
    ManagedBy   = "terraform-cloud"   # => Audit trail tag
    WorkspaceId = terraform.workspace # => Built-in workspace name reference
  }
  # => terraform.workspace returns current workspace name
}

# variable-sets/main.tf
# => Demonstrates referencing shared variable sets via provider configuration
# => Variable sets are configured in Terraform Cloud UI, not in HCL

terraform {
  cloud {
    organization = "my-org"
    workspaces {
      tags = ["app-tier"]           # => All workspaces tagged "app-tier" use this config
      # => Tag-based workspace selection enables dynamic workspace discovery
    }
  }
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

# => Variables below are defined in a Terraform Cloud variable set
# => Variable set "AWS Global Config" applied to all "app-tier" workspaces
# => Variables: aws_region, common_tags, vpc_id, subnet_ids

variable "aws_region" {
  type        = string
  description = "AWS region - provided by variable set"
  # => Value injected from variable set at plan time
  # => No default needed; Terraform Cloud enforces the variable set
}

variable "common_tags" {
  type = map(string)
  description = "Common resource tags - provided by variable set"
  # => Example value from variable set:
  # => { "CostCenter" = "engineering", "Owner" = "platform-team" }
}

provider "aws" {
  region = var.aws_region           # => Region from shared variable set
  # => All workspaces with this variable set deploy to the same region
}

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
  tags       = merge(var.common_tags, {
    Name = "main-vpc"               # => Workspace-specific tag added to common tags
    # => merge() combines two maps; workspace-specific tags override shared ones
  })
  # => Result: { "CostCenter"="engineering", "Owner"="platform-team", "Name"="main-vpc" }
}

# policies/require-tags.sentinel
# => Sentinel policy enforcing mandatory resource tags
# => Sentinel uses its own policy language (similar to Python)

import "tfplan/v2" as tfplan
# => tfplan module provides access to the Terraform plan data
# => v2 is the second generation of the Sentinel Terraform integration

# Define required tags all resources must have
required_tags = ["Environment", "Owner", "CostCenter"]
# => All three tags required on every resource that supports tags

# Get all resources from the plan
all_resources = filter tfplan.resource_changes as _, rc {
  # => filter iterates all resource changes in the plan
  rc.mode is "managed" and   # => Exclude data sources (mode = "data")
  rc.change.actions contains "create" or
  rc.change.actions contains "update"
  # => Check only resources being created or updated
}

# Check each resource for required tags
violations = filter all_resources as address, rc {
  # => Build list of resources missing required tags
  tags = rc.change.after.tags else {}
  # => Read tags from the planned resource state
  # => "else {}" handles resources with no tags attribute (returns empty map)

  any required_tags as tag {
    # => Check if ANY required tag is missing
    not tags[tag] is defined or tags[tag] is ""
    # => Tag missing OR tag present but empty string
  }
}

# Policy result
main = rule {
  length(violations) is 0           # => Pass if no violations found
  # => length(violations) > 0 means at least one resource lacks required tags
}

# opa-policies/deny-public-s3.rego
# => OPA Rego policy preventing public S3 buckets
# => Rego is OPA's query language for policy decisions

package terraform.aws.s3
# => Package declaration namespaces this policy
# => Convention: terraform.<provider>.<service>

import rego.v1
# => Import Rego v1 syntax (recommended for new policies)

# Deny rule: triggers if any S3 bucket ACL is public
deny contains msg if {
  # => deny is a set; each element is an error message
  # => This rule fires once per matching bucket

  resource := input.resource_changes[_]
  # => input.resource_changes is array of all planned changes
  # => [_] iterates over all elements (anonymous variable)

  resource.type == "aws_s3_bucket_acl"
  # => Only check aws_s3_bucket_acl resource type

  resource.change.actions[_] in {"create", "update"}
  # => Only check resources being created or updated

  acl := resource.change.after.acl
  # => Read the planned ACL value

  acl in {"public-read", "public-read-write", "authenticated-read"}
  # => These ACL values expose bucket contents publicly
  # => "private" and "bucket-owner-full-control" are safe

  msg := sprintf(
    "S3 bucket ACL '%s' on resource '%s' makes bucket public. Use 'private' ACL.",
    [acl, resource.address]
  )
  # => Build descriptive error message including resource address
  # => resource.address example: "aws_s3_bucket_acl.app_bucket"
}

# Install conftest and run policy check against Terraform plan
terraform show -json tfplan.binary > tfplan.json
# => Convert binary plan to JSON for OPA consumption
# => tfplan.binary created by: terraform plan -out=tfplan.binary

conftest test tfplan.json --policy policies/
# => conftest tests the plan JSON against all .rego files in policies/
# => Exit code 1 if any deny rules fire, exit code 0 if all pass
# => Output: PASS or FAIL with denial messages

# Example output on failure:
# FAIL - tfplan.json - terraform.aws.s3 - S3 bucket ACL 'public-read' on
#        resource 'aws_s3_bucket_acl.app_bucket' makes bucket public. Use 'private' ACL.

# drift-detection/main.tf
# => Infrastructure configuration with drift detection workflow

resource "aws_security_group" "app" {
  name        = "app-security-group"
  description = "Security group for application tier"
  vpc_id      = var.vpc_id

  ingress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]    # => Allow HTTPS from anywhere
  }

  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]    # => Allow HTTP from anywhere (redirect to HTTPS)
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"              # => -1 means all protocols
    cidr_blocks = ["0.0.0.0/0"]    # => Allow all outbound traffic
  }

  lifecycle {
    ignore_changes = [description]  # => Ignore description drift
    # => Use ignore_changes when certain attributes are managed outside Terraform
    # => Example: Some tools append metadata to descriptions automatically
  }
}

#!/bin/bash
# => Drift detection script for scheduled CI execution

set -euo pipefail
# => -e: exit on error, -u: treat unset vars as error, -o pipefail: pipe failures propagate

terraform refresh
# => Sync state file with actual cloud state (reads current resource attributes)
# => Updates local state without changing infrastructure
# => Deprecated in favor of terraform apply -refresh-only

terraform plan -refresh-only -detailed-exitcode
# => -refresh-only: only refresh state, no config changes
# => -detailed-exitcode: exit 0=no changes, 1=error, 2=changes detected
EXIT_CODE=$?
# => Capture exit code before it's overwritten

if [ $EXIT_CODE -eq 2 ]; then
  echo "DRIFT DETECTED: Infrastructure differs from Terraform state"
  # => Exit code 2 means plan found differences (drift)
  echo "Review the plan above and decide: apply to remediate or import manual changes"
  exit 1                            # => Fail CI job to alert team
  # => Team must decide: override drift (terraform apply) or accept drift (terraform import)
elif [ $EXIT_CODE -eq 0 ]; then
  echo "No drift detected: Infrastructure matches Terraform state"
  # => Exit code 0 means no differences found
  exit 0                            # => Pass CI job
fi

# import/main.tf
# => Configuration matching existing infrastructure to be imported

resource "aws_instance" "legacy_app" {
  ami           = "ami-0abcdef1234567890"   # => Must match existing instance
  instance_type = "t3.large"               # => Must match existing instance type
  # => All attributes must match actual resource to avoid plan showing changes

  tags = {
    Name        = "legacy-app-server"      # => Tag on existing instance
    Environment = "production"             # => Existing tag
  }

  # Lifecycle block prevents accidental destruction during import
  lifecycle {
    prevent_destroy = true                 # => Block terraform destroy for this resource
    # => Safety net: prevents import followed by accidental destroy
  }
}

# import/imports.tf
# => Terraform 1.5+ declarative import blocks (replaces CLI import command)

import {
  to = aws_instance.legacy_app              # => Target resource in configuration
  id = "i-0abc123def456789"                # => Cloud resource ID to import
  # => ID format varies by resource type:
  # => EC2 instance: i-xxxxx
  # => S3 bucket: bucket-name
  # => RDS instance: db-identifier
  # => Security group: sg-xxxxx
}

import {
  to = aws_s3_bucket.legacy_data
  id = "my-legacy-bucket-name"            # => S3 bucket name is the ID
}

# => After running terraform plan with import blocks:
# => Terraform generates resource configuration from actual state
# => terraform plan -generate-config-out=generated.tf
# => Review generated.tf, copy to main.tf, then run terraform apply

# blue-green/main.tf
# => Blue-green infrastructure using AWS Auto Scaling Groups

variable "active_color" {
  type        = string
  description = "Currently active environment: 'blue' or 'green'"
  default     = "blue"              # => Toggle between deployments by changing this
  # => Change to "green" to shift traffic to new environment
}

locals {
  colors = ["blue", "green"]        # => Both environments always exist
  # => Inactive environment receives zero traffic but stays provisioned
}

# Launch templates for both environments
resource "aws_launch_template" "app" {
  for_each      = toset(local.colors)   # => Creates one launch template per color
  name          = "app-${each.key}"     # => app-blue, app-green
  image_id      = var.ami_ids[each.key] # => Different AMI per environment
  # => ami_ids map: { blue = "ami-111", green = "ami-222" }
  instance_type = "t3.medium"

  user_data = base64encode(templatefile("userdata.sh.tpl", {
    color = each.key                # => Pass color to startup script
    # => Startup script configures environment-specific settings
  }))
}

# Auto Scaling Groups for both environments
resource "aws_autoscaling_group" "app" {
  for_each = toset(local.colors)

  name                = "app-asg-${each.key}"
  min_size            = each.key == var.active_color ? 2 : 0
  # => Active environment: minimum 2 instances for high availability
  # => Inactive environment: scaled to 0 (no cost while idle)
  max_size            = 10
  desired_capacity    = each.key == var.active_color ? 3 : 0
  # => Active environment runs at desired capacity
  # => Inactive environment: 0 instances (can be pre-warmed before cutover)

  target_group_arns = each.key == var.active_color ? [aws_lb_target_group.active.arn] : []
  # => Only active environment attached to load balancer target group
  # => Empty list for inactive: instances exist but receive no traffic

  launch_template {
    id      = aws_launch_template.app[each.key].id
    version = "$Latest"             # => Always use latest launch template version
  }
}

# Load balancer target group (points to active environment)
resource "aws_lb_target_group" "active" {
  name     = "app-active-tg"
  port     = 8080
  protocol = "HTTP"
  vpc_id   = var.vpc_id
  # => Target group always represents the "active" environment
  # => Switching active_color variable and re-applying moves traffic
}

# immutable/packer-build.pkr.hcl
# => Packer configuration for baking application into AMI

packer {
  required_plugins {
    amazon = {
      source  = "github.com/hashicorp/amazon"
      version = "~> 1"               # => AWS Packer plugin
    }
  }
}

source "amazon-ebs" "app_image" {
  ami_name      = "my-app-${formatdate("YYYY-MM-DD-hhmm", timestamp())}"
  # => Timestamp in name ensures unique AMI per build
  # => Example: my-app-2026-03-20-1430
  instance_type = "t3.small"         # => Builder instance (terminated after AMI creation)
  region        = "us-east-1"
  source_ami_filter {
    filters = {
      name                = "amzn2-ami-hvm-*-x86_64-gp2"
      virtualization-type = "hvm"    # => Hardware virtualization
    }
    owners      = ["amazon"]         # => Trust only Amazon-published base AMIs
    most_recent = true               # => Use latest matching base AMI
  }
  ssh_username = "ec2-user"          # => Default username for Amazon Linux 2
}

build {
  sources = ["source.amazon-ebs.app_image"]

  provisioner "shell" {
    inline = [
      "sudo yum update -y",          # => Apply all OS security patches
      "sudo yum install -y java-17",  # => Install Java runtime
      "sudo useradd --system app",    # => Create system user (no login shell)
    ]
    # => All provisioning happens at AMI build time, not boot time
    # => Result: instances start in seconds (no boot-time provisioning)
  }

  provisioner "file" {
    source      = "target/app.jar"   # => Application JAR from build pipeline
    destination = "/opt/app/app.jar" # => Destination in AMI
    # => Application binary baked into AMI, not downloaded at boot
  }

  post-processor "manifest" {
    output = "packer-manifest.json"  # => Writes AMI ID to file for Terraform
    # => Terraform reads this file to know which AMI to deploy
  }
}

# Read AMI ID from Packer manifest
locals {
  packer_manifest = jsondecode(file("packer-manifest.json"))
  # => jsondecode converts JSON string to Terraform object
  app_ami_id      = local.packer_manifest.builds[0].artifact_id
  # => artifact_id format: "us-east-1:ami-0abc123"
  # => Split to extract just the AMI ID
  ami_id = split(":", local.app_ami_id)[1]
  # => Result: "ami-0abc123"
}

resource "aws_launch_template" "app" {
  name_prefix   = "app-immutable-"
  image_id      = local.ami_id      # => AMI baked by Packer
  instance_type = "t3.medium"

  lifecycle {
    create_before_destroy = true    # => New launch template before old one destroyed
    # => Prevents downtime: new ASG instances launch before old instances terminate
  }
}

# atlantis.yaml
# => Atlantis project configuration (in repository root)
version: 3 # => Atlantis config version

projects:
  - name: networking # => Project display name
    dir: infrastructure/networking # => Directory containing Terraform code
    workspace: production # => Terraform workspace (maps to Terraform Cloud workspace)
    autoplan:
      enabled: true # => Auto-run plan on PR changes
      when_modified:
        - "**/*.tf" # => Glob: any .tf file in the directory
        - "**/*.tfvars" # => Include variable files
        - "../modules/**/*.tf" # => Replan if shared modules change
    apply_requirements:
      - approved # => Require PR approval before apply
      - mergeable # => Require passing CI checks
    # => apply_requirements prevents rogue applies without code review

  - name: compute
    dir: infrastructure/compute
    workspace: production
    depends_on:
      - networking # => Apply compute only after networking succeeds
      # => Atlantis enforces apply ordering based on depends_on
    autoplan:
      enabled: true
      when_modified:
        - "**/*.tf"
    apply_requirements:
      - approved
      - mergeable

# .github/workflows/terraform.yml
# => GitHub Actions workflow for Terraform CI/CD

name: Terraform CI/CD

on:
  pull_request:
    paths:
      - "infrastructure/**" # => Only trigger on infra changes
      - ".github/workflows/terraform.yml"
  push:
    branches:
      - main # => Trigger apply only on main branch merge

env:
  TF_VERSION: "1.7.0" # => Pin Terraform version for reproducibility
  WORKING_DIR: "./infrastructure" # => Root Terraform directory

jobs:
  terraform-check:
    name: Format and Validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # => Checkout repository code

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
          # => Installs exact Terraform version from env var
          cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}
          # => Token for Terraform Cloud (stored as GitHub secret)

      - name: Terraform Format Check
        working-directory: ${{ env.WORKING_DIR }}
        run: terraform fmt -check -recursive
        # => -check: exit 1 if files need formatting (don't modify files)
        # => -recursive: check all subdirectories
        # => Enforces consistent HCL formatting across team

      - name: Terraform Init
        working-directory: ${{ env.WORKING_DIR }}
        run: terraform init -backend=false
        # => -backend=false: initialize without connecting to remote state
        # => Validates provider requirements without needing credentials

      - name: Terraform Validate
        working-directory: ${{ env.WORKING_DIR }}
        run: terraform validate
        # => Validates HCL syntax and internal consistency
        # => Catches type errors, missing required arguments, invalid references
        # => Does NOT check against cloud (uses -backend=false from init)

  security-scan:
    name: Security Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Checkov
        uses: bridgecrewio/checkov-action@v12
        with:
          directory: infrastructure/
          framework: terraform # => Scan Terraform files specifically
          output_format: sarif # => GitHub-compatible security findings format
          soft_fail: true # => Don't fail pipeline, report as warnings
          # => Checkov checks: public S3 buckets, unencrypted storage, open security groups

  terraform-plan:
    name: Plan
    runs-on: ubuntu-latest
    needs: [terraform-check] # => Only plan if checks pass
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
          cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}

      - name: Terraform Plan
        working-directory: ${{ env.WORKING_DIR }}
        run: terraform plan -no-color -out=tfplan
        # => -no-color: clean output for PR comments (no ANSI escape codes)
        # => -out=tfplan: save plan for apply step (prevents plan/apply mismatch)
        id: plan

      - name: Post Plan to PR
        uses: actions/github-script@v7
        with:
          script: |
            const output = `#### Terraform Plan\n\`\`\`\n${{ steps.plan.outputs.stdout }}\n\`\`\``;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            });
          # => Posts plan output as PR comment for reviewer visibility

// test/vpc_test.go
// => Terratest integration test for VPC module

package test

import (
 "testing"

 "github.com/gruntwork-io/terratest/modules/aws"
 "github.com/gruntwork-io/terratest/modules/terraform"
 "github.com/stretchr/testify/assert"
)

func TestVPCModule(t *testing.T) {
 t.Parallel() // => Run tests concurrently to reduce total test time

 terraformOptions := &terraform.Options{
  TerraformDir: "../modules/vpc", // => Path to Terraform module under test
  Vars: map[string]interface{}{
   "vpc_cidr":    "10.99.0.0/16", // => Non-overlapping CIDR for test isolation
   "environment": "test",          // => Tag resources as test for cleanup
   "region":      "us-east-1",
  },
  NoColor: true, // => Clean output in CI logs
 }

 // Ensure resources are destroyed after test (even on failure)
 defer terraform.Destroy(t, terraformOptions)
 // => defer runs Destroy even if test panics
 // => Critical: prevents orphaned cloud resources from accumulating cost

 // Deploy infrastructure
 terraform.InitAndApply(t, terraformOptions)
 // => Runs terraform init and terraform apply
 // => Blocks until apply completes (real cloud resources created)

 // Read output values from Terraform
 vpcID := terraform.Output(t, terraformOptions, "vpc_id")
 // => Reads "vpc_id" output from Terraform state
 subnetIDs := terraform.OutputList(t, terraformOptions, "private_subnet_ids")
 // => Reads list output as Go string slice

 // Assert VPC was created
 assert.NotEmpty(t, vpcID, "VPC ID should not be empty")
 // => VPC ID format: vpc-0abc123def456789

 // Assert subnets exist using AWS SDK
 vpc := aws.GetVpcById(t, vpcID, "us-east-1")
 // => aws.GetVpcById queries AWS API directly (not Terraform state)
 // => Validates infrastructure exists in cloud, not just in state file

 assert.Equal(t, "10.99.0.0/16", vpc.CidrBlock,
  "VPC CIDR should match input variable")
 // => Verifies Terraform created VPC with correct CIDR

 assert.Len(t, subnetIDs, 3,
  "Should create 3 private subnets (one per AZ)")
 // => Module should distribute subnets across availability zones

 // Validate subnet CIDRs are within VPC CIDR
 for _, subnetID := range subnetIDs {
  subnet := aws.GetSubnetById(t, subnetID, "us-east-1")
  assert.Contains(t, subnet.CidrBlock, "10.99.",
   "Subnet CIDR should be within VPC CIDR")
  // => Each subnet should be a slice of the VPC CIDR range
 }
}

# modules/compute/main.tf
# => Compute module under test

variable "instance_count" {
  type        = number
  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 20
    error_message = "Instance count must be between 1 and 20."
    # => Validation runs during plan, before any resources created
  }
}

variable "environment" {
  type = string
  validation {
    condition     = contains(["dev", "staging", "production"], var.environment)
    error_message = "Environment must be dev, staging, or production."
    # => Restrict to known environments to prevent typos
  }
}

output "instance_tags" {
  value = {
    Environment = var.environment
    Count       = tostring(var.instance_count)
    ManagedBy   = "terraform"
  }
  # => Output used by test assertions
}

# modules/compute/compute_test.tftest.hcl
# => Terraform native test file (*.tftest.hcl extension)
# => Run with: terraform test

run "valid_production_config" {
  # => Test case name (describes the scenario being tested)

  variables {
    instance_count = 3              # => Valid: within 1-20 range
    environment    = "production"   # => Valid: in allowed list
  }

  # => command defaults to "plan" (doesn't create real resources)
  # => Use command = "apply" for integration tests that create resources

  assert {
    condition     = output.instance_tags.Environment == "production"
    error_message = "Environment tag should be 'production'"
    # => Validate output values without creating infrastructure
  }

  assert {
    condition     = output.instance_tags.ManagedBy == "terraform"
    error_message = "ManagedBy tag should be 'terraform'"
    # => Multiple assert blocks in one run block all evaluated
  }
}

run "invalid_instance_count_rejected" {
  variables {
    instance_count = 25             # => Invalid: exceeds maximum of 20
    environment    = "production"
  }

  expect_failures = [
    var.instance_count,             # => Expect this variable's validation to fail
    # => Test passes only if this validation error IS raised
    # => Validates negative cases: bad input produces expected errors
  ]
}

run "invalid_environment_rejected" {
  variables {
    instance_count = 1
    environment    = "staging-v2"   # => Invalid: not in allowed list
  }

  expect_failures = [var.environment]
  # => Test passes only if environment validation rejects "staging-v2"
}

# vault-integration/main.tf
# => Terraform + Vault integration for secrets management

terraform {
  required_providers {
    vault = {
      source  = "hashicorp/vault"
      version = "~> 3.0"           # => Vault provider for secret retrieval
    }
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "vault" {
  address = "https://vault.internal.example.com"
  # => Vault server URL
  # => Authentication via VAULT_TOKEN env var or AppRole
  # => Never hardcode Vault tokens in configuration
}

# Retrieve dynamic AWS credentials from Vault
data "vault_aws_access_credentials" "deploy" {
  backend = "aws"                  # => Vault AWS secrets engine mount path
  role    = "terraform-deployer"   # => Vault role with specific AWS permissions
  # => Vault generates short-lived AWS credentials (TTL: 15 minutes)
  # => Each terraform apply gets unique credentials, not shared long-lived keys
  # => Credentials automatically revoked after TTL expires
}

provider "aws" {
  access_key = data.vault_aws_access_credentials.deploy.access_key
  # => Dynamic access key from Vault (not from ~/.aws/credentials)
  secret_key = data.vault_aws_access_credentials.deploy.secret_key
  # => Dynamic secret key from Vault
  region     = "us-east-1"
  # => Credentials valid only for terraform-deployer role permissions
}

# Read static secret from Vault KV store
data "vault_kv_secret_v2" "db_credentials" {
  mount = "secret"                 # => KV secrets engine mount path
  name  = "production/database"    # => Secret path within the mount
  # => Returns map of key-value pairs stored at this path
}

resource "aws_db_instance" "app" {
  identifier        = "app-db"
  engine            = "postgres"
  engine_version    = "15.4"
  instance_class    = "db.t3.medium"
  allocated_storage = 20

  username = data.vault_kv_secret_v2.db_credentials.data["username"]
  # => Read username from Vault KV secret
  # => .data["username"] accesses the "username" key in the secret map
  password = data.vault_kv_secret_v2.db_credentials.data["password"]
  # => Password from Vault, never appears in .tf files or git history
  # => Note: password still appears in Terraform state (see lifecycle below)

  lifecycle {
    ignore_changes = [password]    # => Don't detect drift on password
    # => Vault might rotate the password; ignore_changes prevents re-applying
  }
}

# group_vars/production/vault.yml
# => Ansible Vault encrypted file (encrypted by ansible-vault encrypt)
# => Actual file content: $ANSIBLE_VAULT;1.1;AES256 followed by encrypted bytes
# => Decrypted content shown below for documentation

# ansible-vault decrypt group_vars/production/vault.yml
# => Decrypted view (never stored in plaintext):
vault_db_password: "super-secret-db-password-here"
vault_api_key: "production-api-key-12345"
vault_ssl_private_key: |
  -----BEGIN RSA PRIVATE KEY-----
  (key content)
  -----END RSA PRIVATE KEY-----

# group_vars/production/vars.yml
# => Non-sensitive variables reference vault variables
# => This file is NOT encrypted (safe to commit as-is)

db_password: "{{ vault_db_password }}"
# => Reference vault variable via Jinja2 template
# => Ansible merges vault and regular vars at runtime
# => Vault vars prefixed with "vault_" by convention

api_key: "{{ vault_api_key }}"
# => Pattern: vault_<name> in encrypted file, <name> in regular vars
# => Playbooks reference api_key (not vault_api_key directly)

# playbooks/configure-app.yml
# => Playbook using vault-encrypted variables

- name: Configure application server
  hosts: production_app
  become: true # => Run as root (sudo)
  vars_files:
    - "../group_vars/production/vars.yml"
    # => Includes both regular vars and vault references

  tasks:
    - name: Write application configuration
      template:
        src: app-config.j2 # => Jinja2 template file
        dest: /etc/app/config.yaml # => Destination on remote host
        owner: app # => File owner
        mode: "0600" # => Read-only for owner (secrets file)
        # => mode: "0600" prevents other users from reading the config
      vars:
        database_password: "{{ db_password }}"
        # => db_password references vault_db_password via group_vars chain

    - name: Configure SSL certificate
      copy:
        content: "{{ vault_ssl_private_key }}"
        dest: /etc/ssl/private/app.key
        owner: root
        group: ssl-cert
        mode: "0640" # => Owner read-write, group read

# Running playbooks with Vault
ansible-playbook playbooks/configure-app.yml --ask-vault-pass
# => Prompts for vault password interactively (development use)

ansible-playbook playbooks/configure-app.yml --vault-password-file ~/.vault_pass
# => Reads vault password from file (CI/CD use)
# => ~/.vault_pass should be mode 600, stored in secrets manager

ansible-vault edit group_vars/production/vault.yml
# => Opens encrypted file in $EDITOR for safe editing
# => Decrypts in memory, saves re-encrypted to disk

# terraform-approach/main.tf
# => Terraform HCL: limited programming constructs

variable "environments" {
  type    = list(string)
  default = ["dev", "staging", "production"]
  # => Create VPC for each environment
}

resource "aws_vpc" "env" {
  for_each   = toset(var.environments) # => Convert list to set for for_each
  cidr_block = "10.${index(var.environments, each.key)}.0.0/16"
  # => Workaround: index() to get position, build CIDR via interpolation
  # => Limitation: index() requires knowing list contents at plan time
  # => Cannot use complex logic (conditionals on computed values) in for_each

  tags = { Name = "${each.key}-vpc" }
}

// pulumi-approach/index.ts
// => Pulumi TypeScript: full programming language capabilities

import * as aws from "@pulumi/aws";
// => Import Pulumi AWS SDK (installed via npm)

const environments = ["dev", "staging", "production"];
// => TypeScript array: familiar data structure

// TypeScript function for CIDR calculation
function getVpcCidr(index: number): string {
  return `10.${index}.0.0/16`;
  // => Real function definition (impossible in HCL)
  // => Can contain arbitrary logic: lookups, calculations, API calls
}

// TypeScript map with type safety
const vpcs = Object.fromEntries(
  environments.map((env, index) => {
    // => .map() with index: native TypeScript array method
    const vpc = new aws.ec2.Vpc(`${env}-vpc`, {
      cidrBlock: getVpcCidr(index), // => Call TypeScript function
      tags: { Name: `${env}-vpc`, Environment: env },
    });
    return [env, vpc]; // => Build map entry
  }),
);
// => vpcs is { dev: VpcResource, staging: VpcResource, production: VpcResource }

// Export VPC IDs (TypeScript type: Record<string, pulumi.Output<string>>)
export const vpcIds = Object.fromEntries(
  Object.entries(vpcs).map(([env, vpc]) => [env, vpc.id]),
  // => vpc.id is a Pulumi Output<string> (resolved after deployment)
);

// cdktf/main.ts
// => CDKTF generates Terraform HCL JSON from TypeScript

import { App, TerraformStack, TerraformOutput } from "cdktf";
// => App: root construct, TerraformStack: maps to Terraform root module

import { AwsProvider, ec2 } from "@cdktf/provider-aws";
// => Type-safe AWS provider bindings generated from Terraform provider schema

import { Construct } from "constructs";
// => Construct: base class for all CDKTF components (like CDK for AWS)

class InfrastructureStack extends TerraformStack {
  // => TerraformStack generates a single Terraform root module
  // => Extending TerraformStack creates a deployable unit

  constructor(scope: Construct, name: string) {
    super(scope, name);

    new AwsProvider(this, "aws", {
      region: "us-east-1",
      // => AwsProvider generates: provider "aws" { region = "us-east-1" }
    });

    // TypeScript array of subnet configs
    const subnetConfigs = [
      { cidr: "10.0.1.0/24", az: "us-east-1a" },
      { cidr: "10.0.2.0/24", az: "us-east-1b" },
      { cidr: "10.0.3.0/24", az: "us-east-1c" },
    ];
    // => Using real TypeScript array (no HCL for_each limitations)

    const vpc = new ec2.Vpc(this, "main-vpc", {
      cidrBlock: "10.0.0.0/16", // => Generates: resource "aws_vpc" "main-vpc" { ... }
    });

    // Create subnets using TypeScript .map()
    const subnets = subnetConfigs.map(
      (config, index) =>
        new ec2.Subnet(this, `subnet-${index}`, {
          vpcId: vpc.id, // => vpc.id references the VPC resource (generates interpolation)
          cidrBlock: config.cidr,
          availabilityZone: config.az,
        }),
      // => Generates: resource "aws_subnet" "subnet-0", "subnet-1", "subnet-2"
    );

    new TerraformOutput(this, "subnet-ids", {
      value: subnets.map((s) => s.id),
      // => Generates: output "subnet-ids" { value = [...] }
      // => TypeScript map() generates Terraform list output
    });
  }
}

const app = new App(); // => Create CDKTF app (root of construct tree)
new InfrastructureStack(app, "my-infra");
// => Register stack with app

app.synth();
// => Synthesize TypeScript code into cdktf.out/ directory containing Terraform JSON
// => Run: cdktf deploy (deploys synthesized Terraform JSON)
// => Run: cdktf diff (equivalent to terraform plan)

# .github/workflows/infracost.yml
# => GitHub Actions workflow for cost estimation

name: Infracost Cost Estimation

on:
  pull_request:
    paths:
      - "infrastructure/**"

jobs:
  infracost:
    name: Estimate Cost
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write # => Required to post PR comment

    steps:
      - uses: actions/checkout@v4

      - name: Setup Infracost
        uses: infracost/actions/setup@v3
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}
          # => API key from infracost.io (free tier available)

      - name: Generate Infracost diff
        run: |
          # Generate cost estimate for PR branch
          infracost breakdown --path infrastructure/ \
            --format json \
            --out-file infracost-base.json
          # => breakdown: estimate costs for all resources in the plan
          # => --format json: machine-readable output for comparison

          # Compare to baseline (main branch)
          infracost diff \
            --path infrastructure/ \
            --compare-to infracost-base.json \
            --format json \
            --out-file infracost-diff.json
          # => diff: shows cost change between branches
          # => Output includes: monthly cost delta, resource-by-resource breakdown
        env:
          INFRACOST_TERRAFORM_CLOUD_TOKEN: ${{ secrets.TF_API_TOKEN }}
          # => Required if using Terraform Cloud for remote state

      - name: Post Infracost comment
        uses: infracost/actions/comment@v3
        with:
          path: infracost-diff.json
          behavior: update # => Update existing comment on re-runs
          # => Posts table like:
          # =>   Resource            Monthly Cost    Change
          # =>   aws_instance.app    $73.00          +$36.50 (+100%)
          # =>   aws_db_instance.db  $52.00          No change
          # =>   Total               $125.00         +$36.50

# infrastructure/main.tf
# => Annotated for cost awareness

resource "aws_instance" "app" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = "t3.large"        # => ~$60/month in us-east-1 (on-demand)
  # => COST IMPACT: instance_type is the primary cost driver
  # => t3.large: 2 vCPU, 8GB RAM
  # => Consider: t3.medium ($30/month) for non-prod, reserved instances for 40% discount

  ebs_optimized = true              # => ~$0/month for t3 (included)
  # => Adds dedicated EBS bandwidth channel

  root_block_device {
    volume_size = 100               # => 100 GB gp3: ~$8/month
    volume_type = "gp3"             # => gp3 cheaper than gp2 for same IOPS
    # => COST IMPACT: over-provisioning storage is common waste
    # => Infracost will show this as separate line item
  }
}

resource "aws_nat_gateway" "main" {
  allocation_id = aws_eip.nat.id
  subnet_id     = aws_subnet.public.id
  # => COST IMPACT: NAT Gateway costs ~$32/month base + $0.045/GB data
  # => Often the hidden cost surprise in VPC architectures
  # => Alternative: NAT instance (EC2) is cheaper but less reliable
}

# .sops.yaml
# => SOPS configuration file (in repository root)

creation_rules:
  - path_regex: environments/production/.*\.yaml$
    # => Match: any .yaml file under environments/production/
    kms: arn:aws:kms:us-east-1:123456789:key/my-kms-key-id
    # => AWS KMS key to encrypt/decrypt production secrets
    # => KMS key policy controls who can encrypt/decrypt (IAM-based)
    # => Audit trail: KMS CloudTrail logs every decrypt operation

  - path_regex: environments/staging/.*\.yaml$
    kms: arn:aws:kms:us-east-1:123456789:key/staging-kms-key-id
    # => Separate KMS key for staging (different IAM access)
    # => Production engineers cannot decrypt staging secrets
    # => (and vice versa, enforcing least privilege)

  - path_regex: .*\.yaml$
    pgp: "FINGERPRINT1,FINGERPRINT2"
    # => Fallback: PGP encryption for non-environment files
    # => Encrypted for multiple recipients (each can decrypt)

# environments/production/secrets.enc.yaml
# => SOPS-encrypted file (stored in git in this encrypted form)
# => After: sops --encrypt environments/production/secrets.enc.yaml

# Encrypted file format (actual git content):
# db_password: ENC[AES256_GCM,data:xyz123...,tag:abc456,type:str]
# api_key: ENC[AES256_GCM,data:def789...,tag:ghi012,type:str]
# sops:
#   kms: [{ arn: "arn:aws:kms:...", enc: "AQICAHi...", created_at: "..." }]
#   version: "3.7.3"

# After: sops --decrypt environments/production/secrets.enc.yaml
# (Decrypted view - never stored in plaintext):
db_password: "production-db-password-here"
api_key: "production-api-key-here"

# sops-terraform/main.tf
# => Terraform reading SOPS-encrypted values

data "sops_file" "prod_secrets" {
  source_file = "${path.module}/environments/production/secrets.enc.yaml"
  # => sops provider decrypts file using KMS at plan/apply time
  # => Requires AWS credentials with kms:Decrypt permission
  # => Decrypted values available as data.sops_file.prod_secrets.data["key"]
}

resource "aws_db_instance" "prod" {
  identifier = "prod-database"
  engine     = "postgres"

  username = "app_user"
  password = data.sops_file.prod_secrets.data["db_password"]
  # => Password decrypted from SOPS-encrypted file at apply time
  # => Never appears in .tf files or environment variables
  # => Decrypt audit trail logged in AWS CloudTrail (KMS usage)
}

# disaster-recovery/main.tf
# => Disaster recovery infrastructure (deployed to secondary region)

variable "dr_mode" {
  type        = bool
  description = "Set to true to activate full DR environment"
  default     = false               # => Normally false (pilot light mode)
  # => pilot light: minimal DR infrastructure, scaled up on activation
}

provider "aws" {
  alias  = "primary"
  region = "us-east-1"             # => Primary region provider
}

provider "aws" {
  alias  = "dr"
  region = "us-west-2"             # => DR region provider
}

# RDS read replica in DR region
resource "aws_db_instance" "dr_replica" {
  provider             = aws.dr    # => Deploy to DR region
  identifier           = "app-db-dr-replica"
  replicate_source_db  = aws_db_instance.primary.arn
  # => Cross-region read replica: data continuously synced from primary
  # => Lag typically < 1 second (near-synchronous replication)
  # => On activation: promote replica to standalone (terraform apply -var dr_mode=true)

  instance_class    = var.dr_mode ? "db.t3.large" : "db.t3.micro"
  # => Normal: tiny instance (pilot light, minimal cost)
  # => DR activated: scale to production size
  multi_az          = var.dr_mode  # => Multi-AZ only when activated
  # => Single AZ for standby, Multi-AZ when serving production traffic
}

# DNS failover
resource "aws_route53_record" "app" {
  zone_id = var.hosted_zone_id
  name    = "app.example.com"
  type    = "A"

  failover_routing_policy {
    type = var.dr_mode ? "SECONDARY" : "PRIMARY"
    # => Normal: Route53 routes to primary region
    # => DR activated: this record becomes the secondary (target)
  }

  health_check_id = aws_route53_health_check.primary.id
  # => Route53 monitors primary endpoint health
  # => Automatic failover if health check fails
  set_identifier = "primary-or-dr"
  alias {
    name                   = var.dr_mode ? aws_lb.dr.dns_name : aws_lb.primary.dns_name
    zone_id                = var.dr_mode ? aws_lb.dr.zone_id : aws_lb.primary.zone_id
    evaluate_target_health = true
  }
}

# auto-scaling/main.tf
# => Advanced auto-scaling configuration

resource "aws_autoscaling_group" "app" {
  name                      = "app-asg"
  min_size                  = 2              # => Never scale below 2 (HA minimum)
  max_size                  = 50             # => Cap at 50 to control costs
  desired_capacity          = 3             # => Starting point
  health_check_type         = "ELB"         # => Use load balancer health checks
  health_check_grace_period = 300           # => 5 minutes for instance warm-up
  # => Grace period prevents terminating instances that are still starting

  vpc_zone_identifier = var.private_subnet_ids
  # => Deploy across multiple AZs for fault tolerance

  launch_template {
    id      = aws_launch_template.app.id
    version = "$Latest"
  }

  instance_refresh {
    strategy = "Rolling"            # => Replace instances one at a time
    preferences {
      min_healthy_percentage = 90   # => Keep 90% healthy during refresh
      # => 10 instances: replaces at most 1 at a time (10% of 10 = 1)
      instance_warmup = 300         # => Wait 5 min before refreshing next
    }
    # => instance_refresh triggers rolling replacement when launch template changes
    # => terraform apply with new launch template automatically refreshes ASG
  }

  tag {
    key                 = "Name"
    value               = "app-instance"
    propagate_at_launch = true      # => Apply tag to every instance launched
  }
}

# Target tracking scaling - CPU
resource "aws_autoscaling_policy" "cpu_scale_out" {
  name                   = "cpu-target-tracking"
  autoscaling_group_name = aws_autoscaling_group.app.name
  policy_type            = "TargetTrackingScaling"
  # => TargetTracking: Auto Scaling adjusts to maintain target metric

  target_tracking_configuration {
    predefined_metric_specification {
      predefined_metric_type = "ASGAverageCPUUtilization"
      # => Pre-built metric: average CPU across all instances in ASG
    }
    target_value = 60.0             # => Target: 60% average CPU utilization
    # => Scale out (add instances) when avg CPU > 60%
    # => Scale in (remove instances) when avg CPU < 60%
    # => Auto Scaling calculates required instance count automatically
  }
}

# Step scaling based on SQS queue depth
resource "aws_autoscaling_policy" "queue_scale_out" {
  name                   = "queue-depth-scale-out"
  autoscaling_group_name = aws_autoscaling_group.app.name
  policy_type            = "StepScaling"
  # => StepScaling: add different numbers of instances based on metric severity

  step_adjustment {
    metric_interval_lower_bound = 0    # => Queue depth 100-500
    metric_interval_upper_bound = 400
    scaling_adjustment          = 2    # => Add 2 instances
  }

  step_adjustment {
    metric_interval_lower_bound = 400  # => Queue depth 500-1000
    metric_interval_upper_bound = 900
    scaling_adjustment          = 5    # => Add 5 instances (more aggressive)
  }

  step_adjustment {
    metric_interval_lower_bound = 900  # => Queue depth > 1000
    scaling_adjustment          = 10   # => Add 10 instances (emergency scale-out)
    # => No upper bound: handles any queue depth above threshold
  }
  adjustment_type = "ChangeInCapacity"  # => Relative adjustment (add/remove)
}

# dependency-graph/main.tf
# => Illustrating Terraform's dependency resolution

# Root resource: no dependencies
resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"       # => Created first (no dependencies)
  # => All other resources in this file depend on this VPC
}

# Depends on VPC (implicit via vpc_id reference)
resource "aws_subnet" "public" {
  vpc_id     = aws_vpc.main.id     # => implicit dependency: subnet waits for VPC
  cidr_block = "10.0.1.0/24"
  # => terraform graph shows edge: aws_subnet.public -> aws_vpc.main
}

resource "aws_subnet" "private" {
  vpc_id     = aws_vpc.main.id     # => Also depends on VPC
  cidr_block = "10.0.2.0/24"
  # => aws_subnet.public and aws_subnet.private are independent (parallel creation)
}

# Depends on VPC and subnet (implicit)
resource "aws_db_subnet_group" "main" {
  name       = "main"
  subnet_ids = [aws_subnet.private.id]
  # => Implicit dependency: waits for private subnet
}

# Explicit dependency using depends_on
resource "aws_db_instance" "app" {
  identifier     = "app-db"
  engine         = "postgres"
  instance_class = "db.t3.micro"
  db_subnet_group_name = aws_db_subnet_group.main.name
  # => Implicit dependency: waits for subnet group

  depends_on = [aws_vpc.main]      # => Explicit dependency (usually unnecessary)
  # => Use depends_on ONLY when dependency not captured by reference
  # => Example: IAM policy changes that affect resource behavior without reference
  # => Overuse of depends_on forces sequential apply instead of parallel
}

# Data source with explicit dependency
data "aws_subnets" "private" {
  filter {
    name   = "vpc-id"
    values = [aws_vpc.main.id]     # => Implicit: data source reads after VPC created
  }
  depends_on = [aws_subnet.private]  # => Wait for subnet creation
  # => Data source might be cached; depends_on forces re-read after subnet creation
}

terraform graph | dot -Tsvg > infrastructure-graph.svg
# => terraform graph outputs Graphviz DOT format
# => dot converts DOT to SVG image
# => Visualize entire dependency tree to identify bottlenecks and cycles

terraform graph -type=plan | dot -Tsvg > plan-graph.svg
# => -type=plan: show only resources affected by current plan
# => Useful for understanding what a specific change will affect