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