Modules: Building Reusable Infrastructure Components

How I learned to stop copying code and start building composable infrastructure

---

Table of Contents

1. Introduction: The Copy-Paste Nightmare

2. What Are Terraform Modules?

3. Why Modules Matter

4. Module Basics

5. Creating Your First Module

6. Module Inputs (Variables)

7. Module Outputs

8. Calling Modules

9. Module Sources

10. Module Composition

11. Terraform Registry

12. Module Best Practices

13. Real-World Example: Multi-Service Blog Platform

14. Module Versioning

15. Testing Modules

16. Publishing Your Module

17. Common Module Patterns

18. What I Learned About Module Design

19. Next Steps

---

Introduction: The Copy-Paste Nightmare

Three months into my Terraform journey, I had a problem. A big one.

I was managing infrastructure for five different microservices. Each service needed:

• A configuration file

• A secrets file

• A deployment manifest

• A monitoring configuration

So I did what any reasonable person would do: I copied the Terraform code five times and changed the service names.

It worked... until I needed to update the configuration template. Then I had to update it in five places. And of course, I forgot to update one of them. Production broke at 2 AM.

That's when a senior engineer saw my code during review.

"Why are you copying this?" they asked.

"Because each service needs its own configuration," I said defensively.

"No," they said. "You need modules. You're doing the equivalent of copying functions instead of calling them."

They refactored my 500 lines of duplicated code into a single 50-line module that could be called five times. Each service got its configuration with three lines of code.

My mind was blown. 🤯

This article is everything I learned about Terraform modules: the building blocks that transform infrastructure code from repetitive scripts into reusable, composable, maintainable components.

---

What Are Terraform Modules?

A module is a container for multiple resources that are used together. It's essentially a package of Terraform configuration.

The Simplest Module

Every Terraform configuration is actually a module! Even this:

# main.tf
resource "local_file" "hello" {
  filename = "hello.txt"
  content  = "Hello!"
}

This is called the root module - the working directory where you run terraform apply.

Calling a Module

Modules become powerful when you call them:

# Root module
module "service_config" {
  source = "./modules/service"
  
  service_name = "web"
  port         = 8080
}

This calls a module stored in ./modules/service and passes it inputs.

Module Structure

project/
├── main.tf              # Root module - calls child modules
├── variables.tf         # Root module variables
├── outputs.tf           # Root module outputs
└── modules/
    └── service/         # Child module
        ├── main.tf      # Module resources
        ├── variables.tf # Module inputs
        └── outputs.tf   # Module outputs

---

Why Modules Matter

1. DRY (Don't Repeat Yourself)

Without modules:

# Service 1
resource "local_file" "web_config" {
  filename = "web-config.yaml"
  content  = "..."
}

# Service 2
resource "local_file" "api_config" {
  filename = "api-config.yaml"
  content  = "..."
}

# Service 3
resource "local_file" "worker_config" {
  filename = "worker-config.yaml"
  content  = "..."
}
# ... 500 lines of duplication

With modules:

module "web" {
  source = "./modules/service"
  name   = "web"
}

module "api" {
  source = "./modules/service"
  name   = "api"
}

module "worker" {
  source = "./modules/service"
  name   = "worker"
}
# 15 lines instead of 500!

2. Abstraction

Modules hide complexity:

# Complex infrastructure reduced to simple interface
module "blog_platform" {
  source = "./modules/blog-platform"
  
  environment = "production"
  domain      = "blog.example.com"
}

# Behind the scenes: web servers, databases, caching, monitoring, etc.

3. Reusability

Write once, use everywhere:

# Same module, different configurations
module "dev_blog" {
  source      = "./modules/blog"
  environment = "dev"
  replicas    = 1
}

module "prod_blog" {
  source      = "./modules/blog"
  environment = "production"
  replicas    = 5
}

4. Testing

Modules can be tested independently:

# Test the module in isolation
module "test" {
  source = "./modules/service"
  name   = "test-service"
}

5. Versioning

Modules can be versioned:

module "service" {
  source  = "app.terraform.io/myorg/service/local"
  version = "1.2.0"
  
  name = "web"
}

---

Module Basics

Module Components

Every well-designed module has three files:

modules/service/
├── main.tf       # Resources and data sources
├── variables.tf  # Input variables
└── outputs.tf    # Output values

Optional files:

modules/service/
├── main.tf
├── variables.tf
├── outputs.tf
├── README.md      # Documentation
├── versions.tf    # Provider requirements
└── examples/      # Usage examples

Module Communication Flow

Flow:

1. Root module passes inputs to child module

2. Child module creates resources

3. Resources have attributes

4. Module exposes attributes as outputs

5. Root module can use those outputs

---

Creating Your First Module

Let's build a simple module step by step.

Project Structure

first-module/
├── main.tf              # Root module
├── modules/
│   └── greeting/        # Our module
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf

Step 1: Create Module Directory

mkdir -p modules/greeting

Step 2: Define Module Variables

modules/greeting/variables.tf:

variable "name" {
  type        = string
  description = "Name to greet"
}

variable "greeting_type" {
  type        = string
  default     = "hello"
  description = "Type of greeting: hello, goodbye, or welcome"
  
  validation {
    condition     = contains(["hello", "goodbye", "welcome"], var.greeting_type)
    error_message = "Must be hello, goodbye, or welcome."
  }
}

variable "enthusiastic" {
  type        = bool
  default     = false
  description = "Add exclamation marks"
}

Step 3: Create Module Resources

modules/greeting/main.tf:

locals {
  greetings = {
    hello   = "Hello"
    goodbye = "Goodbye"
    welcome = "Welcome"
  }
  
  greeting = local.greetings[var.greeting_type]
  
  punctuation = var.enthusiastic ? "!!!" : "."
  
  message = "${local.greeting}, ${var.name}${local.punctuation}"
}

resource "local_file" "greeting" {
  filename = "greeting-${var.name}.txt"
  content  = local.message
}

Step 4: Define Module Outputs

modules/greeting/outputs.tf:

output "filename" {
  value       = local_file.greeting.filename
  description = "Path to greeting file"
}

output "message" {
  value       = local.message
  description = "The greeting message"
}

output "file_id" {
  value       = local_file.greeting.id
  description = "Terraform resource ID"
}

Step 5: Use the Module

main.tf:

terraform {
  required_version = ">= 1.0"
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.4"
    }
  }
}

