OPG Terraform Modules
Scope
This guide will set out when & how we should use Terraform modules.
Overview
Modules in Terraform are self-contained packages of Terraform configurations that are managed as a group. Modules are used to create reusable components in Terraform as well as for basic code organization.
Linked ADR
This guide references ADR-0003-terraform-module-usage.
Guide
Remote Modules
Where possible, we must use modules from the Terraform registry.
We must pin modules from the Terraform registry to major versions.
If you are writing a Terraform module aim to publish it as a public module with its own test pipeline and repository, an exemplar repository is the Terraform AWS VPC module.
You should use the release information area of GitHub to update users of a MAJOR update to a shared module with any contract changes. This will help when Dependabot, Renovate or simialr tools create an update for users of your module.
When to write a Local Module
Local modules should be shareable across environments or for code reuse. For example, a Lambda that has different content but the same configuration otherwise would be a good candidate.
Module Documentation & Testing
- Modules should contain usage documentation so that a user can understand how, and when to use the module.
- Documentation tools such as terraform-docs should be used for generating the inputs and outputs of modules.
- Annotate
inputsandoutputsusing the description field. - Unit test the module.
- A
README.mdthat states its purpose and usage.