github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/modules/index.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "Creating Modules" 4 sidebar_current: "docs-modules" 5 description: |- 6 A module is a container for multiple resources that are used together. 7 --- 8 9 # Creating Modules 10 11 A _module_ is a container for multiple resources that are used together. 12 Modules can be used to create lightweight abstractions, so that you can 13 describe your infrastructure in terms of its architecture, rather than 14 directly in terms of physical objects. 15 16 The `.tf` files in your working directory when you run [`terraform plan`](/docs/commands/plan.html) 17 or [`terraform apply`](/docs/commands/apply.html) together form the _root_ 18 module. That module may [call other modules](/docs/configuration/modules.html#calling-a-child-module) 19 and connect them together by passing output values from one to input values 20 of another. 21 22 To learn how to _use_ modules, see [the Modules configuration section](/docs/configuration/modules.html). 23 This section is about _creating_ re-usable modules that other configurations 24 can include using `module` blocks. 25 26 You can also learn more about how to use and create modules with our hands-on [modules track on learn.hashicorp.com](https://learn.hashicorp.com/terraform/modules/modules-overview?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). 27 28 ## Module structure 29 30 Re-usable modules are defined using all of the same 31 [configuration language](/docs/configuration/) concepts we use in root modules. 32 Most commonly, modules use: 33 34 * [Input variables](/docs/configuration/variables.html) to accept values from 35 the calling module. 36 * [Output values](/docs/configuration/outputs.html) to return results to the 37 calling module, which it can then use to populate arguments elsewhere. 38 * [Resources](/docs/configuration/resources.html) to define one or more 39 infrastructure objects that the module will manage. 40 41 To define a module, create a new directory for it and place one or more `.tf` 42 files inside just as you would do for a root module. Terraform can load modules 43 either from local relative paths or from remote repositories; if a module will 44 be re-used by lots of configurations you may wish to place it in its own 45 version control repository. 46 47 Modules can also call other modules using a `module` block, but we recommend 48 keeping the module tree relatively flat and using [module composition](./composition.html) 49 as an alternative to a deeply-nested tree of modules, because this makes 50 the individual modules easier to re-use in different combinations. 51 52 ## When to write a module 53 54 In principle any combination of resources and other constructs can be factored 55 out into a module, but over-using modules can make your overall Terraform 56 configuration harder to understand and maintain, so we recommend moderation. 57 58 A good module should raise the level of abstraction by describing a new concept 59 in your architecture that is constructed from resource types offered by 60 providers. 61 62 For example, `aws_instance` and `aws_elb` are both resource types belonging to 63 the AWS provider. You might use a module to represent the higher-level concept 64 "[HashiCorp Consul](https://www.consul.io/) cluster running in AWS" which 65 happens to be constructed from these and other AWS provider resources. 66 67 We _do not_ recommend writing modules that are just thin wrappers around single 68 other resource types. If you have trouble finding a name for your module that 69 isn't the same as the main resource type inside it, that may be a sign that 70 your module is not creating any new abstraction and so the module is 71 adding unnecessary complexity. Just use the resource type directly in the 72 calling module instead. 73 74 ## Standard Module Structure 75 76 The standard module structure is a file and directory layout we recommend for 77 reusable modules distributed in separate repositories. Terraform tooling is 78 built to understand the standard module structure and use that structure to 79 generate documentation, index modules for the module registry, and more. 80 81 The standard module structure expects the layout documented below. The list may 82 appear long, but everything is optional except for the root module. Most modules 83 don't need to do any extra work to follow the standard structure. 84 85 * **Root module**. This is the **only required element** for the standard 86 module structure. Terraform files must exist in the root directory of 87 the repository. This should be the primary entrypoint for the module and is 88 expected to be opinionated. For the 89 [Consul module](https://registry.terraform.io/modules/hashicorp/consul) 90 the root module sets up a complete Consul cluster. It makes a lot of assumptions 91 however, and we expect that advanced users will use specific _nested modules_ 92 to more carefully control what they want. 93 94 * **README**. The root module and any nested modules should have README 95 files. This file should be named `README` or `README.md`. The latter will 96 be treated as markdown. There should be a description of the module and 97 what it should be used for. If you want to include an example for how this 98 module can be used in combination with other resources, put it in an [examples 99 directory like this](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples). 100 Consider including a visual diagram depicting the infrastructure resources 101 the module may create and their relationship. 102 103 The README doesn't need to document inputs or outputs of the module because 104 tooling will automatically generate this. If you are linking to a file or 105 embedding an image contained in the repository itself, use a commit-specific 106 absolute URL so the link won't point to the wrong version of a resource in the 107 future. 108 109 * **LICENSE**. The license under which this module is available. If you are 110 publishing a module publicly, many organizations will not adopt a module 111 unless a clear license is present. We recommend always having a license 112 file, even if it is not an open source license. 113 114 * **`main.tf`, `variables.tf`, `outputs.tf`**. These are the recommended filenames for 115 a minimal module, even if they're empty. `main.tf` should be the primary 116 entrypoint. For a simple module, this may be where all the resources are 117 created. For a complex module, resource creation may be split into multiple 118 files but any nested module calls should be in the main file. `variables.tf` 119 and `outputs.tf` should contain the declarations for variables and outputs, 120 respectively. 121 122 * **Variables and outputs should have descriptions.** All variables and 123 outputs should have one or two sentence descriptions that explain their 124 purpose. This is used for documentation. See the documentation for 125 [variable configuration](/docs/configuration/variables.html) and 126 [output configuration](/docs/configuration/outputs.html) for more details. 127 128 * **Nested modules**. Nested modules should exist under the `modules/` 129 subdirectory. Any nested module with a `README.md` is considered usable 130 by an external user. If a README doesn't exist, it is considered for internal 131 use only. These are purely advisory; Terraform will not actively deny usage 132 of internal modules. Nested modules should be used to split complex behavior 133 into multiple small modules that advanced users can carefully pick and 134 choose. For example, the 135 [Consul module](https://registry.terraform.io/modules/hashicorp/consul) 136 has a nested module for creating the Cluster that is separate from the 137 module to setup necessary IAM policies. This allows a user to bring in their 138 own IAM policy choices. 139 140 If the root module includes calls to nested modules, they should use relative 141 paths like `./modules/consul-cluster` so that Terraform will consider them 142 to be part of the same repository or package, rather than downloading them 143 again separately. 144 145 If a repository or package contains multiple nested modules, they should 146 ideally be [composable](./composition.html) by the caller, rather than 147 calling directly to each other and creating a deeply-nested tree of modules. 148 149 * **Examples**. Examples of using the module should exist under the 150 `examples/` subdirectory at the root of the repository. Each example may have 151 a README to explain the goal and usage of the example. Examples for 152 submodules should also be placed in the root `examples/` directory. 153 154 Because examples will often be copied into other repositories for 155 customization, any `module` blocks should have their `source` set to the 156 address an external caller would use, not to a relative path. 157 158 A minimal recommended module following the standard structure is shown below. 159 While the root module is the only required element, we recommend the structure 160 below as the minimum: 161 162 ```sh 163 $ tree minimal-module/ 164 . 165 ├── README.md 166 ├── main.tf 167 ├── variables.tf 168 ├── outputs.tf 169 ``` 170 171 A complete example of a module following the standard structure is shown below. 172 This example includes all optional elements and is therefore the most 173 complex a module can become: 174 175 ```sh 176 $ tree complete-module/ 177 . 178 ├── README.md 179 ├── main.tf 180 ├── variables.tf 181 ├── outputs.tf 182 ├── ... 183 ├── modules/ 184 │ ├── nestedA/ 185 │ │ ├── README.md 186 │ │ ├── variables.tf 187 │ │ ├── main.tf 188 │ │ ├── outputs.tf 189 │ ├── nestedB/ 190 │ ├── .../ 191 ├── examples/ 192 │ ├── exampleA/ 193 │ │ ├── main.tf 194 │ ├── exampleB/ 195 │ ├── .../ 196 ```