Output Contract #

# PRINCIPLE 1: Descriptive, consistent output names

# ANTI-PATTERN: Ambiguous names
output "id" {
  value = aws_vpc.main.id  # ID of what? VPC? Subnet? Instance?
}

output "ip" {
  value = aws_instance.web.public_ip  # Public or private IP?
}

# CORRECT: Names explicit about the resource and attribute
output "vpc_id" {
  value = aws_vpc.main.id
}

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

# PRINCIPLE 2: Informative descriptions — explain WHAT the output is used FOR

# ANTI-PATTERN: A description that repeats the name
output "vpc_id" {
  description = "The VPC ID"  # ✗ Adds no information
  value       = aws_vpc.main.id
}

# CORRECT: A description that explains the usage context
output "vpc_id" {
  description = "ID of the main VPC — used by the compute and database modules to place resources in the right network."
  value       = aws_vpc.main.id
}

# PRINCIPLE 3: Type consistency — don't mix types for similar outputs

# ANTI-PATTERN: Inconsistent output types
output "public_subnet_id" {
  value = aws_subnet.public[0].id  # String — only one subnet
}

output "private_subnet_ids" {
  value = aws_subnet.private[*].id  # List — can be many subnets
}
# Callers must know when to use a string and when to use a list

# CORRECT: Consistently use a list even for a single element
output "public_subnet_ids" {
  value = aws_subnet.public[*].id  # Always a list
}

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

# ANTI-PATTERN: Overly granular outputs
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 separate outputs for one resource — vulnerable to breaking changes if any is added/removed

# CORRECT: Structured output in a single object
output "load_balancer" {
  description = "Load balancer information — DNS, ARN, zone ID, and 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
  }
}
# Easier to extend — add new fields without breaking existing usage
# module.app.load_balancer.dns_name → still valid

# SAFE: Adding a new output
# Existing callers are unaffected, new callers can use the new output

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

# Module version 1.1 (backward compatible — only additions):
output "vpc_id" { value = aws_vpc.main.id }              # Still present
output "private_subnet_ids" { value = aws_subnet.private[*].id }  # Still present
output "public_subnet_ids" { value = aws_subnet.public[*].id }    # NEW — safe
output "nat_gateway_ips" { value = aws_eip.nat[*].public_ip }     # NEW — safe

# DANGEROUS: Renaming or changing the type of an existing output
# Every caller using this output will error

# DON'T do this without a major version bump:
# Before: output "subnet_ids" { value = ... }
# After: output "private_subnet_ids" { value = ... }  ← rename = breaking change

# If you must rename, provide a transition period:
output "subnet_ids" {
  value       = aws_subnet.private[*].id
  description = "DEPRECATED: Use private_subnet_ids. Will be removed in v3.0."
}

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

# Outputs designed for consumption by external systems
# should be in an easily parsable format

output "connection_strings" {
  description = "Connection strings for various components — used by the deployment pipeline"
  sensitive   = true  # Contains credentials
  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 = "Configuration for kubectl setup — used by the CI/CD pipeline"
  value = {
    cluster_name     = aws_eks_cluster.main.name
    cluster_endpoint = aws_eks_cluster.main.endpoint
    cluster_region   = var.aws_region
  }
}

# Consuming outputs from a 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')"

# VERSION 1.0: Initial outputs
output "db_endpoint" {
  description = "Database endpoint"
  value       = aws_db_instance.main.endpoint
}

# VERSION 1.5: Add a new output, mark the old one deprecated
output "db_endpoint" {
  description = "DEPRECATED: Use 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
  }
}

# VERSION 2.0: Remove the old output
# output "db_endpoint" { ... }  # REMOVED
# Consumers MUST migrate to the "database" output

# Output documentation standards:

# 1. Always provide a description
output "vpc_id" {
  description = "ID of the VPC created by this module"
  value       = aws_vpc.main.id
}

# 2. Describe the format for complex outputs
output "database_endpoint" {
  description = "Database endpoint. Format: host:port"
  value       = "${aws_db_instance.main.address}:${aws_db_instance.main.port}"
}

# 3. Mark sensitive if it contains secrets
output "admin_password" {
  description = "Database admin password. MUST be stored in a secret manager."
  value       = random_password.admin.result
  sensitive   = true
}

# 4. Use object outputs for grouping
output "networking" {
  description = "All networking information from the 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 from outputs
terraform output -json | jq 'to_entries[] | {
  name: .key,
  type: .value.type,
  sensitive: .value.sensitive
}'

# When changing an output contract, follow these steps:

# 1. Add the new output (backward-compatible)
# 2. Mark the old output as deprecated (in the description)
# 3. Give consumers time to migrate (1-2 sprints)
# 4. Monitor: who is still using the old output?
# 5. Remove the old output in the next major version