Intermediate

# Input variables declare the module's public API
variable "vpc_cidr" {
  # => Module input: CIDR block string (e.g. "10.0.0.0/16")
  description = "CIDR block for the VPC"
  # => Documents the variable for terraform plan output
  type        = string
  # => Enforces type at plan time; rejects non-string values
}

variable "environment" {
  # => Used to tag resources and form naming conventions
  description = "Deployment environment (dev/staging/prod)"
  type        = string
}

terraform {
  required_version = ">= 1.5"
  # => Minimum Terraform CLI version for this module
}

resource "aws_vpc" "main" {
  # => Creates an AWS VPC using the caller-supplied CIDR
  cidr_block = var.vpc_cidr
  # => var.vpc_cidr reads the module input variable
  # => e.g. "10.0.0.0/16" produces a /16 VPC

  tags = {
    Name        = "${var.environment}-vpc"
    # => Interpolation: "dev-vpc", "staging-vpc", etc.
    Environment = var.environment
    # => Tag used for cost allocation and filtering
  }
}

module "network" {
  # => Block type "module" with local label "network"
  source = "./modules/network"
  # => Relative path to the module directory

  vpc_cidr    = "10.0.0.0/16"
  # => Passes string to var.vpc_cidr inside the module
  environment = "dev"
  # => Passes string to var.environment inside the module
}

output "vpc_id" {
  # => Exposes the VPC ID to the calling configuration
  description = "ID of the created VPC"
  # => Terraform plan and docs will display this description
  value       = aws_vpc.main.id
  # => aws_vpc.main.id is populated after apply
  # => e.g. "vpc-0a1b2c3d4e5f6789"
}

output "vpc_cidr" {
  # => Secondary output: re-export the CIDR for chaining
  description = "CIDR block of the created VPC"
  value       = aws_vpc.main.cidr_block
  # => Returns the same CIDR passed in, confirming apply succeeded
}

module "network" {
  source      = "./modules/network"
  vpc_cidr    = "10.0.0.0/16"
  environment = "dev"
}

module "compute" {
  source = "./modules/compute"

  vpc_id = module.network.vpc_id
  # => module.<LABEL>.<OUTPUT_NAME> syntax
  # => Terraform builds an implicit dependency: compute waits for network
  environment = "dev"
}

output "network_vpc_id" {
  # => Root-level output exposes module output to operators
  value = module.network.vpc_id
  # => Printed after "terraform apply" completes
}

module "s3_bucket" {
  # => Registry source format: <namespace>/<module>/<provider>
  source  = "terraform-aws-modules/s3-bucket/aws"
  # => Downloads from registry.terraform.io on first init
  version = "~> 4.0"
  # => Pessimistic constraint: allow 4.x, reject 5.0+
  # => "~> 4.0" is equivalent to ">= 4.0, < 5.0"

  bucket = "my-app-assets-2025"
  # => Input variable: globally unique S3 bucket name
  acl    = "private"
  # => Input variable: access control list setting

  versioning = {
    # => Input variable: object-level versioning config
    enabled = true
    # => Enables S3 versioning for point-in-time recovery
  }

  tags = {
    Terraform   = "true"
    # => Standard tag indicating Terraform manages this resource
    Environment = "production"
  }
}

output "bucket_arn" {
  # => Output the ARN for use in IAM policies downstream
  value = module.s3_bucket.s3_bucket_arn
  # => Module exposes this output from the registry module
}

terraform {
  # => Terraform block configures CLI behavior and providers
  required_version = ">= 1.5"

  backend "s3" {
    # => Backend block is NOT a resource; it configures state storage
    bucket = "my-org-terraform-state"
    # => S3 bucket that stores the tfstate file
    # => Must exist before running "terraform init"

    key    = "prod/vpc/terraform.tfstate"
    # => Path within the bucket (acts like a folder + filename)
    # => Use path conventions: <env>/<component>/terraform.tfstate

    region = "us-east-1"
    # => AWS region where the S3 bucket lives

    encrypt = true
    # => Enables server-side encryption of the state file
    # => Critical: state contains secrets (passwords, private keys)

    dynamodb_table = "terraform-state-lock"
    # => DynamoDB table for distributed locking
    # => Prevents two concurrent applies from corrupting state
    # => Table must have a partition key named "LockID" (String)
  }
}

# main.tf — workspace-aware configuration

locals {
  # => locals block defines computed values (not inputs, not outputs)
  environment = terraform.workspace
  # => terraform.workspace is a built-in string: "default", "dev", "prod"
  # => Use it to branch configuration per workspace

  instance_size = {
    # => Map lookup: different sizes per environment
    default = "t3.micro"
    # => "default" workspace gets the smallest instance
    dev     = "t3.micro"
    # => Developer workspace: cheap, disposable
    staging = "t3.small"
    # => Staging: slightly larger for realistic load testing
    prod    = "t3.large"
    # => Production: full-size for real traffic
  }
}

