Interface Design #

# variables.tf — good design

# REQUIRED: Values unique per deployment, can't be defaulted
variable "name" {
  description = "Unique name for the resource — used as a prefix on all resources created by this module"
  type        = string
  # No default — every caller must decide this themselves
}

variable "vpc_id" {
  description = "ID of the VPC where resources will be placed"
  type        = string
  # No default — depends on the caller's infrastructure
}

# OPTIONAL: Values with a sensible "industry standard"
variable "instance_type" {
  description = "EC2 instance type for the web server"
  type        = string
  default     = "t3.micro"
  # t3.micro is a sensible choice for light workloads
}

variable "enable_deletion_protection" {
  description = "Enable deletion protection on RDS — should be true in production"
  type        = bool
  default     = true
  # Default true — better protected than not
}

variable "backup_retention_days" {
  description = "Number of days RDS backups are retained"
  type        = number
  default     = 7
  # 7 days is a common standard
}

# ANTI-PATTERN: Over-parameterized — too many detail variables
variable "subnet_cidr_bits"              { type = number }
variable "subnet_newbits"                { type = number }
variable "subnet_netnum_offset"          { type = number }
variable "nat_gateway_eip_allocation_id" { type = string }
variable "route_table_propagation_vgws"  { type = list(string) }
variable "dhcp_options_domain_name"      { type = string }
variable "dhcp_options_domain_name_servers" { type = list(string) }
# 50+ variables for things that actually have good defaults

# CORRECT: Opinionated defaults, expose only what's truly needed
variable "cidr_block" {
  type = string
  # One variable for the CIDR — the module calculates its own subnets
}

variable "az_count" {
  type    = number
  default = 2
  # The module can calculate subnet CIDRs internally
}

# If there's a rare override need, use an optional object:
variable "advanced_config" {
  description = "Advanced configuration — only use if the defaults don't fit"
  type = object({
    enable_nat_per_az          = optional(bool, false)
    dhcp_domain_name_servers   = optional(list(string), ["AmazonProvidedDNS"])
  })
  default = {}
}

# ANTI-PATTERN: Duplicating all RDS arguments as module variables
variable "db_engine"                    { type = string }
variable "db_engine_version"            { type = string }
variable "db_instance_class"            { type = string }
variable "db_allocated_storage"         { type = number }
variable "db_max_allocated_storage"     { type = number }
variable "db_storage_type"              { type = string }
variable "db_storage_encrypted"         { type = bool }
variable "db_kms_key_id"               { type = string }
variable "db_username"                  { type = string }
variable "db_port"                      { type = number }
# ... 30 more variables

# CORRECT: Opinionated defaults + an escape hatch for advanced overrides
variable "instance_class" {
  type    = string
  default = "db.t3.medium"
}

variable "allocated_storage" {
  type    = number
  default = 100
}

# Escape hatch: an object for uncommon overrides
variable "db_overrides" {
  description = "RDS configuration overrides not covered by the main variables. See the aws_db_instance documentation for available fields."
  type        = any
  default     = {}
}

resource "aws_db_instance" "this" {
  instance_class    = var.instance_class
  allocated_storage = var.allocated_storage

  # Merge overrides into the base configuration
  # (only if using dynamic blocks or a provider that supports it)
}

# Recommended pattern for tags
variable "tags" {
  description = "Map of tags applied to all resources created by this module"
  type        = map(string)
  default     = {}
}

# Inside the module, merge caller tags with the module's required tags
locals {
  common_tags = merge(
    var.tags,
    {
      # Tags that always exist, can't be overridden by callers
      ManagedBy = "terraform"
      Module    = "vpc"
    }
  )
}

resource "aws_vpc" "this" {
  cidr_block = var.cidr_block
  tags       = merge(local.common_tags, { Name = "${var.name}-vpc" })
}

resource "aws_subnet" "public" {
  count = var.az_count
  # ...
  tags = merge(local.common_tags, {
    Name = "${var.name}-public-${count.index + 1}"
    Tier = "public"
  })
}

# outputs.tf — comprehensive output design

# Output IDs for all main resources
output "vpc_id" {
  value       = aws_vpc.this.id
  description = "ID of the created VPC"
}

# Output the ARN if the resource has one
output "vpc_arn" {
  value       = aws_vpc.this.arn
  description = "VPC ARN"
}

# List outputs for resources created multiple times
output "public_subnet_ids" {
  value       = aws_subnet.public[*].id
  description = "List of public subnet IDs, ordered by AZ"
}

# Object outputs for easy multi-attribute access
output "nat_gateways" {
  description = "NAT Gateway information per AZ"
  value = {
    for idx, eip in aws_eip.nat : idx => {
      id        = aws_nat_gateway.this[idx].id
      public_ip = eip.public_ip
    }
  }
}

# ANTI-PATTERN: Outputs exposing internal implementation details
# that callers don't need
output "route_table_association_ids" {
  value = aws_route_table_association.public[*].id
  # Callers almost never need this — don't expose it if not necessary
}

# GOOD: Documented interface contract
# modules/networking/README.md
#
# ## Input Interface
# | Variable | Type | Required | Default | Description |
# |----------|------|----------|---------|-------------|
# | vpc_cidr | string | yes | - | VPC CIDR block |
# | azs | list(string) | yes | - | Availability zones |
# | environment | string | yes | - | Environment name |
#
# ## Output Interface  
# | Output | Type | Description |
# |--------|------|-------------|
# | vpc_id | string | VPC ID |
# | subnet_ids | list(string) | Private subnet IDs |
# | nat_gateway_ips | list(string) | NAT gateway public IPs |

# Interface consistency pattern
# All networking modules must output:
# - vpc_id
# - subnet_ids (private)
# - subnet_ids (public)

# All compute modules must input:
# - subnet_ids
# - security_group_ids
# - instance_type

# Generate interface documentation
terraform-docs markdown table ./modules/networking

# Validate interface compliance
# scripts/validate-interface.sh
#!/bin/bash
MODULE=$1
REQUIRED_OUTPUTS="vpc_id subnet_ids"
for output in $REQUIRED_OUTPUTS; do
  if ! grep -q "output \"$output\"" "$MODULE/outputs.tf"; then
    echo "MISSING: $output in $MODULE"
    exit 1
  fi
done

# When a module interface changes, bump the MAJOR version
# v1.0.0: variable "name" = string
# v2.0.0: variable "name" = object({first = string, last = string})

# Backward compatibility pattern:
# Add a new optional variable (MINOR bump)
# DON'T remove or rename variables (MAJOR bump)

# v1.1.0: add an optional variable
variable "tags" {
  description = "Resource tags"
  type        = map(string)
  default     = {}
}

# Interface validation
# Make sure all consumer modules are compatible
terraform plan -target=module.consumer 2>&1 | grep "incompatible"
# If there's an error, update the consumer module version

# Bulk version update
find . -name "*.tf" -exec sed -i 's|module-version/1.0|module-version/2.0|g' {} \;