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  ```