github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/language/modules/develop/index.html.md (about)

     1  ---
     2  layout: "language"
     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  > **Hands-on:** Try the [Reuse Configuration with Modules](https://learn.hashicorp.com/collections/terraform/modules?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
    12  
    13  A _module_ is a container for multiple resources that are used together.
    14  Modules can be used to create lightweight abstractions, so that you can
    15  describe your infrastructure in terms of its architecture, rather than
    16  directly in terms of physical objects.
    17  
    18  The `.tf` files in your working directory when you run [`terraform plan`](/docs/cli/commands/plan.html)
    19  or [`terraform apply`](/docs/cli/commands/apply.html) together form the _root_
    20  module. That module may [call other modules](/docs/language/modules/syntax.html#calling-a-child-module)
    21  and connect them together by passing output values from one to input values
    22  of another.
    23  
    24  To learn how to _use_ modules, see [the Modules configuration section](/docs/language/modules/index.html).
    25  This section is about _creating_ re-usable modules that other configurations
    26  can include using `module` blocks.
    27  
    28  ## Module structure
    29  
    30  Re-usable modules are defined using all of the same
    31  [configuration language](/docs/language/index.html) concepts we use in root modules.
    32  Most commonly, modules use:
    33  
    34  * [Input variables](/docs/language/values/variables.html) to accept values from
    35    the calling module.
    36  * [Output values](/docs/language/values/outputs.html) to return results to the
    37    calling module, which it can then use to populate arguments elsewhere.
    38  * [Resources](/docs/language/resources/index.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