Terraform Basics Explained — State, Providers, and Real-World IaC Patterns

# main.tf — A minimal but complete AWS setup that demonstrates the core loop
# This creates a VPC and a single EC2 instance inside it.
# Run: terraform init -> terraform plan -> terraform apply

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Pin to major version to avoid surprise breaking changes
    }
  }
}

# The provider block tells Terraform WHERE to build — credentials come from
# environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) or an IAM role.
# Never hardcode credentials in .tf files — they'll end up in version control.
provider "aws" {
  region = var.aws_region
}

# Variables make this config reusable across environments.
# Actual values live in terraform.tfvars (git-ignored) or are passed via -var flags.
variable "aws_region" {
  type        = string
  description = "AWS region where all resources will be created"
  default     = "us-east-1"
}

variable "environment_name" {
  type        = string
  description = "Environment tag applied to every resource (e.g. staging, production)"
}

# The VPC is our private network — everything else lives inside it.
resource "aws_vpc" "primary_network" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_hostnames = true  # Needed so EC2 instances get resolvable DNS names

  tags = {
    Name        = "${var.environment_name}-vpc"
    Environment = var.environment_name
    ManagedBy   = "terraform"  # Tagging as Terraform-managed helps ops teams know NOT to edit manually
  }
}

# A public subnet within that VPC.
resource "aws_subnet" "public_web_subnet" {
  vpc_id                  = aws_vpc.primary_network.id  # Reference to the VPC above — Terraform builds the dependency graph from this
  cidr_block              = "10.0.1.0/24"
  availability_zone       = "${var.aws_region}a"
  map_public_ip_on_launch = true

  tags = {
    Name        = "${var.environment_name}-public-subnet"
    Environment = var.environment_name
  }
}

# Data source — reads EXISTING resources rather than creating new ones.
# Here we fetch the latest Amazon Linux 2023 AMI ID dynamically,
# so we're never hardcoding an AMI that gets deprecated.
data "aws_ami" "amazon_linux_2023" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["al2023-ami-*-x86_64"]  # Amazon Linux 2023 naming pattern
  }
}

# The EC2 instance. Notice it references both the subnet and the AMI data source.
resource "aws_instance" "web_server" {
  ami           = data.aws_ami.amazon_linux_2023.id  # Dynamic AMI from the data source above
  instance_type = "t3.micro"
  subnet_id     = aws_subnet.public_web_subnet.id

  tags = {
    Name        = "${var.environment_name}-web-server"
    Environment = var.environment_name
  }
}

# Outputs let you extract values after apply — useful for feeding into CI/CD pipelines
# or just confirming what was built.
output "web_server_public_ip" {
  description = "Public IP of the web server — use this to SSH in or configure DNS"
  value       = aws_instance.web_server.public_ip
}

output "vpc_id" {
  description = "ID of the created VPC — needed if other Terraform workspaces reference this network"
  value       = aws_vpc.primary_network.id
}

# backend.tf — Remote state configuration using S3 + DynamoDB
# This file MUST be committed to version control so the entire team
# uses the same backend. The S3 bucket and DynamoDB table themselves
# are usually bootstrapped manually (or via a separate 'bootstrap' Terraform workspace)
# because you can't store state for the thing that stores your state.

terraform {
  backend "s3" {
    bucket = "my-company-terraform-state"  # Must already exist — Terraform won't create it
    key    = "services/web-app/staging/terraform.tfstate"  # Path within the bucket — use a consistent naming scheme
    region = "us-east-1"

    # DynamoDB table provides state locking — prevents concurrent applies
    # Table must have a partition key named exactly 'LockID' (string type)
    dynamodb_table = "terraform-state-locks"

    # Encrypt the state file at rest — your state contains sensitive values
    # like database passwords and private IPs
    encrypt = true
  }
}

# ─── How to bootstrap the S3 bucket and DynamoDB table themselves ───
# The resources below are meant to run ONCE in a dedicated 'bootstrap' workspace
# that uses local state (committed to git for reference).
# After running this once, you never touch it again.

resource "aws_s3_bucket" "terraform_state_store" {
  bucket = "my-company-terraform-state"

  # Prevent accidental deletion of this bucket — if it's gone, all your state is gone
  lifecycle {
    prevent_destroy = true
  }

  tags = {
    Name      = "Terraform Remote State"
    ManagedBy = "terraform-bootstrap"
  }
}

