HashiCorp Terraform empowers DevOps Engineers and SREs to manage cloud resources efficiently. One of its standout features is the Terraform Modules support, allowing users to organize and reuse infrastructure code effectively as reusable modules. While Terraform’s native module registry serves as a central hub for sharing modules, sometimes you may prefer hosting modules in your own Git repository for greater control and flexibility.

In this article, we’ll look at how to leverage Git repositories as sources for Terraform modules, enabling seamless integration of your infrastructure code with version control systems like GitHub and Azure DevOps Repos.

Git Repositories as Terraform Module Sources

Terraform’s flexibility allows you to define module sources using Git repositories. Whether your modules reside in GitHub, Azure DevOps Repos, or any other Git hosting service, Terraform’s git:: prefix followed by the repository’s SSH or HTTPS URL enables seamless integration. Terraform recognizes this URL format natively to support pulling the Terraform module source from the specified Git repository.

Here are examples of defining Terraform module sources using HTTPS and SSH URLs:

# Git SSH URL
module "WebApp1" {
  source = "git::https://github.com/Build5Nines/tf-webapp-module.git"
}

# Git HTTPS URL
module "WebApp1" {
  source = "git::ssh://git@github.com:Build5Nines/tf-webapp-module.git"
}

When using Git SSH URLs, Terraform automatically utilizes locally configured SSH keys, ensuring secure access to Git repositories. This approach aligns with best practices for automated systems accessing version control securely.

These examples of configuring Git HTTP and Git SSH URLs as the source for Terraform modules is assuming that each of the GitHub repositories referenced contain the Terraform code for a single module. Referencing modules this way will require a unique Git repository for each Terraform Module.

Specify Module Revision within Git Repository

Terraform, by default, will use the default branch in the Git repository specified. This can be overrided by using the ref argument on the Git repository URL. The ref value passed in the URL can be any value that the git checkout command accepts. The ref attribute can be used to specify the branch, tag, or even commit to source the Terraform module from.

Here’s a couple examples of the multiple supported uses of ref to specify the Terraform module revision:

# select a specific branch
module "WebApp1" {
  source = "git::https://github.com/Build5Nines/tf-webapp-module.git?ref=dev"
}

# select a specific Git tag
module "WebApp1" {
  source = "git::https://github.com/Build5Nines/tf-webapp-module.git?ref=v2.5.0"
}

# select a specific commit using SHA-1 hash
module "WebApp1" {
  source = "git::https://github.com/Build5Nines/tf-webapp-module.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}

Organize Multiple Modules within a Single Git Repository

It’s common to host multiple Terraform modules within the same Git repository, each residing in distinct sub-folders. Terraform accommodates this scenario by allowing you to specify the sub-folder containing the desired module within the source URL.

Consider a Git repository with multiple Terraform modules organized in sub-folders. To reference a specific module, you simply suffix the source URL with // followed by the sub-folder name containing the module.

Here’s an example of referencing a two different Terraform modules from the same Git repository:

module "StorageAccount1" {
  source = "git::https://github.com/Build5Nines/terraform-quickstart-templates.git//microsoft-azure/modules/azure_storage_account"
}

module "VirtualNetwork1" {
  source = "git::https://github.com/Build5Nines/terraform-quickstart-templates.git//microsoft-azure/modules/azure_virtual_network"
}

Related: These examples are referencing real Terraform modules that are a part of the Build5Nines Terraform Quickstart Templates open source project.

Terraform Modules in GitHub Repository

The source URL for referencing Terraform Modules within a GitHub Repository is the path to the GitHub repository. There are two syntaxes to the source URL of referencing Terraform Modules from GitHub depending on if the module will be downloaded over HTTPS or SSH.

The following is the syntax of the HTTPS and SSH URLs for referencing Terraform Modules contained within a GitHub Repository named build5nines/terraform-modules:

# HTTPS URL
github.com/build5nines/terraform-modules

# SSH URL
git@github.com:build5nines/terraform-modules.git

To build the SSH and HTTP URLs for GitHub repositories, use the following format while replacing the names for your own GitHub repository:

# GitHub Repository URL Format
# SSH
git@github.com:<username>/<repository>.git

# HTTP
github.com/<username>/<repository>

When referencing GitHub repositories as the source for Terraform modules, the repo contents will be able to be automatically downloaded for any “public” GitHub repositories. For “private” GitHub repositories, you will need to authenticate against GitHub using git in the command-line prior to running any terraform commands. Terraform doesn’t authenticate directly with the GitHub repos, but uses git to do so.

Terraform Modules in Azure DevOps Repos

Since Azure DevOps Git Repositories are really just Git repositories, they can also be used as a Terraform Module source using the same URL syntax to support both HTTPS and SSH URLs.

The following URLs are examples of the SSH and HTTPS URLs for Azure DevOps Git repositories named terraform-modules within the terraform-modules Git repository of the Azure DevOps build5nines organization.

# Azure DevOps Git Repositories
# SSH
git@ssh.dev.azure.com:v3/build5nines/webapp1/terraform-modules
# HTTPS
https://build5nines@dev.azure.com/build5nines/webapp1/_git/terraform-modules

To build the SSH and HTTPS URLs for Azure DevOps Repos, use the following format while replacing the names for your own Azure DevOps organization, project, and repo:

# Azure DevOps Git Repository URL Format
# SSH
git@ssh.dev.azure.com:v3/<organization>/<project>/<repository>
# HTTPS
https://<organization>@dev.azure.com/<organization>/<project>/_git/<repository>

Just as with referencing Terraform Modules from any other Git repository, multiple Terraform Modules can be hosted within a single Azure DevOps Git Repository with each module in a sub-folder at the root of the Git repository. These individual Terraform Modules within the Git Repository can be referenced by appending the source URL for the Git repository with // followed by the Terraform Module sub-folder name.

The following is an example of referencing a Terraform Module using a Git SSH URL hosted within an Azure DevOps Git Repository contained within a sub-folder of the Git repository.

module "WebApp1" {
  source = "git@ssh.dev.azure.com:v3/build5nines/webapp1/terraform-modules//azure-web-app
}

Related: If you need some assistance configuring an SSH key to be used to authenticate with an Azure DevOps Git Repository, please check out the “Azure DevOps: Create SSH Key to Authorize Git on macOS” article written by Chris Pietschmann.

Conclusion

Integrating Git repositories as sources for Terraform modules enhances your infrastructure management workflow. Whether you’re leveraging GitHub, Azure DevOps Repos or any other Git hosting services, Terraform’s flexibility accommodates diverse setups.

By harnessing Git repositories, you gain finer control over versioning, collaboration, and access control of your infrastructure code. Moreover, Terraform’s seamless integration with Git repositories streamlines module management, empowering you to build and maintain infrastructure with efficiency and reliability.

Incorporate Git repositories into your Terraform projects today, and unlock a new level of flexibility and control in managing your infrastructure codebase.

About the Author