Standard Module Structure

The standard module structure is a file and directory layout we recommend for reusable modules distributed in separate repositories. Terraform tooling is built to understand the standard module structure and use that structure to generate documentation, index modules for the module registry, and more.

The standard module structure expects the layout documented below.

  • Root module. Terraform files must exist in the root directory of the repository. This should be the primary entrypoint for the module and is expected to be opinionated.

  • README. The root module and any nested modules should have README files. This file should be named readme.md. There should be a description of the module and what it should be used for. More detailed examples should be put it in an examples directory. Consider including a visual diagram depicting the infrastructure resources the module may create and their relationship. Here is an example of what a readme file should look like.

  • main.tf, variables.tf, outputs.tf. These are the recommended filenames for a minimal module, even if they’re empty. main.tf should be the primary entrypoint. For a simple module, this may be where all the resources are created. For a complex module, resource creation may be split into multiple files but any nested module calls should be in the main file. variables.tf and outputs.tf should contain the declarations for variables and outputs, respectively.

  • Variables and outputs should have descriptions. All variables and outputs should have one or two sentence descriptions that explain their purpose. This is used for documentation.

  • Examples. Detailed examples of using the module should exist under the examples/ subdirectory at the root of the repository. Each example may have a README to explain the goal and usage of the example. Examples for submodules should also be placed in the root examples/ directory.

    Because examples will often be copied into other repositories for customization, any module blocks should have their source set to the address an external caller would use, not to a relative path.

A minimal recommended module following the standard structure is shown below. While the root module is the only required element, we recommend the structure below as the minimum:

$ tree minimal-module/
.
├── readme.md
├── main.tf
├── variables.tf
├── outputs.tf