Creating a child module in Terraform - Step-by-Step CLI Walkthrough

Introduction

Sometimes your infrastructure code gets big and hard to manage. Creating a child module lets you split your code into smaller parts that you can reuse and organize better.

When you want to reuse the same infrastructure setup in different places without copying code.

When your main Terraform file is too long and you want to make it easier to read.

When you want to share infrastructure code with your team in a clean way.

When you want to separate different parts of your infrastructure logically.

When you want to test or update parts of your infrastructure independently.

Config File - main.tf

main.tf

module "my_child_module" {
  source = "./child_module"
  instance_count = 2
  instance_name = "example-instance"
}

output "child_instance_ids" {
  value = module.my_child_module.instance_ids
}

This is the main Terraform file that calls the child module.

module "my_child_module": This block tells Terraform to use the child module located in the child_module folder.

source: Path to the child module folder.

instance_count and instance_name: Variables passed to the child module.

output: This outputs the instance IDs created by the child module.

Commands

This command initializes Terraform in the current directory. It downloads the child module and prepares the working directory.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see any changes.

This command shows what Terraform will do when you apply the configuration. It checks the child module and shows the planned changes.

Terminal

terraform plan

Expected Output

An execution plan has been generated and is shown below.

Resource actions are indicated with the following symbols:

  + create



Terraform will perform the following actions:



  # aws_instance.example[0] will be created

  + resource "aws_instance" "example" {

      + ami           = "ami-12345678"

      + instance_type = "t2.micro"

      + tags          = {

          + "Name" = "example-instance-0"

        }

    }



Plan: 2 to add, 0 to change, 0 to destroy.

This command applies the changes to create the infrastructure defined in the child module. The -auto-approve flag skips the confirmation prompt.

Terminal

terraform apply -auto-approve

Expected Output

aws_instance.example[0]: Creating...

aws_instance.example[1]: Creating...

aws_instance.example[0]: Creation complete after 10s [id=i-0abcd1234efgh5678]

aws_instance.example[1]: Creation complete after 10s [id=i-0abcd1234efgh5679]



Apply complete! Resources: 2 added, 0 changed, 0 destroyed.



Outputs:



child_instance_ids = ["i-0abcd1234efgh5678", "i-0abcd1234efgh5679"]

→

-auto-approve - Automatically approve the apply without asking for confirmation

This command shows the output value from the child module, which is the list of instance IDs created.

Terminal

terraform output child_instance_ids

Expected Output

["i-0abcd1234efgh5678", "i-0abcd1234efgh5679"]

Key Concept

If you remember nothing else from this pattern, remember: a child module is a separate folder with its own Terraform files that you call from your main code to organize and reuse infrastructure.

Common Mistakes

Not specifying the correct source path for the child module.

Terraform cannot find the child module and will give an error.

Use a relative path like "./child_module" that points exactly to the folder containing the child module files.

Forgetting to pass required variables to the child module.

Terraform will fail because the child module expects variables that are missing.

Always pass all required variables in the module block in the main Terraform file.

Not running terraform init after adding a child module.

Terraform will not download or recognize the new module, causing errors.

Run terraform init to initialize and download modules before planning or applying.

Summary

Create a child module in a separate folder with its own Terraform files.

Call the child module from the main Terraform file using a module block with source and variables.

Run terraform init to initialize modules, terraform plan to preview changes, and terraform apply to create resources.

Use terraform output to see values returned from the child module.