resource "aws_instance" "app" {
  # => EC2 instance sized by workspace via local lookup
  ami           = "ami-0c02fb55956c7d316"
  instance_type = local.instance_size[terraform.workspace]
  # => Reads the map key matching the current workspace
  # => e.g., in "prod" workspace: instance_type = "t3.large"

  tags = {
    Name        = "${local.environment}-app-server"
    # => Tag reflects workspace name for easy identification
    Environment = local.environment
  }
}

terraform workspace new dev      # => Creates "dev" workspace and switches to it
terraform workspace new prod     # => Creates "prod" workspace
terraform workspace select dev   # => Switches active workspace to "dev"
terraform workspace list         # => Lists all workspaces; active has asterisk (*)
terraform workspace show         # => Prints current workspace name

# Step 1: Write the resource block to match the real infrastructure
# This HCL must exist BEFORE running "terraform import"

resource "aws_s3_bucket" "legacy_assets" {
  # => Resource address: aws_s3_bucket.legacy_assets
  # => Must match the address used in the import command
  bucket = "my-company-assets-legacy"
  # => The actual bucket name that already exists in AWS
}

# terraform import <resource_address> <provider_id>
terraform import aws_s3_bucket.legacy_assets my-company-assets-legacy
# => Reads the real S3 bucket from AWS API
# => Writes current attributes to state: aws_s3_bucket.legacy_assets
# => Does NOT modify the bucket; read-only API call during import

terraform plan
# => After import, plan shows any drift between HCL and real state
# => Fix HCL until "No changes" is shown before applying

# Read a VPC that exists in AWS but is not managed by THIS configuration
data "aws_vpc" "shared" {
  # => data block: reads from AWS, never creates or modifies
  filter {
    # => Filter narrows lookup to a specific VPC by tag
    name   = "tag:Environment"
    # => AWS tag key to filter on
    values = ["production"]
    # => Returns VPC where tag "Environment" = "production"
    # => Error if zero or multiple VPCs match
  }
}

data "aws_subnets" "private" {
  # => Reads subnet IDs matching the shared VPC
  filter {
    name   = "vpc-id"
    values = [data.aws_vpc.shared.id]
    # => data.aws_vpc.shared.id resolved at plan time
    # => Implicit dependency: subnets query waits for VPC data source
  }

  filter {
    name   = "tag:Tier"
    values = ["private"]
    # => Further narrows to private-tier subnets
  }
}

resource "aws_instance" "app" {
  # => Uses VPC and subnets from the data sources
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.small"
  subnet_id     = data.aws_subnets.private.ids[0]
  # => data.aws_subnets.private.ids is a list of subnet ID strings
  # => [0] picks the first subnet (deterministic ordering assumed)

  vpc_security_group_ids = [data.aws_vpc.shared.id]
  # => Reads VPC ID for security group scoping

  tags = {
    ManagedBy = "terraform"
  }
}

variable "ingress_rules" {
  # => Input: list of objects, each describing one firewall rule
  description = "List of ingress firewall rules"
  type = list(object({
    from_port   = number
    # => Start of port range (e.g. 443)
    to_port     = number
    # => End of port range (e.g. 443; same as from_port for single port)
    protocol    = string
    # => IP protocol: "tcp", "udp", "-1" (all)
    cidr_blocks = list(string)
    # => List of CIDR source ranges (e.g. ["0.0.0.0/0"])
  }))
  default = [
    { from_port = 80,  to_port = 80,  protocol = "tcp", cidr_blocks = ["0.0.0.0/0"] },
    { from_port = 443, to_port = 443, protocol = "tcp", cidr_blocks = ["0.0.0.0/0"] },
    { from_port = 22,  to_port = 22,  protocol = "tcp", cidr_blocks = ["10.0.0.0/8"] },
  ]
  # => Default: HTTP, HTTPS public + SSH internal-only
}

resource "aws_security_group" "web" {
  # => Security group with dynamic ingress rules
  name        = "web-sg"
  description = "Web server security group"
  vpc_id      = "vpc-0a1b2c3d"
  # => VPC where the security group is created

  dynamic "ingress" {
    # => dynamic block: iterates over var.ingress_rules
    for_each = var.ingress_rules
    # => for_each evaluates the list at plan time
    # => Each element becomes one "ingress" nested block

    content {
      # => content block maps iterator attributes to block arguments
      from_port   = ingress.value.from_port
      # => ingress.value accesses the current list element object
      to_port     = ingress.value.to_port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
    }
  }

  egress {
    # => Static egress: allow all outbound (common pattern)
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    # => "-1" means all protocols
    cidr_blocks = ["0.0.0.0/0"]
  }
}

