Skip to content

Better Terraform modules with five good practices

Updated: | 3 min read

Table of contents

Open Table of contents


⚠️ Warning! Contains opinions which may differ from yours. ⚠️

During the years I have used Terraform and also developed modules, these are the five things I think will make your modules easier to use and maintain.

1. Small opinionated modules

Instead of creating all-encompassing modules, which cater each and every use case, but require vast number of parameters to be set correctly, create small, opinionated modules. Cater only relatively small number of very similar use cases. Do not expose every single parameter which are available in the underlying resources to your module users, but have an opinion how they should be configured and set them as static values.

This will lead to relatively small number of available parameters, makes the module development and testing much easier, and expecially makes your module easy to use for your users. Examples of small opinionated modules:

2. Don’t let scope creep take over

Keep your modules small by limiting the scope, and having opinions how they behave. Don’t keep adding things to your module without careful consideration of the pros and cons.

3. Design the module interface carefully

Your module interface, i.e. its inputs and outputs, deserves careful design upfront and iteration before locking the design for the first release. What are the bare minimum required input parameters? Which input parameters are optional and which should not be exposed to users at all?

What data should be exposed as outputs, and how the outputs should be structured?

Most likely your first ideas are not that great, and you should spend enough time testing different designs with external users.

4. Use semantic versioning and maintain changelog

Your modules’ users need an easy way to track changes. Do not reinvent the wheel but use Semantic versioning. Publish a standard structured CHANGELOG of the changes to your modules. Plan for old version deprecation and communicate this with your users through the changelog.

5. Maintain documentation and working examples

It is paramount that your module has sufficient documentation how to use your module, with working and up-to-date deployable example code.