Beginner

# => HCL blocks follow the pattern: block_type "label1" "label2" { arguments }
# => This is the most basic HCL structure you will write

terraform {
  # => The terraform block configures Terraform's own behavior
  # => It is optional but recommended for version pinning

  required_version = ">= 1.6.0"
  # => required_version enforces a minimum Terraform CLI version
  # => Prevents colleagues from running incompatible versions
  # => ">= 1.6.0" means version 1.6.0 or any newer release
}

terraform {
  required_providers {
    # => required_providers lists every provider plugin this config needs
    # => Terraform downloads these from the Terraform Registry on init

    aws = {
      # => "aws" is the local name used to reference this provider
      # => You will see it as "aws_*" resource prefixes throughout the config

      source  = "hashicorp/aws"
      # => source identifies the registry path: <namespace>/<type>
      # => hashicorp/aws is the official AWS provider maintained by HashiCorp

      version = "~> 5.0"
      # => version constraint: "~> 5.0" allows 5.x but not 6.0
      # => This is a pessimistic constraint operator (allows patch and minor updates)
    }
  }
}

provider "aws" {
  # => The provider block configures the named provider
  # => This aws block configures the hashicorp/aws plugin

  region = "us-east-1"
  # => region tells the AWS provider which data center to use
  # => AWS credentials are read from environment variables or ~/.aws/credentials
}

resource "aws_instance" "example" {
  # => resource block: block_type "resource_type" "local_name" { }
  # => aws_instance is the resource type (EC2 virtual machine in AWS)
  # => "example" is the local name used to reference this resource in other blocks

  ami           = "ami-0c55b159cbfafe1f0"
  # => ami is a string argument (always quoted with double quotes in HCL)
  # => ami-0c55b159cbfafe1f0 is an Amazon Machine Image ID (OS template)

  instance_type = "t2.micro"
  # => instance_type is also a string argument
  # => "t2.micro" selects a 1 vCPU / 1GB RAM instance size

  monitoring = false
  # => monitoring is a boolean argument (true/false, no quotes)
  # => false disables detailed CloudWatch monitoring (saves cost)

  root_block_device {
    # => Nested blocks group related arguments under a sub-block
    # => root_block_device configures the instance's primary disk

    volume_size = 20
    # => volume_size is a number argument (no quotes, no units)
    # => 20 means 20 gigabytes of storage

    delete_on_termination = true
    # => boolean: true means the disk is deleted when the instance is terminated
    # => Prevents orphaned EBS volumes from accumulating cost
  }
}

# This is a single-line comment using the hash symbol
# => Used for inline annotations on argument lines

// This is also a single-line comment using double-slash
// => Both # and // are equivalent; # is more common in the Terraform community

/*
  This is a multi-line block comment.
  Use it to document entire resource blocks or explain
  complex configurations that span several arguments.
*/
# => Block comments are useful for temporarily disabling sections of config

resource "aws_s3_bucket" "logs" {
  bucket = "my-app-logs-2026"
  # => Bucket names must be globally unique across all AWS accounts
  # => The naming pattern "app-purpose-year" helps ensure uniqueness

  force_destroy = true
  # => WARNING: force_destroy = true allows terraform destroy to delete non-empty buckets
  # => Acceptable in development; set to false in production to prevent accidental data loss
  // => This is a compliance-critical argument - review before production deployment
}

# .terraform.lock.hcl - AUTO-GENERATED, commit this file to version control
# => This file records the exact provider versions and checksums resolved by terraform init
# => Committing it ensures all team members and CI use identical provider binaries

