Infrastructure as Code Explained — Why, How, and Real-World IaC Patterns

# main.tf — Terraform declarative configuration for a basic web server on AWS
# Run: terraform init && terraform plan && terraform apply

# Tell Terraform which cloud provider to use and which region
provider "aws" {
  region = "us-east-1"
}

# Declare the desired state: an EC2 instance running Ubuntu
# Terraform will CREATE this if it doesn't exist, UPDATE it if the spec changed,
# and do NOTHING if it already matches — this is idempotency in action
resource "aws_instance" "web_server" {
  ami           = "ami-0c02fb55956c7d316"  # Ubuntu 22.04 LTS in us-east-1
  instance_type = "t3.micro"               # Free-tier eligible size

  # Tag the resource so humans can find it in the AWS console
  tags = {
    Name        = "theforge-web-server"
    Environment = "staging"
    ManagedBy   = "terraform"  # Critical: tells the team this isn't manually managed
  }
}

# Output block: print the public IP after apply so we know where to connect
output "web_server_public_ip" {
  description = "The public IP address of our web server"
  value       = aws_instance.web_server.public_ip
}

# .github/workflows/terraform-ci-cd.yml
# This pipeline runs Terraform plan on PRs and Terraform apply on merge to main.
# Prerequisites: Store AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as GitHub Secrets.

name: Terraform Infrastructure Pipeline

on:
  pull_request:
    branches: [main]        # Run plan on any PR targeting main
    paths: ['terraform/**'] # Only trigger when Terraform files actually changed
  push:
    branches: [main]        # Run apply when code lands on main
    paths: ['terraform/**']

env:
  TF_VERSION: '1.7.0'                     # Pin the version — never use 'latest' in CI
  TF_WORKING_DIR: './terraform'            # All .tf files live in this directory
  AWS_REGION: 'us-east-1'

jobs:
  terraform-plan:
    name: Plan Infrastructure Changes
    runs-on: ubuntu-latest
    # Only run the plan job on pull requests, not on direct pushes to main
    if: github.event_name == 'pull_request'

    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Configure AWS credentials from GitHub Secrets
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Install the pinned version of Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Terraform Init — download providers and configure backend
        working-directory: ${{ env.TF_WORKING_DIR }}
        run: terraform init -input=false
        # -input=false prevents the pipeline hanging waiting for keyboard input

      - name: Terraform Validate — catch syntax errors before planning
        working-directory: ${{ env.TF_WORKING_DIR }}
        run: terraform validate

      - name: Terraform Plan — calculate what will change
        working-directory: ${{ env.TF_WORKING_DIR }}
        id: tf_plan
        # -no-color prevents ANSI escape codes from cluttering the GitHub PR comment
        run: terraform plan -no-color -out=tfplan.binary

      - name: Post plan output as a PR comment so reviewers can see the diff
        uses: actions/github-script@v7
        with:
          script: |
            const planOutput = `${{ steps.tf_plan.outputs.stdout }}`;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '### Terraform Plan\n```\n' + planOutput + '\n```'
            })

  terraform-apply:
    name: Apply Infrastructure Changes
    runs-on: ubuntu-latest
    # Only run apply when a PR is merged to main — never on open PRs
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    environment: production   # Requires a GitHub environment approval gate if configured

    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Install Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Terraform Init
        working-directory: ${{ env.TF_WORKING_DIR }}
        run: terraform init -input=false

      - name: Terraform Apply — make the changes in the real cloud
        working-directory: ${{ env.TF_WORKING_DIR }}
        # -auto-approve skips the interactive yes/no prompt — safe here because
        # this only runs after a human approved and merged the PR
        run: terraform apply -input=false -auto-approve

# ─────────────────────────────────────────────
# FILE 1: backend.tf — remote state configuration
# This tells Terraform to store its state file in S3 instead of locally.
# DynamoDB provides a lock so two engineers can't apply simultaneously.
# ─────────────────────────────────────────────

terraform {
  required_version = ">= 1.7.0"  # Prevent older Terraform versions from running this config

  backend "s3" {
    bucket         = "theforge-terraform-state-prod"  # Must exist before you run terraform init
    key            = "services/web-app/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true  # Encrypt state at rest — critical because state contains secrets
    dynamodb_table = "theforge-terraform-locks"  # Table must have a partition key named 'LockID'
  }

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # ~> means 5.x but not 6.x — prevents breaking changes
    }
  }
}


# ─────────────────────────────────────────────
# FILE 2: modules/web_server/main.tf — a reusable module
# This module encapsulates all the resources needed for one web server.
# Call it multiple times with different variables for different services.
# ─────────────────────────────────────────────

variable "service_name" {
  description = "Name of the service this server runs, e.g. 'payments' or 'user-api'"
  type        = string
}

variable "environment" {
  description = "Deployment environment: dev, staging, or production"
  type        = string
  validation {
    # Terraform will refuse to apply if someone passes an unexpected value
    condition     = contains(["dev", "staging", "production"], var.environment)
    error_message = "Environment must be dev, staging, or production."
  }
}

variable "instance_type" {
  description = "EC2 instance size — use t3.micro for dev, t3.medium for production"
  type        = string
  default     = "t3.micro"
}

resource "aws_instance" "service_server" {
  ami           = "ami-0c02fb55956c7d316"
  instance_type = var.instance_type

  tags = {
    Name        = "${var.service_name}-${var.environment}"  # e.g. 'payments-production'
    Environment = var.environment
    Service     = var.service_name
    ManagedBy   = "terraform"
  }
}

output "server_id" {
  value = aws_instance.service_server.id
}


# ─────────────────────────────────────────────
# FILE 3: main.tf — calling the module twice for two different services
# This is the DRY pattern in action. Same infrastructure blueprint, different values.
# ─────────────────────────────────────────────

module "payments_server" {
  source        = "./modules/web_server"
  service_name  = "payments"
  environment   = "production"
  instance_type = "t3.medium"  # Payments needs more power than default
}

module "user_api_server" {
  source       = "./modules/web_server"
  service_name = "user-api"
  environment  = "production"
  # instance_type not specified — falls back to the default t3.micro
}