Output Contract #

# PRINSIP 1: Nama output yang deskriptif dan konsisten

# ANTI-PATTERN: Nama yang ambigu
output "id" {
  value = aws_vpc.main.id  # ID apa? VPC? Subnet? Instance?
}

output "ip" {
  value = aws_instance.web.public_ip  # IP publik atau privat?
}

# BENAR: Nama yang eksplisit tentang resource dan atribut
output "vpc_id" {
  value = aws_vpc.main.id
}

output "web_instance_public_ip" {
  value = aws_instance.web.public_ip
}

# PRINSIP 2: description yang informatif — menjelaskan UNTUK APA output ini dipakai

# ANTI-PATTERN: Description yang mengulang nama
output "vpc_id" {
  description = "The VPC ID"  # ✗ Tidak menambah informasi
  value       = aws_vpc.main.id
}

# BENAR: Description yang menjelaskan konteks penggunaan
output "vpc_id" {
  description = "ID VPC utama — digunakan oleh modul compute dan database untuk menempatkan resource di network yang benar."
  value       = aws_vpc.main.id
}

# PRINSIP 3: Konsistensi tipe — jangan campur tipe untuk output yang serupa

# ANTI-PATTERN: Tipe output yang tidak konsisten
output "public_subnet_id" {
  value = aws_subnet.public[0].id  # String — hanya satu subnet
}

output "private_subnet_ids" {
  value = aws_subnet.private[*].id  # List — bisa banyak subnet
}
# Pemangil harus tahu kapan pakai string dan kapan pakai list

# BENAR: Konsisten menggunakan list meskipun hanya satu element
output "public_subnet_ids" {
  value = aws_subnet.public[*].id  # Selalu list
}

output "private_subnet_ids" {
  value = aws_subnet.private[*].id  # Selalu list
}

# ANTI-PATTERN: Output yang terlalu granular
output "lb_dns_name" {
  value = aws_lb.main.dns_name
}
output "lb_arn" {
  value = aws_lb.main.arn
}
output "lb_zone_id" {
  value = aws_lb.main.zone_id
}
output "lb_security_group_id" {
  value = aws_security_group.lb.id
}
# 4 output terpisah untuk satu resource — rentan breaking change jika ada yang ditambah/hapus

# BENAR: Output terstruktur dalam satu object
output "load_balancer" {
  description = "Informasi load balancer — DNS, ARN, zone ID, dan security group"
  value = {
    dns_name         = aws_lb.main.dns_name
    arn              = aws_lb.main.arn
    zone_id          = aws_lb.main.zone_id
    security_group_id = aws_security_group.lb.id
  }
}
# Lebih mudah diperluas — tambah field baru tanpa breaking existing usage
# module.app.load_balancer.dns_name → tetap valid

# AMAN: Menambah output baru
# Pemangil lama tidak terpengaruh, pemangil baru bisa memanfaatkan output baru

# Versi 1.0 module:
output "vpc_id" { value = aws_vpc.main.id }
output "private_subnet_ids" { value = aws_subnet.private[*].id }

# Versi 1.1 module (backward compatible — hanya tambah):
output "vpc_id" { value = aws_vpc.main.id }              # Tetap ada
output "private_subnet_ids" { value = aws_subnet.private[*].id }  # Tetap ada
output "public_subnet_ids" { value = aws_subnet.public[*].id }    # BARU — aman
output "nat_gateway_ips" { value = aws_eip.nat[*].public_ip }     # BARU — aman

# BERBAHAYA: Mengubah nama atau tipe output yang sudah ada
# Semua pemangil yang menggunakan output ini akan error

# JANGAN lakukan ini tanpa major version bump:
# Sebelum: output "subnet_ids" { value = ... }
# Sesudah: output "private_subnet_ids" { value = ... }  ← rename = breaking change