provider "registry.terraform.io/hashicorp/aws" {
  # => Full registry path: registry.terraform.io/<namespace>/<type>
  # => This is the canonical identifier for the provider in the lock file

  version = "5.31.0"
  # => Exact version installed during init (not a constraint range)
  # => Terraform will refuse to use any other version until you run terraform init -upgrade

  constraints = "~> 5.0"
  # => The version constraint from your required_providers block
  # => Terraform checks that the installed version satisfies this constraint

  hashes = [
    "h1:abc123...",
    # => Cryptographic hash of the provider binary
    # => Terraform validates the download against this hash (supply chain security)
    "zh:def456...",
    # => Multiple hashes for different OS/architecture combinations
    # => Ensures the same provider works on macOS, Linux, and Windows
  ]
}

resource "aws_instance" "web_server" {
  # => resource "TYPE" "NAME" — two labels are required
  # => TYPE: aws_instance — the kind of resource (EC2 virtual machine)
  # => NAME: web_server — your local identifier for referencing this resource

  ami           = "ami-0c55b159cbfafe1f0"
  # => ami: the Amazon Machine Image (OS + software snapshot) to launch
  # => This AMI is Amazon Linux 2 in us-east-1 (AMIs are region-specific)

  instance_type = "t3.micro"
  # => instance_type: hardware profile (1 vCPU, 1GB RAM)
  # => t3.micro is free-tier eligible for 750 hours/month

  tags = {
    # => tags: a map of key-value metadata attached to the AWS resource
    # => Tags are critical for cost allocation, access control, and resource discovery

    Name        = "WebServer"
    # => Name tag appears as the instance's display name in the AWS Console

    Environment = "development"
    # => Environment tag helps filter resources by stage (dev/staging/prod)
    # => Many AWS Cost Explorer reports group by this tag
  }
}

resource "aws_vpc" "main" {
  # => Creates a Virtual Private Cloud (isolated network segment)

  cidr_block = "10.0.0.0/16"
  # => CIDR block: the IP address range for this VPC
  # => /16 gives 65,536 IP addresses (10.0.0.0 to 10.0.255.255)

  tags = {
    Name = "main-vpc"
  }
}

resource "aws_subnet" "public" {
  # => A subnet carves out a portion of the VPC's IP space

  vpc_id = aws_vpc.main.id
  # => Resource reference: TYPE.NAME.ATTRIBUTE
  # => aws_vpc.main.id reads the VPC ID that AWS assigns after creation
  # => Terraform sees this reference and creates aws_vpc.main BEFORE aws_subnet.public

  cidr_block = "10.0.1.0/24"
  # => /24 subnet gives 256 IP addresses (10.0.1.0 to 10.0.1.255)
  # => Must be a subset of the VPC's 10.0.0.0/16 range

  availability_zone = "us-east-1a"
  # => Subnets live in a single Availability Zone (physical data center)
}

resource "aws_security_group" "web" {
  # => Security groups are stateful firewalls attached to AWS resources
  # => They define allowed inbound (ingress) and outbound (egress) traffic

  name        = "web-sg"
  # => name: human-readable label shown in the AWS Console

  description = "Security group for web servers"
  # => description: required by AWS; documents the security group's purpose

  vpc_id = aws_vpc.main.id
  # => Attaches this security group to a specific VPC
  # => Security groups are VPC-scoped, not account-wide

  ingress {
    # => ingress block: defines one inbound traffic rule
    # => Multiple ingress blocks allowed (one rule per block)

    from_port   = 80
    to_port     = 80
    # => from_port and to_port define the allowed port range (80 to 80 = only port 80)

    protocol    = "tcp"
    # => protocol: "tcp", "udp", "icmp", or "-1" (all protocols)

    cidr_blocks = ["0.0.0.0/0"]
    # => cidr_blocks: list of IP ranges allowed to connect
    # => 0.0.0.0/0 means any IP address on the internet (public HTTP access)
  }

  egress {
    # => egress block: defines one outbound traffic rule

    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    # => protocol "-1" matches all protocols

    cidr_blocks = ["0.0.0.0/0"]
    # => Allow all outbound traffic — instances can reach the internet
    # => Restrict this in high-security environments
  }
}

# variables.tf

