Locking #

# S3 Backend — butuh DynamoDB untuk locking
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "production/terraform.tfstate"
    region         = "ap-southeast-1"
    dynamodb_table = "terraform-state-lock"  # Wajib untuk locking
    encrypt        = true
  }
}

# Lock entry di DynamoDB saat apply sedang berjalan:
# LockID: "my-terraform-state/production/terraform.tfstate"
# Info:   {"ID":"abc123", "Operation":"OperationTypeApply",
#          "Who":"user@hostname", "Created":"2024-01-15T10:30:00Z"}

# GCS Backend — locking built-in, tidak perlu resource tambahan
terraform {
  backend "gcs" {
    bucket = "my-terraform-state"
    prefix = "production"
    # Locking menggunakan GCS object versioning — otomatis
  }
}

# Terraform Cloud — locking built-in, dikelola platform
terraform {
  cloud {
    organization = "my-org"
    workspaces {
      name = "production"
    }
  }
}

# Error yang muncul saat lock sedang dipegang:
$ terraform apply

╷
│ Error: Error acquiring the state lock
│
│ Error message: ConditionalCheckFailedException: ...
│ Lock Info:
│   ID:        abc123def456
│   Path:      my-terraform-state/production/terraform.tfstate
│   Operation: OperationTypeApply
│   Who:       [email protected]
│   Version:   1.6.3
│   Created:   2024-01-15 10:30:00.123456789 +0000 UTC
│   Info:
╵

# Informasi penting dari error ini:
# - ID: digunakan untuk force-unlock jika diperlukan
# - Who: siapa yang memegang lock saat ini
# - Created: kapan lock diambil (jika sudah lama, mungkin stuck)

# Cek apakah ada lock aktif
terraform plan
# Jika ada lock, error message akan menampilkan Lock ID

# Force unlock — gunakan Lock ID dari error message
terraform force-unlock abc123def456

# PENTING: Pastikan tidak ada proses Terraform lain yang sedang berjalan
# sebelum melakukan force-unlock. Force unlock pada apply yang masih
# berjalan bisa menyebabkan state corrupt.

# Strategi 1: Serialized pipeline
# Pastikan hanya satu pipeline apply yang bisa berjalan bersamaan
# (konfigurasi di CI/CD tool — GitHub Actions concurrency, GitLab resource groups)

# GitHub Actions: concurrency group
name: Terraform Apply
concurrency:
  group: terraform-production  # Hanya satu workflow dengan group ini boleh jalan
  cancel-in-progress: false    # Jangan cancel yang sedang jalan, antrikan

jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - name: Terraform Apply
        run: terraform apply -auto-approve tfplan

# Strategi 2: Timeout yang masuk akal
# Jika pipeline stuck dan lock tidak terlepas setelah timeout,
# pipeline bisa dianggap failed dan alert dikirim

terraform apply -lock-timeout=5m  # Tunggu maksimal 5 menit untuk acquire lock
# Jika tidak berhasil dalam 5 menit, error dan gagal

# ANTI-PATTERN: Disable locking secara permanen
terraform apply -lock=false  # ✗ Sangat berbahaya di lingkungan tim

# BENAR: Disable locking hanya jika benar-benar terpaksa
# dan kamu yakin tidak ada proses lain yang berjalan
terraform plan -lock=false   # Misalnya: hanya untuk inspeksi darurat

# S3 + DynamoDB locking internals:
# 1. Terraform membuat item di DynamoDB dengan LockID
# 2. Menggunakan DynamoDB conditional write:
#    PutItem dengan ConditionExpression = "attribute_not_exists(LockID)"
# 3. Jika LockID sudah ada → ConditionalCheckFailedException
# 4. Hanya satu proses yang berhasil menulis → atomic

# DynamoDB lock item structure:
{
  "LockID": "my-bucket/production/terraform.tfstate",
  "Info": {
    "ID": "a3b4c5d6-e7f8-9012-abcd-ef1234567890",
    "Operation": "OperationTypeApply",
    "Who": "[email protected]",
    "Version": "1.6.3",
    "Created": "2024-01-15T10:30:00Z",
    "Path": "my-bucket/production/terraform.tfstate"
  }
}

