First docs for count/for_each on modules

This commit is contained in:
Pam Selle 2020-04-10 15:11:27 -04:00
parent 534ba630e4
commit 65c4ba9c85
2 changed files with 47 additions and 31 deletions

View File

@ -155,7 +155,7 @@ described in more detail in other sections:
If not specified, the child module inherits all of the default (un-aliased)
provider configurations from the calling module.
In addition to the above, the argument names `count`, `for_each` and
In addition to the above, the argument names `depends_on` and
`lifecycle` are not currently used by Terraform but are reserved for planned
future features.
@ -361,25 +361,23 @@ setting inside a `terraform` block.
## Multiple Instances of a Module
A particular module source can be instantiated multiple times:
Use the `count` or `for_each` arguments to create multiple instances of a module.
These arguments have the same syntax and type constraints as
[`count`](./resources.html#count-multiple-resource-instances-by-count) and
[`for_each`](./resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings)
as defined for managed resources.
```hcl
# my_buckets.tf
module "assets_bucket" {
module "bucket" {
for_each = toset(["assets", "media"])
source = "./publish_bucket"
name = "assets"
}
module "media_bucket" {
source = "./publish_bucket"
name = "media"
name = "${each.key}_bucket"
}
```
```hcl
# publish_bucket/bucket-and-cloudfront.tf
variable "name" {} # this is the input parameter of the module
resource "aws_s3_bucket" "example" {
@ -396,18 +394,23 @@ subdirectory. That module has configuration to create an S3 bucket. The module
wraps the bucket and all the other implementation details required to configure
a bucket.
We can then instantiate the module multiple times in our configuration by
giving each instance a unique name -- here `module "assets_bucket"` and
`module "media_bucket"` -- whilst specifying the same `source` value.
We declare multiple module instances by using the `for_each` attribute,
which accepts a map (with string keys) or a set of strings as its value. Additionally,
we use the `each.key` in our module block, because the
[`each`](/docs/configuration/resources.html#the-each-object) object is available when
we have declared `for_each` on the module block. When using the `count` argument, the
[`count`](/docs/configuration/resources.html#the-count-object) object is available.
Resources from child modules are prefixed with `module.<module-instance-name>`
when displayed in plan output and elsewhere in the UI. For example, the
`./publish_bucket` module contains `aws_s3_bucket.example`, and so the two
instances of this module produce S3 bucket resources with [_resource addresses_](/docs/internals/resource-addressing.html)
`module.assets_bucket.aws_s3_bucket.example` and `module.media_bucket.aws_s3_bucket.example`
respectively. These full addresses are used within the UI and on the command
line, but are not valid within interpolation expressions due to the
encapsulation behavior described above.
Resources from child modules are prefixed with `module.module_name[module index]`
when displayed in plan output and elsewhere in the UI. For a module with without
`count` or `for_each`, the address will not contain the module index as the module's
name suffices to reference the module.
In our example, the `./publish_bucket` module contains `aws_s3_bucket.example`, and so the two
instances of this module produce S3 bucket resources with [resource addresses](/docs/internals/resource-addressing.html) of `module.bucket["assets"].aws_s3_bucket.example`
and `module.bucket["media"].aws_s3_bucket.example` respectively. These full addresses
are used within the UI and on the command line, but only [outputs](docs/configuration/outputs.html)
from a module can be referenced from elsewhere in your configuration.
When refactoring an existing configuration to introduce modules, moving
resource blocks between modules causes Terraform to see the new location
@ -416,9 +419,8 @@ after performing such actions to ensure that no resources are surprisingly
deleted.
Each instance of a module may optionally have different providers passed to it
using the `providers` argument described above. This can be useful in situations
where, for example, a duplicated set of resources must be created across
several regions or datacenters.
using the [`providers`](/docs/configuration/modules.html#passing-providers-explicitly)
argument. This can be useful in situations where, for example, a duplicated set of resources must be created across several regions or datacenters.
## Tainting resources within a module

View File

@ -21,12 +21,24 @@ __Module path__:
A module path addresses a module within the tree of modules. It takes the form:
```
module.A.module.B.module.C...
module.module_name[module index]
```
Multiple modules in a path indicate nesting. If a module path is specified
without a resource spec, the address applies to every resource within the
module. If the module path is omitted, this addresses the root module.
* `module` - Module keyword indicating a child module (non-root). Multiple `module`
keywords in a path indicate nesting.
* `module_name` - User-defined name of the module.
* `[module index]` - (Optional) Index into a module with multiple
instances, surrounded by square brace characters (`[` and `]`).
An address without a resource spec, i.e. `module.foo` applies to every resource within
the module if a single module, or all instances of a module if a module has multiple instances.
To address all resources of a particular module instance, include the module index in the address,
such as `module.foo[0]`.
If the module path is omitted, the address applies to the root module.
-> Module index only applies to modules in Terraform v0.13 or later, as in earlier
versions of Terraform, a module could not have multiple instances.
__Resource spec__:
@ -38,7 +50,7 @@ resource_type.resource_name[resource index]
* `resource_type` - Type of the resource being addressed.
* `resource_name` - User-defined name of the resource.
* `[resource index]` - an optional index into a resource with multiple
* `[resource index]` - (Optional) Index into a resource with multiple
instances, surrounded by square brace characters (`[` and `]`).
-> In Terraform v0.12 and later, a resource spec without a module path prefix
@ -46,7 +58,9 @@ matches only resources in the root module. In earlier versions, a resource spec
without a module path prefix will match resources with the same type and name
in any descendent module.
__Resource index__:
__Index values for Modules and Resources__:
The following specifications apply to index values on modules and resources with multiple instances:
* `[N]` where `N` is a `0`-based numerical index into a resource with multiple
instances specified by the `count` meta-argument. Omitting an index when