Skip to content

Terraform Module Boilerplate

This page documents our standard boilerplate for creating reusable Terraform modules within the uis/devops/infra/terraform GitLab group. It helps teams quickly scaffold new modules or retrofit existing ones with the structure, testing, and CI support required by DevOps.

Using the boilerplate

This boilerplate is implemented using Copier, which you can run locally or in CI to scaffold new or existing modules.

To create a new module or update an existing one, follow these steps:

Template Git URL

Use this Git URL with Copier:

Copier options

When you run the boilerplate, Copier will prompt you for:

  • module_name: Short Terraform module name (e.g. gcp-service-account)
  • module_long_name: A longer, human-readable description of the module
  • cloud_provider: The target cloud platform (gcp, none)
  • run_python_tests: Whether to include Python test tooling (rare)
  • run_terraform_tests: Whether to include Terraform testing scaffold
    • If true, you must also provide test_name_prefix: a short (max 4 chars) prefix used to generate unique resource names during test runs

Features like test files, cloud setup, and CI config are generated conditionally based on your answers.

Template features

The boilerplate includes:

  • Standard Terraform files (main.tf, variables.tf, outputs.tf, versions.tf, locals.tf)
  • CI config for linting, testing, and publishing
  • Preconfigured test scaffolding using terraform test
  • Optional Python test runner (tox) and task runner (poe)
  • Example documentation and file structure

All features are conditionally included based on your responses to the Copier prompts.

Cloud provider options

During generation, the boilerplate asks which cloud provider the module will target. Currently, we support the following options:

gcp

Select gcp if your module manages Google Cloud resources. This enables:

  • GCP-specific test files under tests/
  • Terraform variables and setup files suited for the Infra Testing GCP project
  • Enforcement of the ucam-devops-terraform-test label for test resources
  • Expectations that real infrastructure will be deployed during testing

The module will also be compatible with our shared GKE-based GitLab runners and standard test cleanup tool.

none

Select none if your module is a standalone, utility module that does not manage cloud infrastructure directly. Examples include:

  • Terraform modules that generate configuration only
  • Modules that manipulate internal data structures
  • Modules tested entirely in plan mode

Choosing none will:

  • Disable cloud-specific setup/test files
  • Still include support for terraform test (plan-only mode)
  • Avoid assumptions about GCP-specific resources, service accounts, or test environments

This mode is ideal for reusable logic modules, string transformers, label normalisers, etc.

Testing and CI

Modules created or retrofitted using this boilerplate support our testing guidance:

  • Unit and integration tests via terraform test
  • Shared test environment (Infra Testing) in GCP
  • Pre/post test cleanup with terraform-test-cleanup
  • GitLab JUnit report support

Tests are defined under tests/, with setup/ used for shared scaffolding. Testing files are cloud-specific and generated only if run_terraform_tests = true.

CI is configured via .gitlab-ci.yml, which includes:

  • Linting: terraform fmt, validate, tflint, trivy
  • Testing: terraform test with cleanup
  • Optional: publishing to the internal Terraform Registry

See also