Table of contents
Open Table of contents
Intro
⚠️ 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:
- Azure Virtual Network module for PaaS resources: creates the virtual network with subnets configured for Private endpoints, DNS and VNet peering. Does not create Resource Groups, Route Tables, Network Security Groups, etc. but depends on them instead.
- Linux Virtual machine module: Creates Virtual machine, disks, optional managed identity, network interface card and the required associations. Does not create/configure patching, backups, virtual networks or subnets, NSGs etc., these are handled elsewhere.
- Private Azure Linux Function module: Creates service plan for Linux functions, Function app, subnet association, private endpoint & private DNS record, optional managed identity and the required private Storage Account. Does not deploy the functions themselves, or create full private DNS zones.
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.