Terraform Module Sources: Local, Registry, and Git

Terraform modules are fundamental building blocks for Infrastructure as Code (IaC). They allow you to encapsulate and reuse infrastructure configurations. A crucial aspect of module development is understanding how to source and reference these modules. This section explores the three primary module sources: local paths, the Terraform Registry, and Git repositories.

1. Local Module Sources

Local module sources allow you to reference modules that are located within your local filesystem. This is particularly useful during module development and testing, as it enables rapid iteration without needing to publish your module to a registry or repository. You specify a relative or absolute path to the directory containing the module's

code

main.tf

file.

Local modules are for development and internal use.

Use local sources to reference modules directly from your file system, ideal for rapid development and testing.

When using a local source, Terraform looks for the module in the specified directory relative to the calling module. For example, source = "./modules/vpc" would reference a module located in a subdirectory named modules within the current directory. This method is simple and effective for organizing your Terraform code within a single project or monorepo.

What is the primary advantage of using local module sources?

Rapid iteration and testing during module development.

2. Terraform Registry Module Sources

The Terraform Registry is a centralized repository for sharing and discovering Terraform modules. It hosts both public and private modules, making it easy to find and use pre-built infrastructure components. Modules from the registry are referenced using a specific format that includes the namespace, name, provider, and optionally a version constraint.

The Terraform Registry is the standard way to share and consume reusable infrastructure modules across teams and organizations.

The general format for referencing a registry module is

code

source = "//"

. For example,

code

source = "hashicorp/aws/aws"

references the AWS VPC module. You can also specify a version using

code

version = "~> 1.0"

to ensure stability and predictability.

Referencing a module from the Terraform Registry involves specifying its unique identifier. This identifier typically follows the pattern: namespace/name/provider. For example, hashicorp/aws/aws means the module is published by hashicorp (namespace), is named aws (name), and is for the aws provider. Version constraints are crucial for managing dependencies and ensuring predictable deployments. Common version constraints include exact versions (= 1.2.3), pessimistic constraints (~> 1.2), or greater than/less than operators.

📚

Text-based content

Library pages focus on text content

3. Git Module Sources

Git repositories are another common and powerful way to source Terraform modules. This method is ideal for private modules within your organization or for collaborating on open-source modules. Terraform can directly clone a Git repository and use the module within it. You can specify a branch, tag, or commit hash for precise version control.

The syntax for Git sources includes the repository URL and optional parameters like

code

ref

for specifying the version. For example:

code

source = "git::https://github.com/hashicorp/terraform-aws-modules.git?ref=v3.0.0"

Source Type	Use Case	Versioning	Discovery
Local	Development, internal projects	Filesystem path	Manual discovery
Registry	Public/Private sharing, collaboration	Version constraints (tags, semantic versioning)	Terraform Registry UI/CLI
Git	Private repos, version control	Branch, tag, commit hash	Git repository browsing

What Git reference can be used to pin a module to a specific point in history?

A commit hash.

Choosing the Right Module Source

The choice of module source depends on your project's needs and your organization's workflow. Local sources are best for initial development. The Terraform Registry is excellent for widely shared, version-controlled modules. Git sources provide flexibility for private repositories and fine-grained control over module versions.

Learning Resources

Terraform Modules Documentation - Module Sources(documentation)

The official Terraform documentation detailing all available module source types and their usage.

Terraform Registry(documentation)

The official Terraform Registry where you can discover and publish modules.

Terraform AWS Modules - GitHub(documentation)

A popular collection of reusable Terraform modules for AWS, hosted on GitHub, demonstrating Git sourcing.

Terraform Modules: Best Practices(blog)

A blog post from HashiCorp discussing best practices for creating and using Terraform modules, including sourcing.

Understanding Terraform Module Sources(blog)

An article explaining the different Terraform module sources and when to use each.

Terraform Module Development Workflow(tutorial)

A tutorial on creating your own Terraform modules, which covers local sourcing and testing.

Advanced Terraform: Modules and Workspaces(video)

A video that delves into advanced Terraform concepts, including module usage and sourcing strategies.

Terraform Git Source Example(documentation)

Specific documentation examples for using Git repositories as Terraform module sources.

Terraform Module Versioning(documentation)

Details on how to specify and manage versions for Terraform modules, crucial for registry and Git sources.

Terraform Registry Module Structure(documentation)

Information on the expected structure of modules published to the Terraform Registry.

Module Sources: Local, Registry, Git

Terraform Module Sources: Local, Registry, and Git

1. Local Module Sources

Local modules are for development and internal use.

2. Terraform Registry Module Sources

3. Git Module Sources

Choosing the Right Module Source

Learning Resources