variable "enable_bastion" {
  # => Feature flag: true creates the bastion, false skips it
  description = "Whether to create a bastion host"
  type        = bool
  default     = false
  # => Default: no bastion (follow least-privilege)
}

variable "environment" {
  type    = string
  default = "dev"
}

resource "aws_instance" "bastion" {
  # => Bastion host: conditionally created via count
  count = var.enable_bastion ? 1 : 0
  # => Conditional expression: (condition ? true_val : false_val)
  # => count = 1 → resource created as aws_instance.bastion[0]
  # => count = 0 → resource skipped; plan shows "0 to add"

  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.nano"
  # => Minimal instance size; bastion only forwards SSH

  tags = {
    Name = "${var.environment}-bastion"
  }
}

output "bastion_ip" {
  # => Output only meaningful when bastion exists
  value = var.enable_bastion ? aws_instance.bastion[0].public_ip : null
  # => [0] index required because count produces a list
  # => null output when bastion disabled: output = (known after apply) → null
}

variable "create_read_replicas" {
  description = "Set of replica identifiers to create (empty set = no replicas)"
  type        = set(string)
  default     = []
  # => Empty set: no replicas created (dev/test environments)
  # => ["replica-1", "replica-2"]: two replicas (prod environment)
}

resource "aws_db_instance" "replica" {
  # => for_each creates one RDS replica per set element
  for_each = var.create_read_replicas
  # => each.key = identifier string (e.g. "replica-1")
  # => each.value = same as key for a set (sets have no distinct value)

  identifier        = "myapp-${each.key}"
  # => Unique DB identifier per replica: "myapp-replica-1"
  instance_class    = "db.t3.medium"
  replicate_source_db = "myapp-primary"
  # => Points to the primary DB instance identifier

  tags = {
    Name        = "myapp-${each.key}"
    Environment = "production"
  }
}

output "replica_endpoints" {
  # => Map output: one endpoint per replica
  value = { for k, v in aws_db_instance.replica : k => v.endpoint }
  # => for expression builds a map: { "replica-1" = "myapp-replica-1.xxx.rds.amazonaws.com" }
  # => k = replica identifier, v = full resource object
}

resource "aws_db_instance" "primary" {
  # => Production database with lifecycle guards
  identifier        = "myapp-prod-db"
  engine            = "postgres"
  engine_version    = "15.3"
  instance_class    = "db.t3.medium"
  username          = "dbadmin"
  password          = var.db_password
  # => Reads from variable to avoid plaintext secret in HCL
  allocated_storage = 100

  lifecycle {
    # => lifecycle block: configures Terraform's behavior for this resource

    prevent_destroy = true
    # => Causes "terraform destroy" and config deletions to FAIL with error
    # => Protects databases, S3 buckets, and stateful storage
    # => Must set prevent_destroy = false and re-plan to remove resource

    ignore_changes = [
      password,
      # => AWS Secrets Manager rotates the password automatically
      # => Without ignore_changes, Terraform would revert rotation on next apply
      engine_version,
      # => Minor version auto-upgrades applied by AWS maintenance window
      # => Terraform would otherwise downgrade to HCL version after each window
    ]
  }

  tags = {
    Name        = "myapp-prod-db"
    Environment = "production"
  }
}

variable "environment" {
  description = "Deployment environment"
  type        = string

  validation {
    # => validation block: evaluated during "terraform plan"
    condition     = contains(["dev", "staging", "prod"], var.environment)
    # => contains(list, value): returns true if value is in list
    # => Plan fails if environment is not one of the three allowed values
    error_message = "environment must be one of: dev, staging, prod."
    # => Shown to the operator when condition is false
    # => Good messages name the allowed values explicitly
  }
}

variable "instance_count" {
  description = "Number of application instances"
  type        = number

  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 20
    # => && is logical AND; both conditions must be true
    # => Prevents misconfiguration: 0 instances (outage) or 100 (cost explosion)
    error_message = "instance_count must be between 1 and 20 inclusive."
  }
}

variable "vpc_cidr" {
  description = "VPC CIDR block"
  type        = string

  validation {
    condition     = can(cidrhost(var.vpc_cidr, 0))
    # => can(): returns true if expression succeeds without error
    # => cidrhost() fails on invalid CIDR, so can() catches invalid input
    # => Validates CIDR format (e.g. "10.0.0.0/16" passes; "10.0.0" fails)
    error_message = "vpc_cidr must be a valid IPv4 CIDR block (e.g. 10.0.0.0/16)."
  }
}