# Versioning on the bucket means you can recover from a botched state write
# by rolling back to a previous version — this has saved production more than once
resource "aws_s3_bucket_versioning" "state_store_versioning" {
  bucket = aws_s3_bucket.terraform_state_store.id

  versioning_configuration {
    status = "Enabled"
  }
}

# Block all public access — state files contain secrets, never make them public
resource "aws_s3_bucket_public_access_block" "state_store_access_block" {
  bucket                  = aws_s3_bucket.terraform_state_store.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

# The DynamoDB table for distributed locking
resource "aws_dynamodb_table" "terraform_lock_table" {
  name         = "terraform-state-locks"
  billing_mode = "PAY_PER_REQUEST"  # No need to provision capacity for a low-traffic lock table
  hash_key     = "LockID"           # Must be exactly 'LockID' — Terraform expects this name

  attribute {
    name = "LockID"
    type = "S"  # String type
  }

  lifecycle {
    prevent_destroy = true  # Losing this table means losing state locking — never delete it
  }

  tags = {
    Name      = "Terraform State Lock Table"
    ManagedBy = "terraform-bootstrap"
  }
}

# ─── Project structure ───────────────────────────────────────────
# terraform-infrastructure/
# ├── modules/
# │   └── web_application/
# │       ├── main.tf       ← You are here
# │       ├── variables.tf
# │       └── outputs.tf
# ├── environments/
# │   ├── staging/
# │   │   ├── main.tf       ← Calls the module with staging values
# │   │   └── terraform.tfvars
# │   └── production/
# │       ├── main.tf       ← Calls the module with production values
# │       └── terraform.tfvars
# └── backend.tf
# ─────────────────────────────────────────────────────────────────

# modules/web_application/variables.tf
variable "environment_name" {
  type        = string
  description = "Deployment environment — controls naming and sizing"
  validation {
    condition     = contains(["staging", "production"], var.environment_name)
    error_message = "environment_name must be either 'staging' or 'production'."  # Catches typos before they hit AWS
  }
}

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

variable "vpc_cidr_block" {
  type        = string
  description = "CIDR block for the VPC — must not overlap with other environments"
}

# modules/web_application/main.tf
resource "aws_vpc" "app_network" {
  cidr_block = var.vpc_cidr_block

  tags = {
    Name        = "${var.environment_name}-app-vpc"
    Environment = var.environment_name
  }
}

resource "aws_subnet" "app_subnet" {
  vpc_id     = aws_vpc.app_network.id
  cidr_block = cidrsubnet(var.vpc_cidr_block, 8, 1)  # cidrsubnet carves a /24 out of the /16 automatically

  tags = {
    Name        = "${var.environment_name}-app-subnet"
    Environment = var.environment_name
  }
}

# modules/web_application/outputs.tf
output "vpc_id" {
  value       = aws_vpc.app_network.id
  description = "VPC ID — expose this so callers can attach other resources to the same network"
}

output "subnet_id" {
  value       = aws_subnet.app_subnet.id
  description = "Subnet ID for the primary application subnet"
}

# ─── environments/staging/main.tf ────────────────────────────────
# This is how you CALL the module from an environment directory.
# The module keyword points to the relative path of the module folder.

terraform {
  required_version = ">= 1.5.0"
  backend "s3" {
    bucket         = "my-company-terraform-state"
    key            = "environments/staging/terraform.tfstate"  # Unique key per environment
    region         = "us-east-1"
    dynamodb_table = "terraform-state-locks"
    encrypt        = true
  }
}

provider "aws" {
  region = "us-east-1"
}

module "staging_web_app" {
  source = "../../modules/web_application"  # Relative path to the module

  environment_name = "staging"
  instance_type    = "t3.micro"   # Cheaper instance for non-production
  vpc_cidr_block   = "10.1.0.0/16"  # Non-overlapping CIDR — staging uses 10.1.x.x
}

# ─── environments/production/main.tf ─────────────────────────────

module "production_web_app" {
  source = "../../modules/web_application"

  environment_name = "production"
  instance_type    = "t3.large"     # Larger instance for production load
  vpc_cidr_block   = "10.2.0.0/16"  # Production uses 10.2.x.x — no CIDR collision
}

# Outputs from a module are accessed via module.<module_name>.<output_name>
output "production_vpc_id" {
  value = module.production_web_app.vpc_id
}