Designing Terraform Root and Child Modules: A Practical Hierarchy Guide

Terraform design comes down to one decision: what becomes the root and what gets carved out into child modules. Get this wrong and you will struggle with state management, reuse, and team collaboration.

This article covers the Terraform Associate (entry-level) exam angles while showing the hierarchy design principles that hold up in production, with minimal patterns and code.

Internalize the Definitions and Roles of Root vs Child

The root module is the set of .tf files in the directory where you run terraform init/plan/apply. A child module is one called by a module block from the root, and a child can call further child modules of its own.

The key point for both practice and the exam: concentrate provider configuration, state file, and I/O boundaries at the root, and keep child modules small and loosely coupled for reuse. As a rule, provider configuration lives in the root and is passed to children via the providers argument.

• Root is the operational unit bound to a single state file (backend)
• Child is a per-feature reuse unit. Make its I/O (variables/outputs) explicit
• Centralize provider configuration in the root. Children externalize their provider dependency
• Make inter-module dependencies explicit via outputs. Avoid implicit dependencies

Minimal example: a root calling a child

terraform {
  required_version = ">= 1.5"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = var.region
}

module "network" {
  source    = "./modules/network"
  providers = { aws = aws }
  cidr      = var.vpc_cidr
}

Directory Design Patterns That Resist Breakage

Sharing modules in a single repository and splitting roots by environment is the go-to layout that balances learning cost and isolation. Splitting across multiple repositories is fine to defer until your change flow and release management are settled.

Prefer nouns over verbs in naming. Split modules along resource boundaries like network, compute, security, and let the root apply only the per-environment differences (dev/stg/prod).

• Keep modules/ small and loosely coupled: one module, one responsibility
• Under environments/ are the roots: separate tfvars and backend per environment
• Include the environment name in the state key (prefix) to prevent collisions

Recommended layout (single repository)

repo-root/
  modules/
    network/
      main.tf
      variables.tf
      outputs.tf
    compute/
      main.tf
      variables.tf
      outputs.tf
  environments/
    dev/
      main.tf
      variables.tf
      terraform.tfvars
      backend.hcl
    stg/
      main.tf
      terraform.tfvars
      backend.hcl
    prod/
      main.tf
      terraform.tfvars
      backend.hcl

Split backend configs into files and pass them via the CLI (variables are not supported here)

# environments/dev/backend.hcl
bucket         = "my-tfstate-bucket"
key            = "env/dev/terraform.tfstate"
region         = "ap-northeast-1"
dynamodb_table = "my-tf-lock"

# 初期化
# terraform -chdir=environments/dev init -backend-config=backend.hcl

Lock Down the Flow of variables / outputs / locals

In a child module, the input boundary is variables.tf and the output boundary is outputs.tf. Keep the internal representation inside locals so the root cannot see it.

The root supplies only the per-environment differences via tfvars, and makes dependencies explicit by passing one module's output as the input of another.

• Strictly manage required vs default for child variables
• Expose only the outputs that downstream consumers truly need
• Use a naming convention on locals to signal they are not exposed externally

Minimal I/O example

# modules/network/variables.tf
variable "cidr" {
  type        = string
  description = "VPC CIDR"
}

# modules/network/main.tf
resource "aws_vpc" "this" {
  cidr_block = var.cidr
  tags = { Name = "nlab-vpc" }
}

# modules/network/outputs.tf
output "vpc_id" {
  value = aws_vpc.this.id
}

# environments/dev/main.tf
module "network" {
  source = "../../modules/network"
  cidr   = var.vpc_cidr
}

module "compute" {
  source = "../../modules/compute"
  vpc_id = module.network.vpc_id
}

Environment Separation: Directory Layout vs Workspaces

For production where strong isolation is required (separate permissions, backends, and change windows), the baseline is to split the root directory per environment. State and backend config are then physically separated.

Terraform workspaces switch the state file while keeping the same code and backend. They are useful for lightweight sandboxes and short-lived review environments, but when per-environment differences are large, directory separation is safer.

• For production, make separate root + separate backend + separate IAM the baseline
• Workspaces are for short-lived, homogeneous environments. Keep config diffs minimal
• Backends do not accept variables, so split them per environment into files and pass via init

Apply the differences in each environment's root (tfvars example)

# environments/dev/terraform.tfvars
region    = "ap-northeast-1"
vpc_cidr  = "10.10.0.0/16"

# environments/prod/terraform.tfvars
region    = "ap-northeast-1"
vpc_cidr  = "10.20.0.0/16"

# 実行例
# terraform -chdir=environments/dev plan -var-file=terraform.tfvars

Get a Feel for Module Versioning and Reuse

Pin registry-distributed modules semantically with the version argument. For Git-referenced modules, specify a ref tag or commit hash in source. Modules referenced by local relative path cannot use version.

On update, use terraform init -upgrade, surface the changes with plan, and put them through review.

• Pin public/private registry modules with version
• For Git sources, pin with ref=tag/commit. Avoid pinning to a branch
• Test local modules together in CI, and promote them to a registry once they are ready for externalization

Registry and Git source examples

# Registry から取得
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.5"
  name    = "nlab"
  cidr    = "10.30.0.0/16"
}

# Git から取得(タグ固定)
module "network" {
  source = "git::https://github.com/example/network-module.git//modules/vpc?ref=v1.4.2"
  cidr   = "10.40.0.0/16"
}

# 更新時
# terraform init -upgrade

Validation Steps and How to Integrate into CI/CD

Automate lint → validate → plan in that order. Even just posting the plan diff as a PR comment raises quality. For apply, the safe path is to require a manual approval per environment.

For modules in isolation, run terraform validate plus a plan against a minimal mock. For roots, point at the backend and focus on visualizing the diff.

• Use fmt/validate/tflint as pre-checks
• Lock the artifact with plan -out and run apply in a separate job
• Require protected branches and explicit approval for destroy

Minimal CI step example (GitHub Actions)

name: terraform
on: [pull_request]
jobs:
  plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: environments/dev
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.7.5
      - run: terraform fmt -check
      - run: terraform init -backend-config=backend.hcl
      - run: terraform validate
      - run: terraform plan -var-file=terraform.tfvars -out=tfplan

Check Your Understanding

Frequently Asked Questions