resource "aws_instance" "app" {
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.small"

  provisioner "local-exec" {
    # => Runs AFTER the EC2 instance is created and Terraform has its ID
    command = "echo ${self.public_ip} >> known_hosts.txt"
    # => self.public_ip: reference to the parent resource's attribute
    # => self is only valid inside provisioner blocks
    # => Appends the new instance's IP to a local file

    interpreter = ["/bin/bash", "-c"]
    # => Optional: set the shell interpreter
    # => Default on Unix: ["/bin/sh", "-c"]
    # => Default on Windows: ["cmd", "/C"]
  }

  provisioner "local-exec" {
    # => Multiple provisioner blocks execute in declaration order
    when    = destroy
    # => when = destroy: runs BEFORE the resource is destroyed
    # => when = create (default): runs after resource creation
    command = "echo Destroying ${self.id} >> destroy_log.txt"
    # => Logs the instance ID to an audit file before teardown
  }

  tags = {
    Name = "app-server"
  }
}

resource "aws_instance" "web" {
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.small"
  key_name      = aws_key_pair.deployer.key_name
  # => SSH key pair must exist for remote-exec to connect

  connection {
    # => connection block describes how to reach the instance
    type        = "ssh"
    # => Protocol: "ssh" (Linux) or "winrm" (Windows)
    user        = "ec2-user"
    # => AMI-specific SSH user (Amazon Linux 2: ec2-user, Ubuntu: ubuntu)
    private_key = file("~/.ssh/id_rsa")
    # => file() reads the private key from disk at plan time
    host        = self.public_ip
    # => self.public_ip: instance IP resolved after creation
  }

  provisioner "remote-exec" {
    # => Commands executed on the remote instance via SSH
    inline = [
      "sudo yum update -y",
      # => Updates all packages; blocking call (waits for completion)
      "sudo yum install -y nginx",
      # => Installs nginx web server
      "sudo systemctl enable nginx",
      # => Enables nginx to start on reboot
      "sudo systemctl start nginx",
      # => Starts nginx immediately
    ]
  }

  tags = {
    Name = "web-server"
  }
}

resource "null_resource" "deploy_app" {
  # => null_resource: exists only in Terraform state; no real cloud resource
  triggers = {
    # => triggers map: provisioners re-run whenever any value changes
    app_version = var.app_version
    # => Changing var.app_version (e.g. "1.2.3" → "1.3.0") triggers re-run
    instance_id = aws_instance.app.id
    # => Replacing the EC2 instance also triggers re-deployment
    deploy_hash = sha256(file("${path.module}/deploy.sh"))
    # => sha256(file()) computes hash of the deploy script
    # => Script content change triggers re-deployment even if version unchanged
  }

  provisioner "local-exec" {
    command = "bash deploy.sh ${aws_instance.app.public_ip} ${var.app_version}"
    # => Runs deploy.sh with the instance IP and app version
    # => Re-runs only when triggers map has changed values
  }

  depends_on = [aws_instance.app]
  # => Explicit dependency: deploy waits for the instance to be ready
  # => depends_on needed because null_resource does not reference instance attributes
}

output "vpc_id" {
  # => Must be defined in the source stack for remote_state to read it
  description = "Shared VPC ID for all compute stacks"
  value       = aws_vpc.main.id
  # => e.g. "vpc-0a1b2c3d4e5f6789"
}

output "private_subnet_ids" {
  description = "Private subnet IDs for compute placement"
  value       = aws_subnet.private[*].id
  # => [*] splat: collects IDs from all subnet instances into a list
}

data "terraform_remote_state" "networking" {
  # => Reads outputs from the networking stack's state file
  backend = "s3"
  # => Must match the backend type of the source stack

  config = {
    bucket = "my-org-terraform-state"
    key    = "prod/networking/terraform.tfstate"
    # => Path to the networking stack's state file in S3
    region = "us-east-1"
  }
}

resource "aws_instance" "app" {
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.small"

  subnet_id = data.terraform_remote_state.networking.outputs.private_subnet_ids[0]
  # => data.terraform_remote_state.<NAME>.outputs.<OUTPUT_NAME>
  # => Reads the private_subnet_ids output from the networking stack
  # => [0] picks the first private subnet

  tags = {
    Name  = "app-server"
    VpcId = data.terraform_remote_state.networking.outputs.vpc_id
    # => Also tags instance with VPC ID for easy filtering
  }
}

---
# defaults/main.yml: lowest-precedence variables
# => These values are easily overridden by inventory or playbook vars

http_port: 80
# => Default HTTP port; override to 8080 in container environments
https_port: 443
# => Default HTTPS port

document_root: /var/www/html
# => Web root directory; override per virtual host configuration

server_name: localhost
# => Nginx server_name directive value; override in inventory per host

---
# tasks/main.yml: entry point for the role's task list

