# Terraform Modules Done Right: Lessons from Managing 50+ Services

URL: https://www.devopsness.com/blog/terraform-modules-done-right-lessons-from-managing-50-services
Author: Kiril Urbonas
Published: 2026-04-01
Updated: 2026-04-01
Categories: Infrastructure
Tags: Terraform, Terraform Modules, Infrastructure as Code, AWS, CI/CD

Summary: Practical patterns for Terraform modules at scale: versioning, composition, testing, and avoiding the monolith trap.

---
# Terraform Modules Done Right: Lessons from Managing 50+ Services

After managing infrastructure for 50+ microservices with Terraform, we've learned which module patterns scale and which become nightmares. Here's what works.

## The Monolith Trap

Our first approach was one massive Terraform repo with everything in it. Plan took 12 minutes. A typo in a dev variable once triggered a production change. We split it up.

## Pattern 1: Layered Modules

We organize modules in three layers:

```
modules/
  base/          # VPC, subnets, DNS zones
  platform/      # EKS cluster, RDS, ElastiCache
  service/       # Per-service: ALB, task def, IAM role
```

Each layer depends only on the layer below via **remote state data sources**:

```hcl
data "terraform_remote_state" "platform" {
  backend = "s3"
  config = {
    bucket = "terraform-state-prod"
    key    = "platform/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_lb_target_group" "service" {
  vpc_id = data.terraform_remote_state.platform.outputs.vpc_id
  # ...
}
```

## Pattern 2: Versioned Module Registry

We publish reusable modules to a private registry with semantic versioning:

```hcl
module "service" {
  source  = "app.terraform.io/ourorg/service/aws"
  version = "~> 2.0"

  name        = "payment-api"
  environment = "production"
  cpu         = 512
  memory      = 1024
}
```

**Rules we follow:**
- Breaking changes = major version bump
- New optional variables = minor version bump
- Bug fixes = patch version bump
- Teams pin to major version (`~> 2.0`), not exact

## Pattern 3: Composition Over Configuration

Instead of one module with 40 variables and 15 conditional blocks, we compose small modules:

```hcl
module "alb" {
  source = "./modules/alb"
  # ...
}

module "ecs_service" {
  source          = "./modules/ecs-service"
  target_group_arn = module.alb.target_group_arn
  # ...
}

module "monitoring" {
  source       = "./modules/cloudwatch-alarms"
  service_name = module.ecs_service.name
  # ...
}
```

Each module does one thing. Connecting them is explicit, not hidden behind flags.

## Pattern 4: Automated Testing

We test modules with `terraform validate`, `tflint`, and integration tests:

```bash
# In CI pipeline
cd modules/service
terraform init -backend=false
terraform validate
tflint --init
tflint

# Integration test (creates real resources, then destroys)
cd tests/
go test -v -timeout 30m ./...
```

## Best Practices Summary

1. **Keep blast radius small**: one service per state file
2. **Version your modules**: semantic versioning with a changelog
3. **Compose, don't configure**: small modules > one mega-module
4. **Test in CI**: validate + lint + integration tests
5. **Use remote state carefully**: read-only data sources, not cross-stack references
6. **Document inputs/outputs**: a module without docs is a module no one trusts

Terraform at scale is a software engineering problem, not just an infrastructure problem. Treat your modules like libraries.
