Terraform mental model:
    HCL config = desired state
    provider   = cloud API adapter
    state      = address -> real resource ID mapping
    plan       = proposed diff
    apply      = execute reviewed diff

one state = one ownership boundary
remote backend + locking is default for team work
review every destroy and replacement before apply
use for_each for named resources; avoid count index drift
do not put secrets in tfvars, state, backend config, or plan files
manual console changes create drift; fix code, then reconcile

# Format all Terraform files.
terraform fmt -recursive

# Download providers/modules and initialize backend.
terraform init

# Check syntax and internal consistency.
terraform validate

# Validate local modules without touching remote backend.
terraform init -backend=false

# Preview changes.
terraform plan -var-file=envs/dev.tfvars

# Save a reviewed plan file.
terraform plan -var-file=envs/dev.tfvars -out=tfplan

# Apply exactly the reviewed plan.
terraform apply tfplan

# Show outputs and current state view.
terraform output
terraform show

# Avoid in shared dev / uat / prod.
terraform apply -auto-approve

infra-live
├── backend.tf
├── provider.tf
├── variables.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── envs
│   ├── dev.tfvars
│   ├── uat.tfvars
│   └── prod.tfvars
└── modules
    └── s3-bucket
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

backend.tf:
    remote state backend only

provider.tf:
    required providers, provider versions, provider config

variables.tf:
    typed input contract

locals.tf:
    naming, common tags, derived values

main.tf:
    resources and module calls

outputs.tf:
    IDs, ARNs, DNS names consumed by people or other states