- name: Install nginx
  # => Task name shown in ansible-playbook output
  ansible.builtin.package:
    # => ansible.builtin.package: OS-agnostic package installation
    # => Uses yum on RHEL/CentOS, apt on Debian/Ubuntu automatically
    name: nginx
    # => Package name (same across major distros)
    state: present
    # => present: install if missing; latest: always upgrade
  become: true
  # => become: true = sudo privilege escalation for this task

- name: Ensure document root exists
  ansible.builtin.file:
    # => Creates directory if it does not exist
    path: "{{ document_root }}"
    # => Jinja2: reads the defaults/main.yml variable
    state: directory
    # => directory: create as directory; file: create as file; absent: delete
    mode: "0755"
    # => Octal permissions: rwxr-xr-x
  become: true

- name: Deploy nginx configuration
  ansible.builtin.template:
    # => template module: renders Jinja2 template and copies to host
    src: nginx.conf.j2
    # => Relative to roles/webserver/templates/
    dest: /etc/nginx/nginx.conf
    # => Destination on the managed host
    mode: "0644"
    # => File permissions: rw-r--r--
  notify: restart nginx
  # => notify: triggers handler named "restart nginx" if task changed
  become: true

---
# handlers/main.yml: triggered by notify directives

- name: restart nginx
  # => Handler name must match the string in "notify: restart nginx" exactly
  ansible.builtin.service:
    # => service module manages systemd/init.d services
    name: nginx
    # => Service name as registered with systemd
    state: restarted
    # => restarted: stops then starts (applies config changes)
    # => reloaded: sends SIGHUP (graceful reload, no downtime)
  become: true

- name: reload nginx
  # => Separate handler for graceful reload (no connection drops)
  ansible.builtin.service:
    name: nginx
    state: reloaded
    # => nginx -s reload: validates config then gracefully reloads
  become: true

- name: restart postgresql
  # => Handlers are not limited to the role's primary service
  ansible.builtin.service:
    name: postgresql
    state: restarted
  become: true

---
- name: Deploy nginx main config
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    mode: "0644"
  notify: reload nginx
  # => Notifies "reload nginx" handler if this task reports "changed"
  # => If template is already up-to-date, task is "ok" and handler NOT notified
  become: true

- name: Deploy nginx SSL config
  ansible.builtin.template:
    src: ssl.conf.j2
    dest: /etc/nginx/conf.d/ssl.conf
    mode: "0644"
  notify: reload nginx
  # => Both tasks notify the same handler; it runs only once
  become: true

