install

Installation Techniques

Terraform Module Sources

All the techniques for installing modules are based around the ways that Terraform modules are sourced. Terraform provides good documentation on this here.

Preferred Method

Using the Repo Source

Assuming you don't have manual modifications that you need to make to serve the purposes of an application, the most convenient method of integrating modules might be by using the repo source of this module like so:

module "namespace" {
    source = "github.com/pbs/terraform-namespace-module?ref=x.y.z"
}

The advantage of installing the module like this is that the module code does not reside in the application repository, and that no manual changes can be performed within the application repository, ensuring that resources are provisioned according to the remote module specifications.

The disadvantage is that this can slow down the provisioning process, especially when large or a large number of modules are being used. In addition, the requirement to have a bespoke manual adjustment to the module can require that the integration method be changed, causing inconsistencies in the application.

Note that the provider being used might also have availability or security implications to account for. If this module is being used without being forked, then the ability to use your module will be dependent on the availability of GitHub. If you do decide to fork this repository, then the repository hosting solution of your choice might have reduced availability or require require SSH key management if the source code is not hosted publicly.

Alternative Installation Methods

Manual Installation

You can install the minified module directly in your repo manually like so:

mkdir -p 'terraform/modules/namespace'
gh -R 'pbs/terraform-namespace-module' release download -p 'release.tar.gz' x.y.z
tar -xvf release.tar.gz -C 'terraform/modules/namespace'
rm -f release.tar.gz

The files will be introduced into your repository as normal, uncommitted files, and must be managed through git manually.

Git Subtrees

You can use this module (or private forks of this module) without authentication during initialization by incorporating this Terraform module as a Git Subtree and referencing the repo by path to source, in a similar fashion to the examples in this repo.

Please read this for information about Git Subtrees, as that will give you a better idea of how they work than the explanation here.

The simplest use case would work like so:

git remote add -f namespace [email protected]:pbs/terraform-namespace-module.git
git subtree add --prefix terraform/modules/namespace namespace main --squash

If necessary, pin the repo version, rather than adding main as your subtree:

git subtree add --prefix terraform/modules/namespace namespace $REF --squash

Where $REF is a commit SHA, tag, or branch name.

Note that unlike submodules, any changes that you make here will be committed back to your repo, rather than the module. This can allow you to make manual modifications that suite your application without updating the source module.

If your changes are testable and widely applicable, please consider sharing your contributions in a pull request to the module!