github.com/jaredpalmer/terraform@v1.1.0-alpha20210908.0.20210911170307-88705c943a03/website/docs/language/modules/syntax.html.md (about)

     1  ---
     2  layout: "language"
     3  page_title: "Modules - Configuration Language"
     4  sidebar_current: "docs-config-modules"
     5  description: "Modules are containers for multiple resources that are used together in configurations. Learn how to call one module from another and access module output."
     6  ---
     7  
     8  # Module Blocks
     9  
    10  > **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.
    11  
    12  A _module_ is a container for multiple resources that are used together.
    13  
    14  Every Terraform configuration has at least one module, known as its
    15  _root module_, which consists of the resources defined in the `.tf` files in
    16  the main working directory.
    17  
    18  A module can call other modules, which lets you include the child module's
    19  resources into the configuration in a concise way. Modules
    20  can also be called multiple times, either within the same configuration or
    21  in separate configurations, allowing resource configurations to be packaged
    22  and re-used.
    23  
    24  This page describes how to call one module from another. For more information
    25  about creating re-usable child modules, see [Module Development](/docs/language/modules/develop/index.html).
    26  
    27  ## Calling a Child Module
    28  
    29  To _call_ a module means to include the contents of that module into the
    30  configuration with specific values for its
    31  [input variables](/docs/language/values/variables.html). Modules are called
    32  from within other modules using `module` blocks:
    33  
    34  ```hcl
    35  module "servers" {
    36    source = "./app-cluster"
    37  
    38    servers = 5
    39  }
    40  ```
    41  
    42  A module that includes a `module` block like this is the _calling module_ of the
    43  child module.
    44  
    45  The label immediately after the `module` keyword is a local name, which the
    46  calling module can use to refer to this instance of the module.
    47  
    48  Within the block body (between `{` and `}`) are the arguments for the module.
    49  Module calls use the following kinds of arguments:
    50  
    51  - The `source` argument is mandatory for all modules.
    52  
    53  - The `version` argument is recommended for modules from a registry.
    54  
    55  - Most other arguments correspond to [input variables](/docs/language/values/variables.html)
    56    defined by the module. (The `servers` argument in the example above is one of
    57    these.)
    58  
    59  - Terraform defines a few other meta-arguments that can be used with all
    60    modules, including `for_each` and `depends_on`.
    61  
    62  ### Source
    63  
    64  All modules **require** a `source` argument, which is a meta-argument defined by
    65  Terraform. Its value is either the path to a local directory containing the
    66  module's configuration files, or a remote module source that Terraform should
    67  download and use. This value must be a literal string with no template
    68  sequences; arbitrary expressions are not allowed. For more information on
    69  possible values for this argument, see [Module Sources](/docs/language/modules/sources.html).
    70  
    71  The same source address can be specified in multiple `module` blocks to create
    72  multiple copies of the resources defined within, possibly with different
    73  variable values.
    74  
    75  After adding, removing, or modifying `module` blocks, you must re-run
    76  `terraform init` to allow Terraform the opportunity to adjust the installed
    77  modules. By default this command will not upgrade an already-installed module;
    78  use the `-upgrade` option to instead upgrade to the newest available version.
    79  
    80  ### Version
    81  
    82  When using modules installed from a module registry, we recommend explicitly
    83  constraining the acceptable version numbers to avoid unexpected or unwanted
    84  changes.
    85  
    86  Use the `version` argument in the `module` block to specify versions:
    87  
    88  ```shell
    89  module "consul" {
    90    source  = "hashicorp/consul/aws"
    91    version = "0.0.5"
    92  
    93    servers = 3
    94  }
    95  ```
    96  
    97  The `version` argument accepts a [version constraint string](/docs/language/expressions/version-constraints.html).
    98  Terraform will use the newest installed version of the module that meets the
    99  constraint; if no acceptable versions are installed, it will download the newest
   100  version that meets the constraint.
   101  
   102  Version constraints are supported only for modules installed from a module
   103  registry, such as the public [Terraform Registry](https://registry.terraform.io/)
   104  or [Terraform Cloud's private module registry](/docs/cloud/registry/index.html).
   105  Other module sources can provide their own versioning mechanisms within the
   106  source string itself, or might not support versions at all. In particular,
   107  modules sourced from local file paths do not support `version`; since
   108  they're loaded from the same source repository, they always share the same
   109  version as their caller.
   110  
   111  ### Meta-arguments
   112  
   113  Along with `source` and `version`, Terraform defines a few more
   114  optional meta-arguments that have special meaning across all modules,
   115  described in more detail in the following pages:
   116  
   117  - `count` - Creates multiple instances of a module from a single `module` block.
   118    See [the `count` page](/docs/language/meta-arguments/count.html)
   119    for details.
   120  
   121  - `for_each` - Creates multiple instances of a module from a single `module`
   122    block. See
   123    [the `for_each` page](/docs/language/meta-arguments/for_each.html)
   124    for details.
   125  
   126  - `providers` - Passes provider configurations to a child module. See
   127    [the `providers` page](/docs/language/meta-arguments/module-providers.html)
   128    for details. If not specified, the child module inherits all of the default
   129    (un-aliased) provider configurations from the calling module.
   130  
   131  - `depends_on` - Creates explicit dependencies between the entire
   132    module and the listed targets. See
   133    [the `depends_on` page](/docs/language/meta-arguments/depends_on.html)
   134    for details.
   135  
   136  In addition to the above, the `lifecycle` argument is not currently used by
   137  Terraform but is reserved for planned future features.
   138  
   139  ## Accessing Module Output Values
   140  
   141  The resources defined in a module are encapsulated, so the calling module
   142  cannot access their attributes directly. However, the child module can
   143  declare [output values](/docs/language/values/outputs.html) to selectively
   144  export certain values to be accessed by the calling module.
   145  
   146  For example, if the `./app-cluster` module referenced in the example above
   147  exported an output value named `instance_ids` then the calling module
   148  can reference that result using the expression `module.servers.instance_ids`:
   149  
   150  ```hcl
   151  resource "aws_elb" "example" {
   152    # ...
   153  
   154    instances = module.servers.instance_ids
   155  }
   156  ```
   157  
   158  For more information about referring to named values, see
   159  [Expressions](/docs/language/expressions/index.html).
   160  
   161  ## Transferring Resource State Into Modules
   162  
   163  When refactoring an existing configuration to split code into child modules,
   164  moving resource blocks between modules causes Terraform to see the new location
   165  as an entirely different resource from the old. Always check the execution plan
   166  after moving code across modules to ensure that no resources are deleted by
   167  surprise.
   168  
   169  If you want to make sure an existing resource is preserved, use
   170  [the `terraform state mv` command](/docs/cli/commands/state/mv.html) to inform
   171  Terraform that it has moved to a different module.
   172  
   173  When passing resource addresses to `terraform state mv`, resources within child
   174  modules must be prefixed with `module.<MODULE NAME>.`. If a module was called with
   175  [`count`](/docs/language/meta-arguments/count.html) or
   176  [`for_each`](/docs/language/meta-arguments/for_each.html),
   177  its resource addresses must be prefixed with `module.<MODULE NAME>[<INDEX>].`
   178  instead, where `<INDEX>` matches the `count.index` or `each.key` value of a
   179  particular module instance.
   180  
   181  Full resource addresses for module contents are used within the UI and on the
   182  command line, but cannot be used within a Terraform configuration. Only
   183  [outputs](/docs/language/values/outputs.html) from a module can be referenced from
   184  elsewhere in your configuration.
   185  
   186  ## Tainting resources within a module
   187  
   188  The [taint command](/docs/cli/commands/taint.html) can be used to _taint_ specific
   189  resources within a module:
   190  
   191  ```shell
   192  $ terraform taint module.salt_master.aws_instance.salt_master
   193  ```
   194  
   195  It is not possible to taint an entire module. Instead, each resource within
   196  the module must be tainted separately.