# Call module multiple times
module "hello_john" {
  source = "./modules/greeting"
  
  name         = "John"
  greeting_type = "hello"
  enthusiastic = false
}

module "welcome_sarah" {
  source = "./modules/greeting"
  
  name         = "Sarah"
  greeting_type = "welcome"
  enthusiastic = true
}

module "goodbye_alex" {
  source = "./modules/greeting"
  
  name         = "Alex"
  greeting_type = "goodbye"
  enthusiastic = false
}

# Use module outputs
output "all_greetings" {
  value = {
    john  = module.hello_john.message
    sarah = module.welcome_sarah.message
    alex  = module.goodbye_alex.message
  }
}

Step 6: Apply

terraform init
terraform apply

Output:

all_greetings = {
  alex = "Goodbye, Alex."
  john = "Hello, John."
  sarah = "Welcome, Sarah!!!"
}

Files created:

• greeting-John.txt → "Hello, John."

• greeting-Sarah.txt → "Welcome, Sarah!!!"

• greeting-Alex.txt → "Goodbye, Alex."

---

Module Inputs (Variables)

Module inputs define the interface to your module.

Input Best Practices

1. Clear descriptions:

variable "port" {
  type        = number
  description = "Port number for the service (1024-65535)"
  
  validation {
    condition     = var.port >= 1024 && var.port <= 65535
    error_message = "Port must be between 1024 and 65535."
  }
}

2. Sensible defaults:

variable "environment" {
  type        = string
  default     = "dev"
  description = "Deployment environment"
}

variable "enable_monitoring" {
  type        = bool
  default     = true
  description = "Enable monitoring and alerting"
}

3. Complex types for structured data:

variable "service_config" {
  type = object({
    name     = string
    port     = number
    replicas = number
    features = list(string)
  })
  
  description = "Complete service configuration"
}

4. Validation:

variable "tier" {
  type        = string
  description = "Service tier"
  
  validation {
    condition     = contains(["basic", "professional", "enterprise"], var.tier)
    error_message = "Tier must be basic, professional, or enterprise."
  }
}

---

Module Outputs

Outputs expose module results to the calling module.

Output Patterns

1. Resource attributes:

output "file_path" {
  value       = local_file.config.filename
  description = "Path to generated config file"
}

output "file_content" {
  value       = local_file.config.content
  description = "Content of config file"
}

2. Computed values:

output "service_url" {
  value       = "https://${var.service_name}.${var.domain}:${var.port}"
  description = "Full service URL"
}

3. Sensitive outputs:

output "password" {
  value       = random_password.db.result
  sensitive   = true
  description = "Database password"
}

4. Structured outputs:

output "service_info" {
  value = {
    name     = var.service_name
    port     = var.port
    endpoint = "https://${var.service_name}.${var.domain}"
    replicas = var.replicas
    status   = "configured"
  }
  description = "Complete service information"
}