variable "instance_type" {
  # => variable block declares an input parameter by name
  # => "instance_type" is the variable name — referenced as var.instance_type

  type        = string
  # => type constraint: only string values accepted
  # => Terraform validates this at plan time, before any API calls

  description = "EC2 instance type for the web server"
  # => description documents what this variable controls
  # => Shown in terraform plan output and used by documentation generators

  default = "t3.micro"
  # => default: value used when no value is provided by the caller
  # => Variables with defaults are optional; without defaults they are required
}

variable "instance_count" {
  type    = number
  # => number type: accepts integers and floats

  default = 1
  description = "Number of EC2 instances to create"
}

variable "enable_monitoring" {
  type    = bool
  # => bool type: accepts true or false only

  default = false
  description = "Enable detailed CloudWatch monitoring"
}

# main.tf — uses variables declared in variables.tf

resource "aws_instance" "app" {
  ami           = "ami-0c55b159cbfafe1f0"
  # => ami hardcoded here; in practice this would also be a variable

  instance_type = var.instance_type
  # => var.instance_type reads the variable declared as variable "instance_type"
  # => At apply time, Terraform substitutes the actual value (e.g., "t3.micro")

  monitoring = var.enable_monitoring
  # => var.enable_monitoring is a bool variable
  # => false by default — no detailed monitoring unless explicitly enabled

  tags = {
    Name        = "app-server"
    Environment = var.environment
    # => var.environment will be provided by the caller (no default)
    # => Terraform will prompt for this value if not provided via tfvars or CLI
  }
}

variable "environment" {
  type        = string
  description = "Deployment environment (development, staging, production)"
  # => No default — caller MUST provide a value
  # => This makes the environment explicit and prevents accidental production deploys
}

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

  validation {
    # => validation block: runs a custom check against the variable value
    # => Multiple validation blocks allowed per variable

    condition = contains(["development", "staging", "production"], var.environment)
    # => condition: a boolean expression that must evaluate to true
    # => contains(list, element): true if element is in list
    # => var.environment must be exactly one of the three allowed strings

    error_message = "Environment must be 'development', 'staging', or 'production'."
    # => error_message: shown to the user when condition is false
    # => Write a clear, actionable message (not just "invalid value")
  }
}

variable "instance_count" {
  type    = number
  default = 1

  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 20
    # => Ensures count is between 1 and 20 (inclusive)
    # => && is logical AND — both conditions must be true

    error_message = "Instance count must be between 1 and 20."
    # => Prevents accidentally spinning up hundreds of instances
  }
}

# development.tfvars — variable values for the development environment
# => .tfvars files contain only variable assignments, no blocks or resource declarations
# => Apply with: terraform apply -var-file="development.tfvars"

instance_type     = "t3.micro"
# => Development uses the smallest instance to minimize cost
# => The same configuration uses "t3.large" in production.tfvars

instance_count    = 1
# => Single instance in development; production.tfvars sets this to 3+

environment       = "development"
# => Satisfies the validation rule in variables.tf

enable_monitoring = false
# => No detailed monitoring in development (saves cost)

allowed_cidrs     = ["10.0.0.0/8"]
# => Restrict access to internal network in development
# => production.tfvars might add 0.0.0.0/0 for public access

# outputs.tf

output "instance_public_ip" {
  # => output block declares a value to surface after terraform apply
  # => "instance_public_ip" is the output name shown in the CLI

  value = aws_instance.web_server.public_ip
  # => value: the expression to evaluate and display
  # => aws_instance.web_server.public_ip reads the IP address AWS assigned

  description = "The public IP address of the web server"
  # => description: documents what this output represents
  # => Shown in terraform output --help and module documentation
}

output "instance_id" {
  value       = aws_instance.web_server.id
  # => .id is the resource's unique identifier assigned by AWS (e.g., "i-0abc123def")
  description = "The EC2 instance ID for use with AWS CLI commands"
}