envs/*.tfvars:
    environment values, not logic

terraform {
  required_version = ">= 1.6.0"

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

provider "aws" {
  region = var.aws_region

  default_tags {
    tags = local.common_tags
  }
}

terraform {
  backend "s3" {
    bucket       = "acme-tfstate-123456789012-ap-east-1"
    key          = "order/dev/default/ap-east-1/network/terraform.tfstate"
    region       = "ap-east-1"
    encrypt      = true
    use_lockfile = true
  }
}

S3 bucket versioning enabled
state locking enabled with use_lockfile
backend key includes system / env / variant / workload region / component
no access_key or secret_key in backend config
state bucket policy allows only required state prefixes

variable "env" {
  type        = string
  description = "Environment name: dev, uat, prod"
}

variable "aws_region" {
  type        = string
  description = "AWS region"
}

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

locals {
  name_prefix = "order-${var.env}"

  common_tags = {
    Project     = "order"
    Environment = var.env
    ManagedBy   = "terraform"
  }
}

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = true
  enable_dns_support   = true

  tags = {
    Name = "${local.name_prefix}-vpc"
  }
}

output "vpc_id" {
  value = aws_vpc.main.id
}

output "vpc_cidr" {
  value = aws_vpc.main.cidr_block
}

env        = "dev"
aws_region = "ap-east-1"
vpc_cidr   = "10.10.0.0/16"

resource "aws_s3_bucket" "logs" {
  bucket = "${local.name_prefix}-logs"
}

data "aws_caller_identity" "current" {}

output "account_id" {
  value = data.aws_caller_identity.current.account_id
}

resource:
    creates and manages infrastructure

data source:
    reads existing infrastructure or provider metadata

resource address:
    aws_s3_bucket.logs

variable "subnet_names" {
  type    = list(string)
  default = ["public-a", "public-b", "private-a"]
}

resource "aws_subnet" "this" {
  count = length(var.subnet_names)

  vpc_id     = aws_vpc.main.id
  cidr_block = cidrsubnet(var.vpc_cidr, 8, count.index)

  tags = {
    Name = var.subnet_names[count.index]
  }
}

if public-b is removed:
    private-a moves from index 2 to index 1
    resource address changes
    plan becomes hard to trust

variable "subnets" {
  type = map(object({
    cidr = string
    az   = string
  }))
}

resource "aws_subnet" "this" {
  for_each = var.subnets

  vpc_id            = aws_vpc.main.id
  cidr_block        = each.value.cidr
  availability_zone = each.value.az

  tags = {
    Name = each.key
  }
}

resource address is aws_subnet.this["private-a"]
removing public-b does not shift private-a
plan is easier to review

resource "aws_cloudwatch_log_group" "app" {
  name = "/aws/ecs/${local.name_prefix}"
}

resource "aws_ecs_service" "app" {
  name = local.name_prefix

  depends_on = [
    aws_cloudwatch_log_group.app
  ]
}

resource "aws_db_instance" "main" {
  identifier = "${local.name_prefix}-db"

  lifecycle {
    prevent_destroy = true
  }
}

resource "aws_ecs_service" "app" {
  name            = local.name_prefix
  task_definition = aws_ecs_task_definition.app.arn

  lifecycle {
    ignore_changes = [
      task_definition
    ]
  }
}

root module owns:
    environment values
    state boundary
    provider aliases
    high-level wiring between systems

shared module owns:
    repeatable resource pattern
    naming shape
    safe defaults
    outputs needed by callers

modules/s3-bucket
├── main.tf
├── variables.tf
└── outputs.tf

# modules/s3-bucket/variables.tf
variable "name" {
  type = string
}

# modules/s3-bucket/main.tf
resource "aws_s3_bucket" "this" {
  bucket = var.name
}

# modules/s3-bucket/outputs.tf
output "bucket_name" {
  value = aws_s3_bucket.this.bucket
}

module "app_logs" {
  source = "./modules/s3-bucket"

  name = "${local.name_prefix}-app-logs"
}

use typed variables with descriptions
return stable outputs
keep provider config in root module unless there is a strong reason
do not fork public modules just to rename variables
wrap public modules only when your team has repeated conventions

state stores:
    resource address
    provider type
    cloud resource ID
    attributes used for diff
    dependency mapping

do not edit state manually
do not commit terraform.tfstate
do not share local state by chat
do not run apply from two machines at the same time
do not merge unrelated ownership boundaries into one state

# List resources tracked by state.
terraform state list

# Show one resource from state.
terraform state show aws_vpc.main

# Show one resource inside a module.
terraform state show 'module.default.aws_lb.this[0]'

# Move resource address after refactor.
terraform state mv aws_s3_bucket.old aws_s3_bucket.new

# Remove resource from state without deleting real infrastructure.
terraform state rm aws_s3_bucket.legacy

existing cloud resource
    -> write matching Terraform config
    -> import remote ID into the exact Terraform address
    -> terraform plan
    -> adjust config until the diff is expected

import {
  to = aws_s3_bucket.logs
  id = "company-prod-logs"
}

resource "aws_s3_bucket" "logs" {
  bucket = "company-prod-logs"
}

# Review the import and resulting diff.
terraform plan

# Apply import into state.
terraform apply

# Root-module resource.
terraform import aws_s3_bucket.logs company-prod-logs

# Resource inside a normal module call.
terraform import \
  'module.network.aws_vpc.this' \
  vpc-0123456789abcdef0

# Resource inside a normal module call, when the resource uses count.
terraform import \
  'module.alb.aws_lb.this[0]' \
  'arn:aws:elasticloadbalancing:ap-east-1:123456789012:loadbalancer/app/order-prod-alb/0123456789abcdef'

# Resource inside a module created with for_each.
terraform import \
  'module.ecs_service["api"].aws_ecs_service.this' \
  'order-prod-cluster/api'

# Resource inside a module created with for_each, when the resource uses count.
terraform import \
  'module.alb["default"].aws_lb.this[0]' \
  'arn:aws:elasticloadbalancing:ap-east-1:123456789012:loadbalancer/app/order-prod-alb/0123456789abcdef'

module.<module_name>:
    normal module call

module.<module_name>["<key>"]:
    module call created with for_each

<resource_type>.<resource_name>:
    normal resource inside the module

<resource_type>.<resource_name>[0]:
    resource inside the module created with count

<resource_type>.<resource_name>["<key>"]:
    resource inside the module created with for_each

variable "services" {
  type = map(object({
    desired_count = number
    image         = string
  }))
}

services = {
  api = {
    desired_count = 2
    image         = "123456789012.dkr.ecr.ap-east-1.amazonaws.com/order-api:2026-07-08"
  }

  worker = {
    desired_count = 1
    image         = "123456789012.dkr.ecr.ap-east-1.amazonaws.com/order-worker:2026-07-08"
  }
}

module "ecs_service" {
  for_each = var.services

  source = "./modules/ecs-service"

  name        = each.key
  cluster_arn = module.ecs.cluster_arn
  desired_count = each.value.desired_count
  image         = each.value.image
}

resource "aws_ecs_service" "this" {
  name    = var.name
  cluster = var.cluster_arn
}

terraform import \
  'module.ecs_service["api"].aws_ecs_service.this' \
  'order-prod-cluster/api'

module.ecs_service:
    the module block name

["api"]:
    the for_each key from var.services

aws_ecs_service.this:
    the resource address inside ./modules/ecs-service

order-prod-cluster/api:
    AWS provider import ID, formatted as cluster-name/service-name
    order-prod-cluster is the ECS cluster name
    api is the ECS service name

1. write module/resource config with matching names, ports, subnets, security groups, roles, and health checks
2. import shared edge resources first: ALB, listeners, target groups
3. import ECS cluster
4. import IAM roles and CloudWatch log groups
5. import ECS service
6. decide separately whether Terraform should manage task definitions
7. run plan until there is no unexpected replacement

developer:
    edit .tf
    terraform fmt -recursive
    terraform validate
    terraform plan
    open PR with plan summary

reviewer:
    check create / update / replace / destroy
    check IAM permissions
    check public exposure
    check state boundary
    check names and tags

pipeline:
    init
    fmt -check
    validate
    plan
    manual approval
    apply reviewed plan

# PR validation without backend access.
terraform init -backend=false
terraform fmt -check -recursive
terraform validate

# Deployment pipeline.
terraform init
terraform plan -var-file=envs/prod.tfvars -out=tfplan
terraform apply tfplan

no unexpected destroy
no unexpected replacement
IAM changes reviewed
public networking reviewed
state backend and workspace are correct
plan file comes from the reviewed commit

mkdir -p "$HOME/.terraform.d/plugin-cache"
touch "$HOME/.terraformrc"

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

credentials "app.terraform.io" {
  token = "xxxxxx"
}

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
terraform init

terraform init
du -sh "$HOME/.terraform.d/plugin-cache"
find "$HOME/.terraform.d/plugin-cache" -maxdepth 6 -type f | head

cache directory must already exist
commit .terraform.lock.hcl
do not commit .terraform/ or plugin-cache
do not use the same directory as provider filesystem mirror
do not share one writable cache across many concurrent terraform init processes
manually clean old provider versions when the cache grows too large

Apple Silicon:
    darwin_arm64

Intel Mac:
    darwin_amd64

CI Linux runner:
    linux_amd64 or linux_arm64

terraform providers lock \
  -platform=darwin_arm64 \
  -platform=darwin_amd64 \
  -platform=linux_amd64

configuration:
    required_version and provider versions pinned
    variables are typed
    environment values live in tfvars
    common tags are applied by provider default_tags or locals

state:
    remote backend configured
    locking enabled
    bucket versioning enabled
    one state maps to one ownership boundary

security:
    no static cloud credentials in code
    no secrets in tfvars
    IAM changes reviewed before apply
    public exposure reviewed before apply

operations:
    plan is reviewed before apply
    replacement and destroy are explicitly approved
    outputs expose only useful IDs, ARNs, and endpoints
    import and state moves are performed in small batches