bananalab / terraform-modules-template

Terraform Modules

This repository contains Terraform Modules for use in configurations.

Developing a module

Development Environment

This project uses devcontainers to provide a consistent developer experience. All required tools and settings are defined in the devcontainer config file .devcontainer/devcontainer.json.

Create a new module

From the project root run make module <module-name>. The new module can be found under the modules directory.

The make target creates a complete skeleton module for you. You can cd into the module directory and run make test. The example should run without error. Once you have verified that the skeleton project works you can begin coding it's functionality.

Module Layout

The template module is based on this article. There are a few modifications (test/ and versions.tf). This layout is the minimum... you may need to add to it. For example you might create a modules/ directory to contain embedded submodules.

terraform-my-module
├── examples                    < - Example usage of the module goes here.
│   └── simple                      All modules should include at least one.
│       └── main.tf
├── main.tf                     < - The main functionality of the module goes here.
├── outputs.tf                  < - Module outputs.
├── test                        < - Terratest tests go here.
│   ├── go.mod
│   ├── go.sum
│   └── integration_test.go
├── variables.tf                < - Module variables go here.
└── versions.tf                 < - Module requirements go here.

Documentation

This repo uses terraform-docs via pre-commit to automatically generate documentation of variables, outputs, and requirements. Additionally you should provide guidance by editing the header section of the module's main.tf file. The skeleton includes a header comment that looks like this:

/**
  * <!-- This comment will become the header of README.md.
  *      Include any important information here.
  *      Note that the `variables`, `outputs`, and provider
  *      requirements will be autogenerated... There is no
  *      need to include them here ==!>
  * # terraform-my-module
  *
*/

This will be converted to markdown and included at the top of README.md. You should write a sentence about how and when to use this module.

Using this repo

Publishing a module

After creating your module follow these steps to publish it:

• Create a new branch git checkout -b <my-new-module>.

• Stage your changes git add -A, or add files individually (be careful not to add unintended files).

• Commit your changes git commit

  Note:
  This repository uses [Conventional Commit]
  (https://www.conventionalcommits.org/en/v1.0.0/) messages to manage release
  tags.  Your commit message must be identifiable as a `feature` or a `fix` to
  be releasble.
  

• Ensure that all pre-commit checks have passed. Some hooks may alter staged files. If files are changed the commit will fail. You must re-stage these files before attempting to commit again. Other checks may fail without making changes. In these the check should tell you what the issues is. You will need to remedy the error before a commit will succeed.

• git push your branch and open a Pull Request against develop.

• The CI system will run Terratest against the test/ directory for all modules that have been modified in your branch. All tests must pass in order for the PR to become mergeable.

Modifting the .template

.template contains the definition used to create new modules via the module make target. This template may be modified if needed, but existing modules will not automatically be updated. The template directory is rendered by the gomplate utility, see its documentation to learn its capabilities. Currently only MODULENAME is passed in as a variable.