---

Calling Modules

Module Block Syntax

module "label" {
  # Required: source
  source = "./modules/service"
  
  # Optional: version (for registry modules)
  version = "1.2.0"
  
  # Module inputs
  service_name = "web"
  port         = 8080
  
  # Meta-arguments
  count    = 3
  for_each = var.services
  depends_on = [module.networking]
  providers = {
    local = local.alternate
  }
}

Accessing Module Outputs

# Single module
output "service_url" {
  value = module.web.service_url
}

# Module with count
output "all_urls" {
  value = module.services[*].service_url
}

# Module with for_each
output "service_urls" {
  value = {
    for name, service in module.services :
    name => service.service_url
  }
}

Module Dependencies

module "networking" {
  source = "./modules/network"
}

module "services" {
  source = "./modules/service"
  
  # Explicit dependency
  depends_on = [module.networking]
  
  # Or implicit via output reference
  network_id = module.networking.network_id
}

---

Module Sources

Terraform supports multiple module sources:

1. Local Paths

module "service" {
  source = "./modules/service"          # Relative path
  # source = "/absolute/path/to/module" # Absolute path
}

2. Terraform Registry

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.0.0"
}

3. GitHub

# HTTPS
module "service" {
  source = "github.com/username/repo//modules/service"
}

# SSH
module "service" {
  source = "[email protected]:username/repo.git//modules/service"
}

# Specific branch/tag
module "service" {
  source = "github.com/username/repo//modules/service?ref=v1.2.0"
}

4. Generic Git

module "service" {
  source = "git::https://example.com/repo.git//modules/service"
}

5. HTTP URLs

module "service" {
  source = "https://example.com/modules/service.zip"
}

6. S3 Buckets

module "service" {
  source = "s3::https://s3.amazonaws.com/bucket/modules/service.zip"
}

---

Module Composition

Modules can call other modules, creating a hierarchy.

Simple Composition

root/
├── main.tf
└── modules/
    ├── application/
    │   ├── main.tf
    │   └── modules/
    │       ├── web/
    │       └── api/
    └── database/

modules/application/main.tf:

module "web" {
  source = "./modules/web"
  
  name = "${var.app_name}-web"
  port = 8080
}

module "api" {
  source = "./modules/api"
  
  name = "${var.app_name}-api"
  port = 8081
}

Root main.tf:

module "blog_app" {
  source = "./modules/application"
  
  app_name = "blog"
}

Module Communication

Modules can pass outputs to each other:

module "network" {
  source = "./modules/network"
  
  cidr_block = "10.0.0.0/16"
}

module "application" {
  source = "./modules/application"
  
  # Use network module output
  network_id = module.network.id
  subnet_ids = module.network.subnet_ids
}

module "database" {
  source = "./modules/database"
  
  # Use outputs from both modules
  network_id     = module.network.id
  allowed_cidrs  = module.application.security_group_cidrs
}

Module Composition Diagram

---

Terraform Registry

The Terraform Registry is a repository of public modules.

Using Registry Modules

module "example" {
  source  = "namespace/module-name/provider"
  version = "1.0.0"
  
  # Module inputs
}

Example - AWS VPC module:

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.0.0"
  
  name = "my-vpc"
  cidr = "10.0.0.0/16"
  
  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
  
  enable_nat_gateway = true
  enable_vpn_gateway = true
  
  tags = {
    Environment = "production"
  }
}

Finding Modules

Search the registry:

• Browse by provider: AWS, Azure, GCP

• Browse by category: Network, Compute, Security

• Search by keyword: "vpc", "kubernetes", "monitoring"

Quality indicators:

• ✅ Verified modules (HashiCorp verified)

• ⭐ Star count (community endorsement)

• 📝 Documentation quality

• 🔄 Recent updates

• 📊 Download count

Module Versioning

Semantic versioning (SemVer):

MAJOR.MINOR.PATCH
  |     |     |
  |     |     +-- Bug fixes
  |     +-------- New features (backward compatible)
  +-------------- Breaking changes

Version constraints:

# Exact version
version = "1.2.3"

# Greater than or equal
version = ">= 1.0.0"

# Pessimistic constraint (recommended)
version = "~> 1.2"    # Allows 1.2.x, but not 1.3.0
version = "~> 1.2.0"  # Allows 1.2.x only

# Range
version = ">= 1.0.0, < 2.0.0"

---

Module Best Practices

1. Single Responsibility

Each module should do one thing well:

Good:

# Focused modules
module "network" { }
module "compute" { }
module "database" { }

Bad:

# God module that does everything
module "entire_infrastructure" { }

2. Clear Interfaces

Define clear inputs and outputs:

# variables.tf - Well documented
variable "service_name" {
  type        = string
  description = "Name of the service (alphanumeric, max 32 chars)"
  
  validation {
    condition     = can(regex("^[a-z0-9]{1,32}$", var.service_name))
    error_message = "Service name must be alphanumeric and max 32 characters."
  }
}

# outputs.tf - Complete information
output "service" {
  value = {
    name     = var.service_name
    endpoint = local.endpoint
    status   = "configured"
    files    = local_file.configs[*].filename
  }
  description = "Complete service configuration details"
}

3. Sensible Defaults

Provide defaults for non-critical inputs:

variable "replicas" {
  type        = number
  default     = 1
  description = "Number of service replicas"
}

variable "monitoring_enabled" {
  type        = bool
  default     = true
  description = "Enable monitoring"
}

4. Avoid Hardcoding

Use variables instead of hardcoded values:

Bad:

resource "local_file" "config" {
  filename = "prod-config.yaml"  # Hardcoded!
}

Good:

resource "local_file" "config" {
  filename = "${var.environment}-config.yaml"
}

5. Use Locals for Computed Values

locals {
  # Compute once, use many times
  full_name = "${var.project}-${var.environment}-${var.service}"
  
  tags = merge(
    var.common_tags,
    {
      Service = var.service
      Module  = "service-config"
    }
  )
}

resource "local_file" "config" {
  filename = "${local.full_name}-config.yaml"
  # ...
}

6. Document Your Module

README.md:

# Service Configuration Module

Generates service configuration files.

## Usage

```hcl
module "web_service" {
  source = "./modules/service"
  
  service_name = "web"
  port         = 8080
  environment  = "production"
}

Inputs

Name	Type	Default	Description
service_name	string	-	Service name (required)
port	number	-	Service port (required)
environment	string	"dev"	Deployment environment

Outputs

Name	Description
config_file	Path to configuration file
service_url	Full service URL

### 7. Version Your Modules

Use Git tags for versioning:

```bash
git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0

Then reference specific versions:

module "service" {
  source = "github.com/myorg/modules//service?ref=v1.0.0"
}

---

Real-World Example: Multi-Service Blog Platform

Let's build a complete blog platform using modules.

Project Structure

blog-platform/
├── main.tf
├── variables.tf
├── outputs.tf
├── environments/
│   ├── dev.tfvars
│   ├── staging.tfvars
│   └── production.tfvars
└── modules/
    ├── service/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    ├── monitoring/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── deployment/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

Service Module

modules/service/variables.tf:

variable "name" {
  type        = string
  description = "Service name"
}

variable "environment" {
  type        = string
  description = "Deployment environment"
}

variable "config" {
  type = object({
    port     = number
    replicas = number
    features = list(string)
    tier     = string
  })
  description = "Service configuration"
}

variable "enable_monitoring" {
  type        = bool
  default     = true
  description = "Enable monitoring"
}

variable "common_tags" {
  type        = map(string)
  default     = {}
  description = "Common resource tags"
}

modules/service/main.tf:

locals {
  full_name = "${var.name}-${var.environment}"
  
  tier_multipliers = {
    basic        = 1
    professional = 2
    enterprise   = 5
  }
  
  scaled_replicas = var.config.replicas * local.tier_multipliers[var.config.tier]
  
  tags = merge(
    var.common_tags,
    {
      Service     = var.name
      Environment = var.environment
      Module      = "service"
    }
  )
}

# Service configuration
resource "local_file" "config" {
  filename = "${path.root}/generated/${var.environment}/config/${var.name}.yaml"
  
  content = yamlencode({
    service = {
      name        = local.full_name
      port        = var.config.port
      replicas    = local.scaled_replicas
      features    = var.config.features
      tier        = var.config.tier
      monitoring  = var.enable_monitoring
    }
    
    deployment = {
      strategy = var.environment == "production" ? "rolling" : "recreate"
      timeout  = var.environment == "production" ? 600 : 300
    }
    
    tags = local.tags
  })
  
  file_permission = "0644"
}

# Service secrets
resource "random_password" "secret" {
  length  = 32
  special = true
}

resource "local_file" "secret" {
  filename        = "${path.root}/generated/${var.environment}/secrets/${var.name}.txt"
  content         = random_password.secret.result
  file_permission = "0600"
}

# Health check script
resource "local_file" "healthcheck" {
  filename = "${path.root}/generated/${var.environment}/scripts/${var.name}-health.sh"
  
  content = <<-EOT
    #!/bin/bash
    # Health check for ${local.full_name}
    curl -f http://localhost:${var.config.port}/health || exit 1
  EOT
  
  file_permission = "0755"
}