output "vpc_id" {
  value       = aws_vpc.main.id
  description = "VPC ID for use in dependent Terraform configurations"

  sensitive = false
  # => sensitive = true hides the value from CLI output (for passwords, tokens)
  # => false is the default; listed here for documentation purposes
}

resource "aws_db_instance" "main" {
  # => Simulated RDS database instance (simplified for illustration)

  identifier     = "app-db"
  engine         = "postgres"
  instance_class = "db.t3.micro"
  username       = var.db_username
  # => Reads username from a variable (not hardcoded)
  password       = var.db_password
  # => Reads password from a sensitive variable
}

variable "db_password" {
  type        = string
  description = "RDS master password"
  sensitive   = true
  # => sensitive = true: Terraform redacts this variable's value in all output
  # => The value is still stored in state; this only affects display
}

output "db_endpoint" {
  value       = aws_db_instance.main.endpoint
  # => endpoint is the hostname:port string (e.g., "app-db.xyz.us-east-1.rds.amazonaws.com:5432")
  description = "Database connection endpoint"
}

output "db_password_reminder" {
  value     = aws_db_instance.main.password
  # => Exposes the password as an output (needed by application configs)

  sensitive = true
  # => sensitive = true hides the value in terraform output and plan diffs
  # => Prints "(sensitive value)" in the terminal instead of the actual password
  # => The value is still accessible via: terraform output -raw db_password_reminder
}

data "aws_ami" "amazon_linux" {
  # => data block: data "TYPE" "NAME" { filter arguments }
  # => Reads existing AWS infrastructure without managing it
  # => "amazon_linux" is your local name for referencing this data source

  most_recent = true
  # => most_recent: when multiple AMIs match the filters, return the newest
  # => Essential for always using the latest patched OS image

  owners = ["amazon"]
  # => owners: filter AMIs to those published by the official "amazon" account
  # => Prevents using unofficial or potentially malicious images

  filter {
    # => filter blocks narrow down which AMI is returned
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
    # => name filter: AMI names matching this glob pattern
    # => * matches any version string, returning the latest Amazon Linux 2 AMI
  }
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux.id
  # => data reference: data.TYPE.NAME.ATTRIBUTE
  # => Reads the AMI ID that the data source fetched
  # => Always uses the latest Amazon Linux 2 AMI, no hardcoded IDs needed

  instance_type = "t3.micro"
}

data "aws_vpc" "existing" {
  # => Looks up an existing VPC by its tags
  # => Useful when your Terraform config deploys INTO a VPC managed elsewhere

  tags = {
    Name        = "production-vpc"
    Environment = "production"
    # => Both tags must match — acts as AND filter
    # => The VPC must have BOTH the Name and Environment tags set to these values
  }
}

data "aws_subnet" "app_tier" {
  vpc_id = data.aws_vpc.existing.id
  # => Reads the VPC ID from the data source above
  # => Creates a dependency: aws_vpc data source is read before aws_subnet

  filter {
    name   = "tag:Tier"
    values = ["application"]
    # => Filter by a specific tag (tag:KEY format)
    # => Finds the subnet tagged with Tier = "application"
  }

  filter {
    name   = "availabilityZone"
    values = ["us-east-1a"]
    # => Second filter: narrows to a specific availability zone
    # => Both filters must match (AND logic)
  }
}

resource "aws_instance" "app" {
  subnet_id = data.aws_subnet.app_tier.id
  # => Deploys the instance into the subnet discovered by the data source
  # => The actual subnet ID is resolved at plan time from existing AWS resources

  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
}

