github.com/pulumi/terraform@v1.4.0/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) tutorials.
    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  Terraform does not use the `lifecycle` argument. However, the `lifecycle` block is reserved for future versions.
   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](/language/values/outputs) 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](/language/expressions).
   160  
   161  ## Transferring Resource State Into Modules
   162  
   163  Moving `resource` blocks from one module into several child modules causes
   164  Terraform to see the new location as an entirely different resource. As a
   165  result, Terraform plans to destroy all resource instances at the old address
   166  and create new instances at the new address.
   167  
   168  To preserve existing objects, you can use
   169  [refactoring blocks](/language/modules/develop/refactoring) to record the old and new
   170  addresses for each resource instance. This directs Terraform to treat existing
   171  objects at the old addresses as if they had originally been created at the
   172  corresponding new addresses.
   173  
   174  ## Replacing resources within a module
   175  
   176  You may have an object that needs to be replaced with a new object for a reason
   177  that isn't automatically visible to Terraform, such as if a particular virtual
   178  machine is running on degraded underlying hardware. In this case, you can use
   179  [the `-replace=...` planning option](/cli/commands/plan#replace-address)
   180  to force Terraform to propose replacing that object.
   181  
   182  If the object belongs to a resource within a nested module, specify the full
   183  path to that resource including all of the nested module steps leading to it.
   184  For example:
   185  
   186  ```shellsession
   187  $ terraform plan -replace=module.example.aws_instance.example
   188  ```
   189  
   190  The above selects a `resource "aws_instance" "example"` declared inside a
   191  `module "example"` child module declared inside your root module.
   192  
   193  Because replacing is a very disruptive action, Terraform only allows selecting
   194  individual resource instances. There is no syntax to force replacing _all_
   195  resource instances belonging to a particular module.