Remote Modules

Remote modules#

Modules are great for enabling you to reuse configuration blocks across a project. What if you want to build up a library of modules and share them across your company or with your friends, though? Terraform has answered that question with remote modules. A remote module is a module hosted externally to the local file system. Terraform supports many different remote module sources such as GitHub, BitBucket, and S3.

Project example#

We are going to use GitHub to host the sqs-with-backoff module that we declared and then reference in our local project:

You will notice that this code is almost the same as the code we wrote earlier when using the sqs-with-backoff module. The only difference is that we are setting the source of the module to github.com/kevholditch/sqs-with-backoff rather than the local path to the folder. By default, Terraform will add the https:// for you.

Output#

We’ll initialise Terraform by running the terraform init command. You will see at the top of the output something like the following:

Module cloning#

Terraform clones the code for the module when it is initialised. The code is downloaded to .terraform/modules. If you have a look in that folder, you will see the module as defined in the repository github.com/kevholditch/sqs-with-backoff. Since we have specified the URL to the repository, the clone will be made from GitHub using https. If you want instead to clone using SSH, you can change the URL to [email protected]:kevholditch/sqs-with-backoff.git which is the SSH clone address. It is helpful that Terraform allows you to clone the module either way!

📝Note: You will need SSH setup with GitHub in order for the SSH clone to work.

Run the project by running terraform apply. You will see the same output as before where the two SQS queues are created, one being a dead letter queue of the other one.

Remote module disadvantage#

In a team environment when you are using remote modules to share modules using GitHub, you want to ensure that Terraform is run every time using the same version of the module. You want to be able to consciously control when you move to a newer version of the module if one is checked in. With the code we have written above, you will always get the latest version of the module by default every time you run Terraform. This is probably not ideal. If someone makes a change to the module, then that change will start rolling out the next time anyone runs a Terraform project that references the module.

Solution to the problem#

To get around this problem, you can pin the version of the remote module you reference by using a git tag. A tag in git is simply a marker to a commit. You can think of a git tag as a branch that never moves. In the repository github.com/kevholditch/sqs-with-backoff, we have created a tag 0.0.1 which points to an older version of the module. If you update the source in our code example to github.com/kevholditch/sqs-with-backoff?ref=0.0.1 and run terraform again, you will notice that the SQS queue names are now prefixed with bad_co instead of awesome_co.

Why this solution#

This happens by adding the parameter ref=0.0.1, which tells Terraform to use the source code inside the GitHub repository from the commit that was tagged with 0.0.1. The commit that the tag points to has a different queue prefix, so you can see that something has changed. When you omit the ref parameter, as we did at the start, you get the latest version from the master branch. It is much better to be able to control when you move by using the ref parameter.

Update project example code#

Now update the source URL to github.com/kevholditch/sqs-with-backoff?ref=0.0.2. Run terraform init and terraform apply again. The SQS queue names now get put back to awesome_co. The tag 0.0.2 also points to the latest version of the master branch, so the effect is the same as leaving the ref parameter off.