modules/service/outputs.tf:

output "service_name" {
  value       = local.full_name
  description = "Full service name"
}

output "config_file" {
  value       = local_file.config.filename
  description = "Service configuration file path"
}

output "port" {
  value       = var.config.port
  description = "Service port"
}

output "replicas" {
  value       = local.scaled_replicas
  description = "Actual replica count (after tier scaling)"
}

output "secret" {
  value       = random_password.secret.result
  sensitive   = true
  description = "Service secret"
}

output "info" {
  value = {
    name     = local.full_name
    port     = var.config.port
    replicas = local.scaled_replicas
    tier     = var.config.tier
    url      = "http://localhost:${var.config.port}"
    files = {
      config      = local_file.config.filename
      secret      = local_file.secret.filename
      healthcheck = local_file.healthcheck.filename
    }
  }
  description = "Complete service information"
}

Monitoring Module

modules/monitoring/variables.tf:

variable "environment" {
  type        = string
  description = "Environment name"
}

variable "services" {
  type = map(object({
    name     = string
    port     = number
    replicas = number
  }))
  description = "Services to monitor"
}

variable "alert_level" {
  type        = string
  default     = "standard"
  description = "Alert level: basic, standard, or advanced"
}

modules/monitoring/main.tf:

locals {
  alert_thresholds = {
    basic = {
      cpu_percent    = 90
      memory_percent = 90
      error_rate     = 10
    }
    standard = {
      cpu_percent    = 80
      memory_percent = 80
      error_rate     = 5
    }
    advanced = {
      cpu_percent    = 70
      memory_percent = 70
      error_rate     = 1
    }
  }
  
  thresholds = local.alert_thresholds[var.alert_level]
}

resource "local_file" "monitoring_config" {
  filename = "${path.root}/generated/${var.environment}/monitoring/config.yaml"
  
  content = yamlencode({
    monitoring = {
      environment = var.environment
      level       = var.alert_level
      
      services = {
        for name, service in var.services :
        name => {
          endpoint     = "http://localhost:${service.port}/metrics"
          replicas     = service.replicas
          health_check = "http://localhost:${service.port}/health"
        }
      }
      
      alerts = {
        cpu_threshold    = local.thresholds.cpu_percent
        memory_threshold = local.thresholds.memory_percent
        error_threshold  = local.thresholds.error_rate
      }
    }
  })
  
  file_permission = "0644"
}

resource "local_file" "prometheus_config" {
  filename = "${path.root}/generated/${var.environment}/monitoring/prometheus.yml"
  
  content = yamlencode({
    global = {
      scrape_interval = var.alert_level == "advanced" ? "15s" : "30s"
    }
    
    scrape_configs = [
      for name, service in var.services : {
        job_name = name
        static_configs = [
          {
            targets = ["localhost:${service.port}"]
            labels = {
              service     = name
              environment = var.environment
            }
          }
        ]
      }
    ]
  })
  
  file_permission = "0644"
}

modules/monitoring/outputs.tf:

output "config_file" {
  value       = local_file.monitoring_config.filename
  description = "Monitoring configuration file"
}

output "prometheus_config" {
  value       = local_file.prometheus_config.filename
  description = "Prometheus configuration file"
}

output "monitored_services" {
  value       = keys(var.services)
  description = "List of monitored services"
}

Deployment Module

modules/deployment/variables.tf:

variable "environment" {
  type        = string
  description = "Environment name"
}

variable "project" {
  type = object({
    name    = string
    version = string
  })
  description = "Project information"
}

variable "services" {
  type = map(object({
    name     = string
    port     = number
    replicas = number
    tier     = string
  }))
  description = "Services to deploy"
}

modules/deployment/main.tf:

resource "random_uuid" "deployment_id" {}

locals {
  deployment_timestamp = timestamp()
  deployment_date      = formatdate("YYYY-MM-DD", local.deployment_timestamp)
}

resource "local_file" "deployment_manifest" {
  filename = "${path.root}/generated/${var.environment}/deployment.yaml"
  
  content = yamlencode({
    deployment = {
      id          = random_uuid.deployment_id.result
      timestamp   = local.deployment_timestamp
      environment = var.environment
    }
    
    project = var.project
    
    services = var.services
  })
  
  file_permission = "0644"
}

