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.
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.