Terraform Module Best Practices
Follow Official Conventions
Following official conventions is especially important if the module will ever be published to the terraform module registry. Either way, we suggest following these conventions to create more standardized/portable modules.
Use GitHub. For public modules that you intend to publish to the public registry, the module repos must be hosted on GitHub as a public repo.
User Proper Naming. Module repository names must follow the
terraform-$PROVIDER-$NAMEnaming convention, where
$NAMEis a descriptive label for the kind of infrastructure that is provisioned, and
$PROVIDERis the primary provider provisioning the infrastructure (e.g.
aws). Use hyphens (
-) to separate all fields. Do not use underscores (
Repository description. The GitHub repository description is used to populate the short description of the module. This should be a simple one sentence description of the module.
Standard Module Structure. The module must follow the standard module structure. This makes it easier for others to jump in and contribute, but is also a requirement for publishing modules to the registry. The registry will inspect the module and generate documentation automatically from
outputdeclarations, track resource usage, parse submodules and examples, and more.
Use Semantic Versioning. Every release should have a tag in the
x.y.zformat. The registry will use the repository’s tags to identify module versions. Use semantic versions for tagged releases. Tags may be optionally prefixed with a
Root Module Pattern
This refers to the “root” or top-level invocation of terraform modules. We provide examples of these on our
This is a DRY pattern that allows module invocations to be easily versioned and copied between geodesic modules by leveraging docker’s multi-stage-builds (e.g.