# GCS locking internals:
# 1. Terraform membuat file .tflock di bucket
# 2. Menggunakan GCS preconditions:
#    ifGenerationMatch: 0 (hanya berhasil jika file belum ada)
# 3. Hapus file .tflock saat release
# 4. GCS menjamin atomicity melalui preconditions

# Default lock timeout adalah 0s — langsung error jika lock dipegang
terraform apply
# Error: Error acquiring the state lock (langsung gagal)

# Atur timeout untuk menunggu lock terlepas
terraform apply -lock-timeout=5m   # Tunggu maksimal 5 menit
terraform apply -lock-timeout=30s  # Tunggu maksimal 30 detik
terraform apply -lock-timeout=1h   # Tunggu maksimal 1 jam

# SITUASI: Lock stuck, tidak tahu siapa yang memegang
$ terraform plan

Error: Error acquiring the state lock
Lock Info:
  ID:        a3b4c5d6-e7f8-9012-abcd-ef1234567890
  Operation: OperationTypeApply
  Who:       deploy-agent@ci-runner-03
  Created:   2024-01-15 10:30:00 +0000 UTC
  Info:

# LANGKAH 1: Cek apakah proses masih berjalan
# Di CI/CD — cek apakah runner/pod masih aktif
kubectl get pods -l app=terraform-runner
# Jika pod sudah tidak ada → lock stuck, aman untuk force-unlock

# LANGKAH 2: Cek umur lock
# Lock yang sudah lebih dari 30 menit tanpa progress biasanya stuck
LOCK_CREATED="2024-01-15T10:30:00Z"
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
echo "Lock age: $(($(date -d "$NOW" +%s) - $(date -d "$LOCK_CREATED" +%s))) seconds"

# LANGKAH 3: Cek DynamoDB langsung (untuk S3 backend)
aws dynamodb get-item \
  --table-name terraform-state-lock \
  --key '{"LockID":{"S":"my-bucket/production/terraform.tfstate"}}'

# LANGKAH 4: Force unlock jika yakin tidak ada proses aktif
terraform force-unlock a3b4c5d6-e7f8-9012-abcd-ef1234567890

# LANGKAH 5: Verifikasi state konsisten setelah unlock
terraform plan
# Harusnya "No changes" — jika ada perubahan tak terduga,
# kemungkinan apply sebelumnya terpotong di tengah jalan

# Lock table yang bisa digunakan untuk banyak state (shared)
resource "aws_dynamodb_table" "terraform_lock" {
  name         = "terraform-state-lock"
  billing_mode = "PAY_PER_REQUEST"  # Tidak perlu provisioned capacity
  hash_key     = "LockID"

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

  # TTL untuk auto-cleanup lock yang stuck
  # (perlu TTL attribute bernama "ExpiresAt" di item)
  ttl {
    attribute_name = "ExpiresAt"
    enabled        = true
  }

  point_in_time_recovery {
    enabled = true  # Backup lock table
  }
}

# PATTERNS:

# 1. Shared lock table untuk semua state
#    Satu DynamoDB table, banyak LockID berbeda
#    Cocok untuk: organisasi kecil-sedang (< 50 state files)
#    LockID: "bucket-name/path/to/terraform.tfstate"

# 2. Per-environment lock table
#    DynamoDB table terpisah per environment
#    terraform-lock-production, terraform-lock-staging
#    Cocok untuk: isolasi ketat antar environment
#    Memisahkan IAM permission per table

# 3. Per-team lock table
#    Setiap tim punya lock table sendiri
#    Tim infrastruktur: terraform-lock-infra
#    Tim aplikasi: terraform-lock-apps
#    Cocok untuk: organisasi besar dengan banyak tim

# REKOMENDASI: Mulai dengan pattern 1 (shared), pisahkan
# hanya jika ada kebutuhan IAM isolation yang spesifik