locals {
  # => locals block: one or more key = expression assignments
  # => Values are computed once and referenced as local.NAME throughout the config

  project     = "myapp"
  environment = var.environment
  # => Captures the variable into a local for shorter references

  common_tags = {
    # => A map computed from other locals and variables
    # => Apply these tags to every resource for consistent cost allocation

    Project     = local.project
    Environment = local.environment
    # => Referencing other locals: local.NAME
    ManagedBy   = "terraform"
    # => Hard-coded tag that marks all resources as Terraform-managed
  }

  name_prefix = "${local.project}-${local.environment}"
  # => String interpolation: ${expression} embeds expressions in strings
  # => "${local.project}-${local.environment}" with project="myapp" and environment="dev"
  # => => name_prefix is "myapp-dev"
}

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

  tags = merge(local.common_tags, {
    Name = "${local.name_prefix}-web"
    # => "${local.name_prefix}-web" => "myapp-dev-web"
  })
  # => merge(map1, map2): combines two maps, second map's keys override first map's
  # => Applies common_tags plus a resource-specific Name tag
}

variable "project_name" {
  type    = string
  default = "webapp"
}

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

locals {
  # => String interpolation examples

  bucket_name = "${var.project_name}-${var.region}-artifacts"
  # => interpolates two variables into a string
  # => with defaults: bucket_name = "webapp-us-east-1-artifacts"

  log_prefix = "${var.project_name}/logs/"
  # => Mixed literal and variable: var.project_name = "webapp"
  # => => log_prefix = "webapp/logs/"

  resource_arn = "arn:aws:s3:::${local.bucket_name}"
  # => Constructs an AWS ARN (Amazon Resource Name) using the local value
  # => => resource_arn = "arn:aws:s3:::webapp-us-east-1-artifacts"
}

resource "aws_s3_bucket" "artifacts" {
  bucket = local.bucket_name
  # => Uses the interpolated local value as the bucket name
  # => Result: "webapp-us-east-1-artifacts"

  tags = {
    Name   = local.bucket_name
    Region = var.region
  }
}

# This configuration produces different plan output depending on current state

resource "aws_s3_bucket" "data" {
  bucket = "my-app-data-2026"
  # => If bucket does not exist: plan shows "+ aws_s3_bucket.data will be created"
  # => If bucket already exists with same config: plan shows "No changes"
  # => If bucket exists but config differs: plan shows "~ aws_s3_bucket.data will be updated"

  tags = {
    Environment = "production"
    # => Changing a tag value produces: ~ tags.Environment: "development" -> "production"
    # => This is an in-place update — no resource recreation needed
  }
}

# Plan output symbols:
# + resource will be created   (green plus sign)
# - resource will be destroyed  (red minus sign)
# ~ resource will be updated    (yellow tilde)
# -/+ resource must be replaced (destroy then recreate)
# => Understanding these symbols is essential before running terraform apply

# main.tf — configuration to apply

resource "aws_instance" "demo" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

  tags = {
    Name = "demo-instance"
  }
}

output "instance_id" {
  value = aws_instance.demo.id
  # => After apply, the instance ID is written to state and displayed here
  # => Example: instance_id = "i-0a1b2c3d4e5f6a7b8"
}

# Typical apply workflow:
# 1. terraform init      # => Downloads providers, creates .terraform/ directory
# 2. terraform plan      # => Shows what will be created (+ aws_instance.demo)
# 3. terraform apply     # => Prompts "Do you want to perform these actions?"
#                        # => Type "yes" and press Enter to proceed
#                        # => Terraform calls AWS APIs to create the instance
# 4. terraform output    # => Shows output values (instance_id = "i-...")

# For CI/CD pipelines (non-interactive environments):
# terraform apply -auto-approve
# => Skips the confirmation prompt
# => ONLY safe in automated pipelines with proper plan review gates

# There is no special configuration for destroy — it reads existing resources from state
# The configuration below would be destroyed when terraform destroy is run

resource "aws_instance" "temp" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
  tags = {
    Name        = "temporary-test"
    AutoDestroy = "true"
    # => Tag to identify ephemeral resources created for testing
    # => Some teams use Lambda functions to auto-destroy tagged resources nightly
  }
}

