Terraform Modules in Subdirectories

Terraform modules are usually at the root of a repository. Sometimes they’re nested in a subdirectory, and you need to point Terraform at the right one.

Terraform handles this with a double-slash (//) in the source path. Everything after the // is treated as a subdirectory within the package.

How It Works

The syntax is straightforward:

module "consul" {
  source = "hashicorp/consul/aws//modules/consul-cluster"
}

The hashicorp/consul/aws part is the module registry path. The //modules/consul-cluster tells Terraform to look inside that package for the actual module.

You can use this with any source type:

# Git repository
module "vpc" {
  source = "git::https://example.com/network.git//modules/vpc"
}

# Zip file
module "vpc" {
  source = "https://example.com/network-module.zip//modules/vpc"
}

# S3 bucket
module "vpc" {
  source = "s3::https://s3-eu-west-1.amazonaws.com/examplecorp-terraform-modules/network.zip//modules/vpc"
}

Version Control Sources

When you’re pulling from Git and need to pin a version with ref, the subdirectory path comes before the query parameters:

module "vpc" {
  source = "git::https://example.com/network.git//modules/vpc?ref=v1.2.0"
}

Get the order wrong and Terraform won’t find your module.

What Gets Downloaded

Terraform downloads the entire package, not just the subdirectory you’re after. It then looks inside for the module at the path you specified and uses that. The rest is ignored.

This also means modules inside the same package can reference each other using local relative paths, which is handy when you’re organising a set of related modules together.

Why This Matters

You don’t have to split every module into its own repository. If you’ve got a group of modules that belong together – say, a VPC module and a security group module that always ship together – you can keep them in one repo and point at each subdirectory as needed.

It keeps related code close without forcing you to manage a dozen repositories for what amounts to one logical unit.

More details in the official Terraform documentation on Modules in Package Subdirectories.