# Jika harus rename, beri masa transisi:
output "subnet_ids" {
  value       = aws_subnet.private[*].id
  description = "DEPRECATED: Gunakan private_subnet_ids. Akan dihapus di v3.0."
}

output "private_subnet_ids" {
  value       = aws_subnet.private[*].id
  description = "List ID private subnet"
}

# Output yang dirancang untuk dikonsumsi oleh sistem eksternal
# sebaiknya dalam format yang mudah diparse

output "connection_strings" {
  description = "Connection string untuk berbagai komponen — digunakan oleh deployment pipeline"
  sensitive   = true  # Mengandung kredensial
  value = {
    database = "postgresql://${aws_db_instance.main.username}@${aws_db_instance.main.endpoint}/${aws_db_instance.main.db_name}"
    redis    = "redis://${aws_elasticache_cluster.main.cache_nodes[0].address}:${aws_elasticache_cluster.main.cache_nodes[0].port}"
  }
}

output "kubernetes_config" {
  description = "Konfigurasi untuk setup kubectl — digunakan oleh CI/CD pipeline"
  value = {
    cluster_name     = aws_eks_cluster.main.name
    cluster_endpoint = aws_eks_cluster.main.endpoint
    cluster_region   = var.aws_region
  }
}

# Konsumsi output dari CI/CD pipeline
DB_ENDPOINT=$(terraform output -raw database_endpoint)
CLUSTER_NAME=$(terraform output -json kubernetes_config | jq -r '.cluster_name')

aws eks update-kubeconfig \
  --name "$CLUSTER_NAME" \
  --region "$(terraform output -json kubernetes_config | jq -r '.cluster_region')"

# VERSI 1.0: Output awal
output "db_endpoint" {
  description = "Database endpoint"
  value       = aws_db_instance.main.endpoint
}

# VERSI 1.5: Tambah output baru, tandai lama deprecated
output "db_endpoint" {
  description = "DEPRECATED: Gunakan database.primary_endpoint"
  value       = aws_db_instance.main.endpoint
}

output "database" {
  description = "Database connection details"
  value = {
    primary_endpoint = aws_db_instance.main.endpoint
    port             = aws_db_instance.main.port
    engine           = aws_db_instance.main.engine
  }
}

# VERSI 2.0: Hapus output lama
# output "db_endpoint" { ... }  # DIHAPUS
# Consumer HARUS migrasi ke output "database"

# Standar dokumentasi output:

# 1. Selalu berikan description
output "vpc_id" {
  description = "ID dari VPC yang dibuat oleh module ini"
  value       = aws_vpc.main.id
}

# 2. Deskripsikan format untuk output kompleks
output "database_endpoint" {
  description = "Endpoint database. Format: host:port"
  value       = "${aws_db_instance.main.address}:${aws_db_instance.main.port}"
}

# 3. Tandai sensitive jika mengandung rahasia
output "admin_password" {
  description = "Password admin database. HARUS disimpan di secret manager."
  value       = random_password.admin.result
  sensitive   = true
}

# 4. Gunakan object output untuk grouping
output "networking" {
  description = "Semua informasi networking dari module"
  value = {
    vpc_id              = aws_vpc.main.id
    public_subnet_ids   = aws_subnet.public[*].id
    private_subnet_ids  = aws_subnet.private[*].id
    nat_gateway_ips     = aws_nat_gateway.main[*].public_ip
  }
}

# Generate documentation dari output
terraform output -json | jq 'to_entries[] | {
  name: .key,
  type: .value.type,
  sensitive: .value.sensitive
}'


---

## Output Migration Strategy

```bash
# Saat mengubah output contract, ikuti langkah ini:

# 1. Tambah output baru (backward-compatible)
# 2. Tandai output lama sebagai deprecated (di description)
# 3. Beri waktu untuk consumer migrasi (1-2 sprint)
# 4. Monitor: siapa yang masih pakai output lama?
# 5. Hapus output lama di major version berikutnya