website: standard module structure
This commit is contained in:
parent
bf7f4d243d
commit
0718e9ce3f
|
@ -95,6 +95,98 @@ The [get command](/docs/commands/get.html) will automatically get all nested mod
|
|||
|
||||
You don't have to worry about conflicting versions of modules, since Terraform builds isolated subtrees of all dependencies. For example, one module might use version 1.0 of module `foo` and another module might use version 2.0, and this will all work fine within Terraform since the modules are created separately.
|
||||
|
||||
## Standard Structure
|
||||
## Standard Module Structure
|
||||
|
||||
TODO
|
||||
The standard module structure is a file and folder layout we recommend for
|
||||
reusable modules. Terraform tooling is built to understand the standard
|
||||
module structure and use that structure to generate documentation, index
|
||||
modules for the registry, and more.
|
||||
|
||||
The standard module expects the structure documented below. The list may appear
|
||||
long, but everything is optional except for the root module. All items are
|
||||
documented in detail. Most modules don't need to do any work to follow the
|
||||
standard structure.
|
||||
|
||||
* **Root module**. This is the **only required element** for the standard
|
||||
module structure. Terraform files must exist in the root directory of
|
||||
the module. This should be the primary entrypoint for the module and is
|
||||
expected to be opinionated. For the
|
||||
[Consul module](#)
|
||||
the root module sets up a complete Consul cluster. A lot of assumptions
|
||||
are made, however, and it is fully expected that advanced users will use
|
||||
specific nested modules to more carefully control what they want.
|
||||
|
||||
* **README**. The root module and any nested modules should have README
|
||||
files. This file should be named `README` or `README.md`. The latter will
|
||||
be treated as markdown. The README doesn't need to document inputs or
|
||||
outputs of the module because tooling will automatically generate this.
|
||||
|
||||
|
||||
* **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 all nested module usage 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. See the documentation for
|
||||
[variable configuration](/docs/configuration/variables.html) and
|
||||
[output configuration](/docs/configuration/outputs.html) for more details.
|
||||
|
||||
* **Nested modules**. Nested modules should exist under the `modules/`
|
||||
subdirectory. Any nested module with a `README.md` is considered usable
|
||||
by an external user. If a README doesn't exist, it is considered for internal
|
||||
use only. These are purely advisory; Terraform will not actively deny usage
|
||||
of internal modules. Nested modules should be used to split complex behavior
|
||||
into multiple small modules that advanced users can carefully pick and
|
||||
choose. For example, the
|
||||
[Consul module](#)
|
||||
has a nested module for creating the Cluster that is separate from the
|
||||
module to setup necessary IAM policies. This allows a user to bring in their
|
||||
own IAM policy choices.
|
||||
|
||||
* **Examples**. Examples of using the module should exist under the
|
||||
`examples/` subdirectory. Each example may have a README to explain the
|
||||
goal and usage of the example.
|
||||
|
||||
A minimal recommended module following the standard structure is shown below.
|
||||
While the root module is the only required element, we recommend below as
|
||||
a minimum structure:
|
||||
|
||||
```sh
|
||||
$ tree minimal-module/
|
||||
.
|
||||
├── README.md
|
||||
├── main.tf
|
||||
├── variables.tf
|
||||
├── outputs.tf
|
||||
```
|
||||
|
||||
A complete example of a module following the standard structure is shown below.
|
||||
This example includes all optional elements and is therefore the most
|
||||
complex a module can become:
|
||||
|
||||
```sh
|
||||
$ tree complete-module/
|
||||
.
|
||||
├── README.md
|
||||
├── main.tf
|
||||
├── variables.tf
|
||||
├── outputs.tf
|
||||
├── ...
|
||||
├── modules/
|
||||
│ ├── nestedA/
|
||||
│ │ ├── variables.tf
|
||||
│ │ ├── main.tf
|
||||
│ │ ├── outputs.tf
|
||||
│ ├── nestedB/
|
||||
│ ├── .../
|
||||
├── examples/
|
||||
│ ├── exampleA/
|
||||
│ │ ├── main.tf
|
||||
│ ├── exampleB/
|
||||
│ ├── .../
|
||||
```
|
||||
|
|
Loading…
Reference in New Issue