github.com/hugorut/terraform@v1.1.3/website/docs/language/modules/syntax.mdx (about)

     1  ---
     2  page_title: Modules - Configuration Language
     3  description: >-
     4    Modules are containers for multiple resources that are used together in
     5    configurations. Learn how to call one module from another and access module
     6    output.
     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](/language/modules/develop).
    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](/language/values/variables). 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](/language/values/variables)
    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](/language/modules/sources).
    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](/language/expressions/version-constraints).
    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](/cloud-docs/registry).
   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](/language/meta-arguments/count)
   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](/language/meta-arguments/for_each)
   125    for details.
   126  
   127  - `providers` - Passes provider configurations to a child module. See
   128    [the `providers` page](/language/meta-arguments/module-providers)
   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](/language/meta-arguments/depends_on)
   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](/language/values/outputs) 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](/language/expressions).
   161  
   162  ## Transferring Resource State Into Modules
   163  
   164  Moving `resource` blocks from one module into several child modules causes
   165  Terraform to see the new location as an entirely different resource. As a
   166  result, Terraform plans to destroy all resource instances at the old address
   167  and create new instances at the new address.
   168  
   169  To preserve existing objects, you can use
   170  [refactoring blocks](/language/modules/develop/refactoring) to record the old and new
   171  addresses for each resource instance. This directs Terraform to treat existing
   172  objects at the old addresses as if they had originally been created at the
   173  corresponding new addresses.
   174  
   175  ## Replacing resources within a module
   176  
   177  You may have an object that needs to be replaced with a new object for a reason
   178  that isn't automatically visible to Terraform, such as if a particular virtual
   179  machine is running on degraded underlying hardware. In this case, you can use
   180  [the `-replace=...` planning option](/cli/commands/plan#replace-address)
   181  to force Terraform to propose replacing that object.
   182  
   183  If the object belongs to a resource within a nested module, specify the full
   184  path to that resource including all of the nested module steps leading to it.
   185  For example:
   186  
   187  ```shellsession
   188  $ terraform plan -replace=module.example.aws_instance.example
   189  ```
   190  
   191  The above selects a `resource "aws_instance" "example"` declared inside a
   192  `module "example"` child module declared inside your root module.
   193  
   194  Because replacing is a very disruptive action, Terraform only allows selecting
   195  individual resource instances. There is no syntax to force replacing _all_
   196  resource instances belonging to a particular module.