Enterprise Repository & Module Layout

In this module, you'll learn to:

• Keep reusable child modules apart from the root modules that deploy them
• Split each environment into numbered state layers, and explain what that protects
• Pin versions exactly in production roots and as ranges in child modules

Before you start: you should be comfortable writing basic Terraform: resources, variables, terraform plan, and terraform apply. This is the first module of the track.

The two types of Terraform modules

Mixing up a reusable child module and a root deployment module is one of the most common reasons a Terraform codebase becomes hard to maintain.

Keep the two apart:

• Child modules (the building blocks): reusable blueprints driven by inputs. They don't declare a backend, hardcode account IDs, or mention a specific environment. They're versioned and released like software libraries.
• Root modules (the deployments): the real environments. They set the S3 state backend and the provider (account, region, credentials), call the child modules, and pass in environment-specific values from .tfvars.

The canonical directory layout

Organize the repository into clear layers of responsibility:

terraform-root/
├── modules/                         # Reusable child modules (pure blueprints, versioned)
│   ├── vpc/
│   │   ├── main.tf                  # VPC, subnets, route tables, flow logs
│   │   ├── variables.tf             # Inputs with validation & type constraints
│   │   ├── outputs.tf               # Exports VPC ID, subnet IDs, CIDR blocks
│   │   ├── versions.tf              # Min provider/core constraints (~> 5.0)
│   │   └── README.md                # Generated documentation with inputs/outputs
│   ├── aurora-postgresql/
│   └── eks-cluster/
│
└── environments/                    # Root execution environments (where state lives)
    ├── prod/
    │   ├── 00-bootstrap/            # S3 state bucket and KMS keys
    │   │   ├── backend.tf           # (Local backend during first run, then migrated)
    │   │   └── main.tf
    │   ├── 01-networking/           # Foundation: VPC, Transit Gateway, Route 53
    │   │   ├── backend.tf           # S3 backend with native locking (use_lockfile)
    │   │   ├── main.tf              # Calls modules/vpc with prod parameters
    │   │   ├── providers.tf         # Provider with exact version pin
    │   │   ├── terraform.tfvars     # Prod CIDRs, tags, AZs
    │   │   ├── variables.tf
    │   │   └── outputs.tf           # Writes IDs to AWS SSM Parameter Store
    │   ├── 02-security/             # Organization IAM roles, GuardDuty, Security Hub
    │   │   ├── backend.tf
    │   │   └── main.tf
    │   ├── 03-data/                 # Aurora DB, DynamoDB tables, S3 lakes, EFS
    │   │   ├── backend.tf
    │   │   └── main.tf
    │   └── 04-compute/              # EKS clusters, Node Groups, ALB, ECS services
    │       ├── backend.tf
    │       └── main.tf
    │
    └── nonprod/                     # Parity with prod; identical 5-layer topology
        ├── 00-bootstrap/
        ├── 01-networking/
        ├── 02-security/
        ├── 03-data/
        └── 04-compute/

The 5-Layer Enterprise Slicing Standard

Why slice environments into numbered layers instead of one monolithic deployment?

Exact pins in roots, ranges in modules

Where you declare a version matters as much as which version you pick:

1. In child modules: allow a range with ~>

The pessimistic constraint operator ~> lets a module accept compatible minor updates, so it works in more places:

# modules/vpc/versions.tf
terraform {
  required_version = ">= 1.5.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.30" # Accepts 5.30.x and 5.99.x, but rejects 6.0.0
    }
  }
}

2. In production roots: pin exact versions with =

A production plan should give the same result every time. If a provider release changes behaviour overnight, your pipeline shouldn't pick it up by surprise:

# environments/prod/01-networking/versions.tf
terraform {
  required_version = "= 1.11.4" # 1.11+: native S3 state locking is generally available

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "= 5.48.0" # Strictly pinned for reproducible plans
    }
  }
}

Anti-patterns to avoid

Anti-Pattern 1: The "Monolithic State Monster"

Putting VPC networking, Aurora clusters, IAM roles, and EKS deployments in a single main.tf file.

• Why it fails: one typo in an IAM policy can put the database in the same plan, and terraform plan gets slow across hundreds of resources.
• Fix: split state into separate layers (01-networking, 02-security, 03-data, 04-compute).

Anti-Pattern 2: Hardcoding Environment Logic Inside Modules

Writing if var.env == "prod" inside a reusable module.

• Why it fails: the module now only works for the environments it knows about, and every new environment means editing the module.
• Fix: pass the setting in as a variable instead (for example retention_in_days = var.log_retention_days).

Anti-Pattern 3: Unpinned Modules in Git

Referencing modules using source = "git::https://github.com/.../my-module.git" without a tag or commit ref.

• Why it fails: Any push to main in the module repo immediately changes future plans in production.
• Fix: always pin to a release tag such as ?ref=v1.4.2, or a commit SHA.

Key terms

• Child module: a reusable blueprint driven by inputs. No backend, no account IDs, no environment names.
• Root module: a real deployment. It sets the backend and provider, calls child modules, and passes in each environment's values.
• State layer: a numbered root (00-bootstrap to 04-compute) with its own state, its own lock, and its own CI role.
• ~> constraint: accepts compatible updates within a major version. ~> 5.30 allows 5.30 and later 5.x, but not 6.0.
• Exact pin (=): used in production roots, so a new provider release can't change a plan by surprise.

Pop quiz

Five questions: three on the ideas in this module, and two scenarios where you apply them. The order changes every time you take it, and 4 out of 5 passes.