resource "local_file" "docker_compose" {
  filename = "${path.root}/generated/${var.environment}/docker-compose.yml"
  
  content = yamlencode({
    version = "3.8"
    
    services = {
      for name, service in var.services :
      name => {
        image = "${var.project.name}/${name}:${var.project.version}"
        ports = ["${service.port}:${service.port}"]
        deploy = {
          replicas = service.replicas
        }
        environment = {
          SERVICE_NAME = service.name
          ENVIRONMENT  = var.environment
        }
        volumes = [
          "./config/${name}.yaml:/app/config.yaml:ro",
          "./secrets/${name}.txt:/app/secret.txt:ro"
        ]
      }
    }
  })
  
  file_permission = "0644"
}

resource "local_file" "readme" {
  filename = "${path.root}/generated/${var.environment}/README.md"
  
  content = <<-EOT
    # ${title(var.environment)} Deployment
    
    **Project**: ${var.project.name} v${var.project.version}  
    **Deployment ID**: ${random_uuid.deployment_id.result}  
    **Date**: ${local.deployment_date}
    
    ## Services
    
    ${join("\n", [
      for name, service in var.services :
      "- **${name}**: ${service.replicas} replicas on port ${service.port}"
    ])}
    
    ## Quick Start
    
    ```bash
    cd generated/${var.environment}
    docker-compose up -d
    ```
  EOT
  
  file_permission = "0644"
}

modules/deployment/outputs.tf:

output "deployment_id" {
  value       = random_uuid.deployment_id.result
  description = "Unique deployment identifier"
}

output "manifest_file" {
  value       = local_file.deployment_manifest.filename
  description = "Deployment manifest file"
}

output "docker_compose_file" {
  value       = local_file.docker_compose.filename
  description = "Docker Compose file"
}

Root Module

variables.tf:

variable "environment" {
  type        = string
  description = "Deployment environment"
}

variable "project" {
  type = object({
    name        = string
    version     = string
    team        = string
    cost_center = string
  })
  description = "Project metadata"
}

variable "services" {
  type = map(object({
    enabled  = bool
    port     = number
    replicas = number
    features = list(string)
  }))
  description = "Service definitions"
}

variable "tier" {
  type        = string
  description = "Service tier: basic, professional, enterprise"
}

variable "enable_monitoring" {
  type        = bool
  default     = true
  description = "Enable monitoring stack"
}

main.tf:

terraform {
  required_version = ">= 1.0"
  
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.4"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.5"
    }
  }
}

locals {
  # Common tags for all resources
  common_tags = {
    Project     = var.project.name
    Version     = var.project.version
    Environment = var.environment
    Team        = var.project.team
    CostCenter  = var.project.cost_center
    ManagedBy   = "Terraform"
  }
  
  # Filter enabled services
  enabled_services = {
    for name, config in var.services :
    name => config
    if config.enabled
  }
}

# Create services
module "services" {
  source   = "./modules/service"
  for_each = local.enabled_services
  
  name        = each.key
  environment = var.environment
  
  config = {
    port     = each.value.port
    replicas = each.value.replicas
    features = each.value.features
    tier     = var.tier
  }
  
  enable_monitoring = var.enable_monitoring
  common_tags       = local.common_tags
}

# Create monitoring stack
module "monitoring" {
  count = var.enable_monitoring ? 1 : 0
  
  source = "./modules/monitoring"
  
  environment = var.environment
  
  services = {
    for name, service in module.services :
    name => {
      name     = service.service_name
      port     = service.port
      replicas = service.replicas
    }
  }
  
  alert_level = var.environment == "production" ? "advanced" : "standard"
}

# Create deployment configuration
module "deployment" {
  source = "./modules/deployment"
  
  environment = var.environment
  project     = var.project
  
  services = {
    for name, service in module.services :
    name => {
      name     = service.service_name
      port     = service.port
      replicas = service.replicas
      tier     = var.tier
    }
  }
}

outputs.tf:

output "deployment_id" {
  value       = module.deployment.deployment_id
  description = "Unique deployment identifier"
}

output "services" {
  value = {
    for name, service in module.services :
    name => service.info
  }
  description = "All service information"
}

output "monitoring" {
  value = var.enable_monitoring ? {
    config     = module.monitoring[0].config_file
    prometheus = module.monitoring[0].prometheus_config
    services   = module.monitoring[0].monitored_services
  } : null
  description = "Monitoring configuration"
}

output "files" {
  value = {
    deployment     = module.deployment.manifest_file
    docker_compose = module.deployment.docker_compose_file
    services       = [for s in module.services : s.config_file]
    monitoring     = var.enable_monitoring ? module.monitoring[0].config_file : null
  }
  description = "Generated configuration files"
}

Environment Configuration

environments/production.tfvars:

environment = "production"

