README.md

Description

Repository where we store reusable terraform modules for GDS engineering access.

Requirements

• checkov
• codespell
• pre-commit
• terraform-docs
• tflint
• trivy

Steps:

1. Install using brew: brew install pre-commit tflint checkov trivy terraform-docs

2. Install pre-commit hooks: pre-commit install

Creating new modules

All terraform modules live in the root of the repository.

Create a new folder for your terraform module, using the following naming convention: <resource_type>-<module_name>. Example azurerm-conditional-access.

Generating documentation for the modules

A README.md file must be created on each module directory. The file is divided in two parts:

• Static sections explaining what the module does, examples on how to use it and any caveats
• Auto-generated sections managed by terraform-docs

Start by running pre-commit run terraform_docs. This will create a new file with the auto-generated sections in the module directory. Add your static content above the <!-- BEGIN_TF_DOCS --> line.

Every time an applicable change is made to the terraform module, pre-commit will automatically run terraform-docs and update the README.md when you attempt to commit. The initial commit will fail and you will need to stage the changes for the subsequent commit to succeed.

Releasing modules

First determine the next version to release

To release a new version of a specific module, create and push a git tag matching the module's directory name and desired version. For example, to release version 0.0.1 of the azurerm-conditional-access module, you would run the commands below from the root of the checked out repository:

git tag azurerm-conditional-access/v0.0.1 -m 'Initial release'
git push origin azurerm-conditional-access/v0.0.1

This will trigger the release workflow for that module only. Each module should be tagged and released independently using this pattern.

Consuming modules

1. On the Releases page, find your desired module/version combination and click on the short commit SHA hash:

2. On the commit page, click the copy button to retrieve the full commit SHA hash:

3. Reference the module in the source argument of your module block. Add a comment to indicate the release version this commit SHA represents:

module "azurerm-conditional-access" {
  source = "github.com/alphagov/gds-engineering-access-terraform-modules//<module name>?ref=<commit sha hash>" # <release version>
  #...
}

# Example

module "azurerm-conditional-access" {
  source = "github.com/alphagov/gds-engineering-access-terraform-modules//azurerm-conditional-access?ref=303d8966acf114429f8613fa070a1848c2ff3661" # v0.0.1
  #...
}

Important

The double forward slash is required syntax when referencing a module in a repository subdirectory.