resource "aws_s3_bucket" "temp_storage" {
  bucket        = "temp-test-storage-2026"
  force_destroy = true
  # => force_destroy = true: allows destroy even if bucket contains objects
  # => REQUIRED for terraform destroy to work on non-empty buckets
  # => NEVER set this on production buckets containing important data
}

# terraform destroy output:
# Terraform will perform the following actions:
#
#   - aws_instance.temp will be destroyed
#   - aws_s3_bucket.temp_storage will be destroyed
#
# Plan: 0 to add, 0 to change, 2 to destroy.
#
# Do you really want to destroy all resources?
# => Type "yes" to confirm (same confirmation gate as apply)

# The state file (terraform.tfstate) is JSON — a simplified excerpt:
#
# {
#   "version": 4,
#   "resources": [
#     {
#       "type": "aws_instance",
#       "name": "web",
#       "instances": [
#         {
#           "attributes": {
#             "id": "i-0abc123def456",
#             "instance_type": "t3.micro",
#             "public_ip": "54.123.45.67"
#           }
#         }
#       ]
#     }
#   ]
# }

# Rules for working with state:

# Rule 1: NEVER edit terraform.tfstate manually
# => Corrupted state causes Terraform to lose track of real infrastructure
# => Use terraform state commands for any state manipulation

# Rule 2: NEVER commit terraform.tfstate to version control
# => State contains sensitive values (passwords, private keys) in plain text
# => Use remote backends (S3, Terraform Cloud) for shared state

# Rule 3: Use remote backends for team environments
# => Local state cannot be shared across team members or CI/CD pipelines
# => Remote backends provide locking to prevent concurrent apply conflicts

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  # => After apply, state records the resolved ami ID and all computed attributes
  # => terraform state show aws_instance.web displays the full state record
  instance_type = "t3.micro"
}

terraform {
  backend "s3" {
    # => backend block configures where Terraform stores state
    # => "s3" uses an S3 bucket as the remote state store

    bucket = "my-terraform-state-2026"
    # => S3 bucket name (must already exist before running terraform init)
    # => The bucket itself is NOT managed by this configuration (chicken-and-egg)

    key    = "environments/production/terraform.tfstate"
    # => Object key (path) within the bucket for this state file
    # => Use a consistent naming convention: environments/ENV/COMPONENT/terraform.tfstate

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

    encrypt = true
    # => encrypt = true: S3 server-side encryption for the state file at rest
    # => Protects secrets stored in state from unauthorized bucket access

    dynamodb_table = "terraform-state-locks"
    # => DynamoDB table for state locking (prevents concurrent applies)
    # => Table must have a primary key named "LockID" (string type)
    # => Without locking, two concurrent applies can corrupt state
  }
}

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
  # => Created first because aws_subnet.public references it
}

resource "aws_subnet" "public" {
  vpc_id     = aws_vpc.main.id
  # => IMPLICIT dependency: this reference tells Terraform to create aws_vpc.main first
  # => Terraform builds a dependency graph and determines creation order automatically

  cidr_block = "10.0.1.0/24"
}

resource "aws_s3_bucket" "logs" {
  bucket = "app-access-logs-2026"
  # => No reference to aws_instance.web — no implicit dependency
}

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
  subnet_id     = aws_subnet.public.id
  # => Implicit dependency on aws_subnet.public (and transitively on aws_vpc.main)

  depends_on = [aws_s3_bucket.logs]
  # => EXPLICIT dependency: ensures aws_s3_bucket.logs is created before aws_instance.web
  # => Use depends_on when a dependency exists that Terraform cannot infer from references
  # => Example: the instance writes logs to S3, but the bucket ARN is not referenced in code
}

variable "instance_count" {
  type    = number
  default = 3
}

resource "aws_instance" "web" {
  count = var.instance_count
  # => count: creates var.instance_count identical instances
  # => count = 3 => creates aws_instance.web[0], aws_instance.web[1], aws_instance.web[2]

  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

  tags = {
    Name = "web-server-${count.index}"
    # => count.index: zero-based index of the current instance (0, 1, 2, ...)
    # => "web-server-${count.index}" => "web-server-0", "web-server-1", "web-server-2"

    Index = count.index
    # => count.index is a number — usable directly as a tag value
  }
}