project = {
  name        = "blog-platform"
  version     = "2.0.0"
  team        = "platform"
  cost_center = "eng-001"
}

tier = "enterprise"

services = {
  web = {
    enabled  = true
    port     = 8080
    replicas = 3
    features = ["caching", "cdn"]
  }
  
  api = {
    enabled  = true
    port     = 8081
    replicas = 5
    features = ["rate-limiting", "auth"]
  }
  
  admin = {
    enabled  = true
    port     = 9000
    replicas = 2
    features = ["audit-logging"]
  }
  
  worker = {
    enabled  = true
    port     = 9001
    replicas = 3
    features = ["queue", "retry"]
  }
}

enable_monitoring = true

Module Dependency Graph

Deploy

terraform init
terraform apply -var-file="environments/production.tfvars"

Result:

• ✅ 4 services configured (web, api, admin, worker)

• ✅ Each service scaled by tier (enterprise = 5x)

• ✅ Configuration files generated

• ✅ Secrets created

• ✅ Monitoring configured

• ✅ Docker Compose ready

• ✅ Deployment manifest created

---

Module Versioning

Semantic Versioning for Modules

v1.2.3
│ │ │
│ │ └─ PATCH: Bug fixes, documentation
│ └─── MINOR: New features (backward compatible)
└───── MAJOR: Breaking changes

Creating Versions

# Tag the module
git tag -a v1.0.0 -m "Initial stable release"
git push origin v1.0.0

# Subsequent versions
git tag -a v1.1.0 -m "Add monitoring support"
git push origin v1.1.0

git tag -a v2.0.0 -m "Breaking: Rename variables"
git push origin v2.0.0

Using Versioned Modules

module "service" {
  source = "github.com/myorg/terraform-modules//service?ref=v1.1.0"
  
  # ...
}

# Or with Terraform Registry
module "service" {
  source  = "app.terraform.io/myorg/service/local"
  version = "~> 1.1"
  
  # ...
}

Version Constraints

# Exact version
version = "1.2.3"

# Minimum version
version = ">= 1.0.0"

# Maximum version
version = "< 2.0.0"

# Range
version = ">= 1.0.0, < 2.0.0"

# Pessimistic constraint (recommended)
version = "~> 1.2"     # >= 1.2.0, < 2.0.0
version = "~> 1.2.0"   # >= 1.2.0, < 1.3.0

---

Testing Modules

Manual Testing

Create a test directory:

modules/service/
├── main.tf
├── variables.tf
├── outputs.tf
└── test/
    └── main.tf

test/main.tf:

module "test_service" {
  source = "../"
  
  name        = "test-service"
  environment = "test"
  
  config = {
    port     = 9999
    replicas = 1
    features = ["test-feature"]
    tier     = "basic"
  }
}

output "test_result" {
  value = module.test_service.info
}

Run test:

cd test
terraform init
terraform apply

Automated Testing with Terratest

test/service_test.go:

package test

import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

func TestServiceModule(t *testing.T) {
    terraformOptions := &terraform.Options{
        TerraformDir: "../",
        Vars: map[string]interface{}{
            "name": "test-service",
            "environment": "test",
            "config": map[string]interface{}{
                "port": 9999,
                "replicas": 1,
                "features": []string{"test"},
                "tier": "basic",
            },
        },
    }
    
    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)
    
    serviceName := terraform.Output(t, terraformOptions, "service_name")
    assert.Equal(t, "test-service-test", serviceName)
}

---

Publishing Your Module

Terraform Registry Requirements

1. GitHub repository

2. Standard module structure

3. Semantic versioning (Git tags)

4. README.md with usage examples

5. LICENSE file

Module Structure

terraform-local-service/
├── README.md
├── LICENSE
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
└── examples/
    ├── basic/
    │   └── main.tf
    └── complete/
        └── main.tf

README.md Template

# Terraform Service Module

Creates and configures a service with monitoring.

## Usage

```hcl
module "web_service" {
  source = "app.terraform.io/myorg/service/local"
  version = "~> 1.0"
  
  name        = "web"
  environment = "production"
  
  config = {
    port     = 8080
    replicas = 3
    features = ["caching"]
    tier     = "enterprise"
  }
}

Examples

• Basic - Minimal configuration

• Complete - Full-featured setup

Requirements

Name	Version
terraform	>= 1.0
local	~> 2.4
random	~> 3.5

Inputs

Name	Type	Default	Required	Description
name	string	-	yes	Service name
environment	string	-	yes	Environment
config	object	-	yes	Service configuration

Outputs

Name	Description
service_name	Full service name
config_file	Configuration file path
info	Complete service information

License

MIT

### Publishing Steps

1. **Create GitHub repository** following naming convention:
   - `terraform-<PROVIDER>-<NAME>`
   - Example: `terraform-local-service`

2. **Push code with proper structure**

3. **Create release tags:**
   ```bash
   git tag -a v1.0.0 -m "Initial release"
   git push origin v1.0.0

