terraform-modules

A repo for creating terraform modules.

Module Usage

Copy the relevant module from its example file and delete the local source. Uncomment the remote source path and replace the <ref> with the latest version from the repo's releases page. You can pin to a MAJOR, MINOR, or PATCH version. Check out Release Strategy for considerations before doing so, I recommend only pinning to MINOR or PATCH versions.

Release Strategy

To release a new version, use bump-repo-version-tags.py to create or update the relevant tags.

The version incrementing strategy is as follows:

• MAJOR - Major changes such as provider major version bumps
• MINOR - Breaking changes to one or more existing modules
• PATCH - Non-breaking changes to existing modules or adding new modules

Usage:

python bump-repo-version-tags.py "PATCH" "add s3/bucket module"

Module Structure

• README.md - README that provides an overview of the module, link to the example file, and documentation that is auto-generated by terraform-docs
• data.tf - all external data sources the module references
• locals.tf - all locals the module calculates
• main.tf - all resources the module creates and manages
• outputs.tf - all module outputs
• variables.tf - all variables the module takes

If a file would not have any contents, it should not exist since there's no need for empty files.

Examples and Testing

All modules need an example file. This example is also used for testing. The example file should live at the path examples/<module-path>.tf where any / in the module path is substituted for -.

Within the example file, invoke the module using a local source path but also include a commented out source of the Github URL. This allows running the tests to always check the configuration you're currently looking at but also tell users how to import the module in their repo.

The module should be named <module-path>-example. If you need multiple test cases and examples, append a description of what is unique about that test case to the end of the above name.

To test and make sure that all modules work properly, run make plan.

terraform-docs

Module documentation can be auto-generated from variable and output definitions using terraform-docs.

terraform-docs markdown --no-requirements <path-to-module>