output "instance_ids" {
  value = aws_instance.web[*].id
  # => [*] splat expression: collects the .id attribute from all count instances
  # => => ["i-0abc", "i-0def", "i-0ghi"] (one ID per instance)

  description = "IDs of all web server instances"
}

variable "environments" {
  type = map(string)
  # => map(string): a map where all values are strings
  # => The key is the environment name; the value is the instance type

  default = {
    development = "t3.micro"
    staging     = "t3.small"
    production  = "t3.large"
    # => Three environments, three instance types
    # => for_each will create one EC2 instance per entry
  }
}

resource "aws_instance" "env" {
  for_each = var.environments
  # => for_each: creates one instance per map entry
  # => Creates: aws_instance.env["development"], aws_instance.env["staging"], aws_instance.env["production"]

  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = each.value
  # => each.value: the map value for the current entry (e.g., "t3.micro" for development)

  tags = {
    Name        = "server-${each.key}"
    # => each.key: the map key for the current entry (e.g., "development")
    # => "server-${each.key}" => "server-development", "server-staging", "server-production"

    Environment = each.key
    # => Tags the instance with its environment name
  }
}

# site.yml — a minimal Ansible playbook
---
# => --- marks the start of a YAML document (optional but conventional)

- name: Configure web servers
  # => - (dash) begins a play — a playbook can contain multiple plays
  # => name: human-readable description shown in ansible-playbook output

  hosts: web
  # => hosts: which hosts or groups from inventory this play targets
  # => "web" matches the [web] group in the inventory file

  become: true
  # => become: true enables privilege escalation (sudo)
  # => Required for tasks that install packages or modify system files

  vars:
    app_port: 8080
    # => vars: play-level variables available to all tasks in this play
    # => Equivalent to Terraform variables but scoped to a single play

  tasks:
    # => tasks: the ordered list of actions Ansible executes on each host

    - name: Install nginx
      # => Each task has a name (shown in output) and one module call

      ansible.builtin.package:
        # => ansible.builtin.package: the module that manages OS packages
        # => ansible.builtin is the fully-qualified collection namespace

        name: nginx
        # => name: the package to manage

        state: present
        # => state: present = install if not already installed
        # => Ansible is idempotent: running this twice does NOT reinstall nginx

# hosts.ini — static inventory in INI format
# => INI format: [group_name] followed by host entries

[web]
# => [web] defines a group named "web"
# => Hosts in this group are targeted when plays specify hosts: web

web-server-01 ansible_host=10.0.1.10
# => web-server-01: the inventory hostname (your alias for this host)
# => ansible_host=10.0.1.10: the actual IP or DNS name Ansible connects to

web-server-02 ansible_host=10.0.1.11
# => Second host in the [web] group

[db]
# => [db] group for database servers

db-primary ansible_host=10.0.2.10 ansible_user=ec2-user
# => ansible_user: the SSH username (overrides default for this host)
# => ec2-user is the default user for Amazon Linux AMIs

[web:vars]
# => [group:vars] sets variables for all hosts in a group
# => These override inventory defaults for the [web] group

ansible_user=ubuntu
# => All web servers connect as the "ubuntu" user
# => Ubuntu AMIs use "ubuntu" as the default SSH user

ansible_ssh_private_key_file=~/.ssh/webserver_key.pem
# => Path to the SSH private key for this group
# => The matching public key must be in ~/.ssh/authorized_keys on the servers

[all:vars]
# => [all:vars]: variables applied to every host in the inventory

ansible_python_interpreter=/usr/bin/python3
# => Specifies which Python interpreter Ansible uses on managed hosts
# => Required when the system has both python2 and python3 installed