1. Sign in to Terraform Registry:

   • Go to https://registry.terraform.io/

   • Sign in with GitHub

   • Publish module

2. Module is now available:

   module "service" {
     source  = "your-org/service/local"
     version = "1.0.0"
   }

---

Common Module Patterns

Pattern 1: Conditional Resource Creation

resource "local_file" "optional" {
  count = var.create_file ? 1 : 0
  
  filename = "optional.txt"
  content  = "Created conditionally"
}

Pattern 2: Default Values with Merge

locals {
  default_config = {
    replicas    = 1
    monitoring  = true
    cache       = false
  }
  
  config = merge(local.default_config, var.custom_config)
}

Pattern 3: Computed Resource Names

locals {
  resource_prefix = "${var.project}-${var.environment}"
  
  names = {
    web    = "${local.resource_prefix}-web"
    api    = "${local.resource_prefix}-api"
    worker = "${local.resource_prefix}-worker"
  }
}

Pattern 4: Feature Flags

variable "features" {
  type = object({
    caching    = bool
    monitoring = bool
    cdn        = bool
  })
}

resource "local_file" "cache_config" {
  count = var.features.caching ? 1 : 0
  # ...
}

resource "local_file" "monitoring_config" {
  count = var.features.monitoring ? 1 : 0
  # ...
}

Pattern 5: Multi-Environment Configuration

locals {
  env_configs = {
    dev = {
      replicas = 1
      size     = "small"
    }
    prod = {
      replicas = 5
      size     = "large"
    }
  }
  
  config = local.env_configs[var.environment]
}

---

What I Learned About Module Design

1. Start Simple, Refactor Later

Don't try to create the perfect module immediately:

First iteration:

# Simple, works for one use case
module "service" {
  source = "./modules/service"
  name   = "web"
}

After seeing patterns:

# Evolved to handle multiple scenarios
module "service" {
  source = "./modules/service"
  
  name   = "web"
  config = var.service_configs["web"]
  features = {
    caching = true
    monitoring = true
  }
}

2. Inputs Are Your API

Treat module inputs like a public API:

• Clear names: replicas not num

• Good defaults: Most inputs should be optional

• Validation: Catch errors early

• Documentation: Every variable needs description

3. Outputs Are Your Contract

Expose useful information:

• Resource IDs

• Computed values

• Structured data for downstream modules

4. Composition Over Complexity

Bad - One giant module:

module "entire_infrastructure" {
  source = "./modules/everything"
  # 50 input variables...
}

Good - Composed modules:

module "network" { }
module "compute" { }
module "database" { }
module "monitoring" { }

5. Test in Isolation

Each module should work standalone:

# modules/service/test/main.tf
module "test" {
  source = "../"
  name   = "test"
}

---

Next Steps

Congratulations! You've mastered Terraform modules:

✅ Module fundamentals ✅ Creating custom modules ✅ Module inputs and outputs ✅ Module sources (local, registry, Git) ✅ Module composition ✅ Terraform Registry ✅ Versioning and publishing ✅ Real-world multi-service platform ✅ Testing and best practices

Practice Exercises

Exercise 1: Refactor to Modules

Take your existing Terraform code and:
1. Identify repeated patterns
2. Extract them into modules
3. Replace duplication with module calls
4. Compare line count before/after

Exercise 2: Create a Module Library

Build a library of reusable modules:
- Configuration generator
- Secret manager
- Deployment manifest creator
- Monitoring setup

Exercise 3: Publish a Module

1. Create a useful module
2. Write comprehensive README
3. Add examples
4. Version with Git tags
5. Publish to Terraform Registry

Coming Up Next

In Article 6: State Management - Understanding and Managing Terraform State, we'll dive deep into:

• What is Terraform state?

• State file structure

• Remote state backends

• State locking

• State migration

• Troubleshooting state issues

Modules organize your code. State tracks your infrastructure. Together, they're the foundation of production Terraform.

---

This Week's Challenge: Refactor your existing infrastructure code into modules. Aim for 80% reduction in duplication. Share your module on GitHub!

See you in Article 6! 🏗️

---

"The day I learned modules was the day my infrastructure code went from 2,000 lines of copy-paste to 200 lines of elegant composition. I'll never go back." - Me, after deleting 1,800 lines of duplicated code