# Managed by Ansible — do not edit manually
# Generated: {{ ansible_date_time.iso8601 }}
{# ansible_date_time.iso8601 is a magic variable with current timestamp #}
{# Lines starting with {# are Jinja2 comments; stripped from output #}

user www-data;
worker_processes {{ ansible_processor_vcpus | default(2) }};
{# ansible_processor_vcpus: gathered fact (CPU count) #}
{# | default(2): fallback if fact not gathered (e.g. gather_facts: false) #}

error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

events {
    worker_connections {{ nginx_worker_connections | default(1024) }};
    {# Role variable with default; override in inventory for high-traffic hosts #}
}

http {
    server {
        listen {{ http_port }};
        {# http_port: from role defaults (80) or inventory override #}
        server_name {{ server_name }};
        {# server_name: set per-host in inventory for virtual hosting #}

        root {{ document_root }};
        {# document_root: path to web files on the managed host #}

        {% if enable_ssl | default(false) %}
        {# Jinja2 if block: only renders if enable_ssl is truthy #}
        listen {{ https_port }} ssl;
        ssl_certificate /etc/ssl/certs/{{ server_name }}.crt;
        ssl_certificate_key /etc/ssl/private/{{ server_name }}.key;
        {% endif %}
        {# {% endif %} closes the Jinja2 if block #}
    }
}

# Creating and using vault-encrypted variables

# Step 1: Create an encrypted variable file
# ansible-vault create group_vars/prod/vault.yml
# => Opens $EDITOR with an empty file; save to encrypt
# => Prompts for vault password

# Step 2: Contents of vault.yml (before encryption)
---
vault_db_password: "s3cr3t-production-password"
# => vault_ prefix convention: marks variables as vault-sourced
# => Plain text only visible during edit; stored encrypted

vault_api_key: "sk-prod-abc123xyz789"
# => API key for external service integration

vault_ssl_private_key: |
  -----BEGIN RSA PRIVATE KEY-----
  MIIEowIBAAKCAQEA...
  -----END RSA PRIVATE KEY-----
  # => Multiline string (|): literal block scalar in YAML
  # => Private key stored encrypted in version control

---
# Plain variable file references vault variables
db_password: "{{ vault_db_password }}"
# => Indirection: exposes vault variable under an environment-agnostic name
# => Playbook uses db_password; actual value comes from vault

api_key: "{{ vault_api_key }}"
# => Same pattern for API keys

db_host: "prod-db.internal.example.com"
# => Non-sensitive values stay in plain vars file
db_port: 5432
# => Mixing vault and plain vars in same directory is intentional

---
- name: Configure application database
  hosts: app_servers
  vars_files:
    - group_vars/prod/vars.yml
    # => Loads both plain vars and vault vars (Ansible merges them)
    - group_vars/prod/vault.yml
    # => Vault file decrypted at runtime using --vault-password-file or prompt

  tasks:
    - name: Write application config
      ansible.builtin.template:
        src: app_config.j2
        dest: /etc/app/config.yml
        mode: "0600"
        # => 0600: rw------- (owner read/write only; secret file)
      no_log: true
      # => no_log: true prevents task output from logging secret values
      # => Critical for tasks that handle passwords or private keys

---
- name: OS-aware package installation
  hosts: all
  gather_facts: true
  # => gather_facts: true (default): collects ansible_os_family, ansible_distribution, etc.

  tasks:
    - name: Install nginx on Debian-family systems
      ansible.builtin.apt:
        # => apt module: Debian/Ubuntu package manager
        name: nginx
        state: present
        update_cache: true
        # => update_cache: runs "apt update" before installing
      when: ansible_os_family == "Debian"
      # => when: skips task if os family is not Debian
      # => ansible_os_family is a gathered fact: "Debian", "RedHat", "Suse", etc.
      become: true

    - name: Install nginx on RedHat-family systems
      ansible.builtin.dnf:
        # => dnf module: RHEL 8+/Fedora package manager
        name: nginx
        state: present
      when: ansible_os_family == "RedHat"
      # => Only runs on RHEL/CentOS/Fedora/Amazon Linux
      become: true

    - name: Enable TLS only on production
      ansible.builtin.template:
        src: ssl.conf.j2
        dest: /etc/nginx/conf.d/ssl.conf
      when:
        # => List of conditions: ALL must be true (logical AND)
        - ansible_os_family == "Debian"
        # => Only on Debian systems
        - environment == "prod"
        # => Only in production environment variable
        - ssl_enabled | default(false)
        # => Only when ssl_enabled is explicitly set true
      become: true

    - name: Skip on unsupported distribution
      ansible.builtin.debug:
        msg: "Skipping: {{ ansible_distribution }} not supported"
        # => ansible_distribution: "Ubuntu", "CentOS", "Amazon", etc.
      when: ansible_distribution not in ["Ubuntu", "CentOS", "Amazon"]
      # => not in: boolean NOT membership test

---
- name: User and directory management
  hosts: all
  become: true

  vars:
    app_users:
      # => List of user objects to create
      - name: deploy
        groups: www-data
        # => Secondary group membership
        shell: /bin/bash
      - name: monitor
        groups: adm
        shell: /usr/sbin/nologin
        # => No-login shell for service accounts
      - name: backup
        groups: backup
        shell: /usr/sbin/nologin

    log_directories:
      # => List of directories to create with permissions
      - path: /var/log/app
        mode: "0755"
      - path: /var/log/app/errors
        mode: "0750"
        # => Restricted: owner and group only
      - path: /var/log/app/access
        mode: "0755"

  tasks:
    - name: Create application users
      ansible.builtin.user:
        # => user module manages Linux user accounts
        name: "{{ item.name }}"
        # => item: current loop element (the user object)
        # => item.name: accesses the "name" key of the dict
        groups: "{{ item.groups }}"
        shell: "{{ item.shell }}"
        state: present
        # => present: create if missing; absent: delete
      loop: "{{ app_users }}"
      # => loop: iterates over the app_users list
      # => Each iteration: item = { name: "deploy", groups: "www-data", ... }

    - name: Create log directories
      ansible.builtin.file:
        path: "{{ item.path }}"
        # => item.path from the log_directories list
        state: directory
        mode: "{{ item.mode }}"
        # => item.mode from the list; per-directory permissions
        owner: root
        group: root
      loop: "{{ log_directories }}"
      # => loop: one task execution per log directory

    - name: Install required packages
      ansible.builtin.package:
        name: "{{ item }}"
        # => item: plain string when looping over a simple list
        state: present
      loop:
        # => Inline list: alternative to vars for short lists
        - curl
        - jq
        - htop
        - git

module "network" {
  source = "../../modules/network"
  # => Relative path to shared module
  # => Both dev and prod call this same module

  vpc_cidr    = var.vpc_cidr
  # => var.vpc_cidr comes from environments/prod/terraform.tfvars
  environment = "prod"
}

module "compute" {
  source = "../../modules/compute"
  vpc_id      = module.network.vpc_id
  # => Cross-module reference: compute consumes network output
  instance_type = var.instance_type
  # => prod instance_type = "t3.large" (from terraform.tfvars)
  environment = "prod"
}

vpc_cidr      = "10.2.0.0/16"
# => Prod VPC CIDR: separate address space from dev (10.0.0.0/16)
instance_type = "t3.large"
# => Production-sized instances
min_capacity  = 3
# => Auto-scaling minimum: 3 instances for HA in prod
max_capacity  = 20

---
all:
  # => all: top-level group; every host is implicitly a member
  children:
    # => children: nested group definitions
    webservers:
      # => Group name used in playbook "hosts:" directive
      hosts:
        web-prod-01.example.com:
          # => Hostname or IP; becomes ansible_host if it resolves
          ansible_user: ec2-user
          # => SSH user for this specific host (host_var)
        web-prod-02.example.com:
          ansible_user: ec2-user
        web-prod-03.example.com:
          ansible_user: ec2-user
    databases:
      hosts:
        db-prod-01.example.com:
          ansible_user: ec2-user
          ansible_port: 2222
          # => Non-standard SSH port for database servers

---
# Variables applied to all hosts in the "webservers" group
# in the PROD inventory (overrides dev inventory group_vars)

environment: prod
# => Used in role templates and conditionals

http_port: 80
https_port: 443
enable_ssl: true
# => SSL enabled in prod; disabled in dev inventory equivalent

nginx_worker_connections: 4096
# => Higher limit for prod traffic; dev uses default (1024)

document_root: /var/www/html
server_name: www.example.com
# => Production domain name

---
- name: Adaptive service management
  hosts: webservers
  become: true

  tasks:
    - name: Check if nginx config is valid
      ansible.builtin.command:
        cmd: nginx -t
        # => nginx -t: tests configuration syntax without reloading
      register: nginx_config_test
      # => register: stores the task result in variable "nginx_config_test"
      # => nginx_config_test.rc: return code (0 = valid, 1 = invalid)
      # => nginx_config_test.stderr: nginx -t writes output to stderr
      changed_when: false
      # => This task only reads config; never reports "changed"
      failed_when: false
      # => failed_when: false prevents play abort on non-zero rc
      # => We handle the failure ourselves in the next task

    - name: Display nginx config errors
      ansible.builtin.debug:
        msg: "nginx config error: {{ nginx_config_test.stderr }}"
        # => .stderr: captures nginx -t error output (e.g. "unknown directive")
      when: nginx_config_test.rc != 0
      # => Only shows error when nginx -t exited non-zero

    - name: Reload nginx if config is valid
      ansible.builtin.service:
        name: nginx
        state: reloaded
      when: nginx_config_test.rc == 0
      # => Only reloads when config test passed
      # => Prevents reloading with broken config (nginx would reject it anyway)

    - name: Check if application process is running
      ansible.builtin.command:
        cmd: pgrep -f myapp
        # => pgrep -f: searches full command line, returns PIDs
      register: app_running
      # => app_running.rc: 0 if process found, 1 if not found
      changed_when: false
      failed_when: false

    - name: Start application if not running
      ansible.builtin.service:
        name: myapp
        state: started
      when: app_running.rc != 0
      # => Only starts app if pgrep returned non-zero (process not found)

variable "instances" {
  # => Input: map of instance names to their configuration objects
  description = "Map of instance name to configuration"
  type = map(object({
    instance_type = string
    environment   = string
  }))
  default = {
    "web-1" = { instance_type = "t3.micro",  environment = "dev" }
    "web-2" = { instance_type = "t3.small",  environment = "staging" }
    "api-1" = { instance_type = "t3.medium", environment = "prod" }
  }
}

locals {
  # => locals: computed values derived from inputs

  # Transform: keep only prod instances
  prod_instances = {
    for k, v in var.instances :
    # => for k, v in <map>: iterates with key k and value v
    k => v
    # => k => v: output key => output value
    if v.environment == "prod"
    # => if filter: only include elements where condition is true
    # => Result: { "api-1" = { instance_type = "t3.medium", environment = "prod" } }
  }

  # Transform: extract just the instance type values as a map
  instance_type_map = {
    for k, v in var.instances : k => v.instance_type
    # => Produces: { "web-1" = "t3.micro", "web-2" = "t3.small", "api-1" = "t3.medium" }
  }

  # Transform: list of unique environments
  environments = toset([
    for k, v in var.instances : v.environment
    # => [] list for expression: collects environment values
    # => toset(): deduplicates to unique values
    # => Result: toset(["dev", "staging", "prod"])
  ])
}

resource "aws_instance" "servers" {
  # => for_each over prod_instances map creates only prod resources
  for_each      = local.prod_instances
  ami           = "ami-0c02fb55956c7d316"
  instance_type = each.value.instance_type
  # => each.value accesses the object for this iteration

  tags = {
    Name        = each.key
    Environment = each.value.environment
  }
}

output "prod_instance_ids" {
  # => Output: map of prod instance names to IDs
  value = { for k, v in aws_instance.servers : k => v.id }
  # => for expression over resource: transforms resource map to ID map
}

variable "project"     { type = string; default = "myapp" }
variable "environment" { type = string; default = "prod" }
variable "region"      { type = string; default = "us-east-1" }

locals {
  # => locals block: computed once, referenced multiple times

  # Name prefix used by all resources
  name_prefix = "${var.project}-${var.environment}"
  # => "myapp-prod"; avoid repeating interpolation in every resource

  # Common tags applied to all resources
  common_tags = {
    Project     = var.project
    Environment = var.environment
    Region      = var.region
    ManagedBy   = "terraform"
    # => ManagedBy tag: identifies Terraform-managed resources in console
  }

  # Computed: region-to-AMI mapping (avoids hard-coding region-specific AMIs)
  ami_ids = {
    "us-east-1" = "ami-0c02fb55956c7d316"
    # => US East: Amazon Linux 2 AMI
    "us-west-2" = "ami-0ceecbb0f30a902a6"
    # => US West: Amazon Linux 2 AMI (different ID per region)
    "eu-west-1" = "ami-07d9160fa81ccffb5"
    # => EU West: Amazon Linux 2 AMI
  }

  # Lookup: select AMI for the current region
  current_ami = local.ami_ids[var.region]
  # => Fails at plan time if var.region not in the map (index error)
  # => Safer: lookup(local.ami_ids, var.region, "ami-default")
}

resource "aws_instance" "app" {
  ami           = local.current_ami
  # => local.current_ami: resolved AMI for the current region
  instance_type = "t3.small"

  tags = merge(local.common_tags, {
    # => merge(): combines two maps; second map wins on key conflict
    Name = "${local.name_prefix}-app"
    # => "myapp-prod-app"
    Role = "application"
    # => Resource-specific tag merged with common tags
  })
}

resource "aws_security_group" "app" {
  name = "${local.name_prefix}-sg"
  # => Reuses name_prefix: "myapp-prod-sg"

  tags = merge(local.common_tags, {
    Name = "${local.name_prefix}-sg"
    Role = "security"
  })
}

resource "aws_iam_role" "lambda_exec" {
  # => IAM role that the Lambda function will assume
  name = "myapp-lambda-exec"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Action    = "sts:AssumeRole"
      Effect    = "Allow"
      Principal = { Service = "lambda.amazonaws.com" }
    }]
  })
  # => jsonencode(): converts HCL object to JSON string
  # => IAM policies must be JSON strings, not HCL objects
}

resource "aws_iam_role_policy_attachment" "lambda_logs" {
  # => Attaches AWS-managed policy for CloudWatch logging
  role       = aws_iam_role.lambda_exec.name
  # => Implicit dependency: reads role name from the role resource
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}

resource "aws_lambda_function" "app" {
  # => Lambda function that needs the IAM role with policies attached
  function_name = "myapp-handler"
  role          = aws_iam_role.lambda_exec.arn
  # => Implicit dependency on the role (reads the ARN)
  # => BUT: Terraform might create Lambda before policy attachment propagates in IAM
  # =>  IAM changes take 5-10 seconds to propagate globally in AWS

  filename      = "function.zip"
  handler       = "index.handler"
  runtime       = "nodejs20.x"

  depends_on = [
    aws_iam_role_policy_attachment.lambda_logs,
    # => Explicit dependency: wait for policy attachment before creating Lambda
    # => Without this, Lambda creation races with IAM propagation
    # => apply may succeed but first invocation fails with permission denied
  ]
}

# Old structure: resource at root level
resource "aws_instance" "web_server" {
  # => State address: aws_instance.web_server
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.small"
  tags = { Name = "web-server" }
}

# New structure: resource now inside a module
module "compute" {
  source = "./modules/compute"
  # => Resource is now at: module.compute.aws_instance.app
}

moved {
  from = aws_instance.web_server
  # => The old state address (before refactoring)
  to   = module.compute.aws_instance.app
  # => The new state address (after moving into module)
  # => Terraform updates state file to new address
  # => No destroy/create cycle; EC2 instance continues running
}

resource "aws_instance" "app" {
  # => New name inside module: "app" (was "web_server")
  # => moved block maps old address to this new address
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.small"
  tags = { Name = "web-server" }
  # => Tags unchanged: ensures no resource recreation
}