Meta-Arguments: count, for_each and depends_on

Inside a block that uses count there is exactly one extra named value: count.index, a zero-based number. It can be used in any argument of the block, including nested blocks, provisioner blocks and connection blocks (where self refers to the instance). count.index is not available outside the block, and other blocks reach an instance only through its address.

A block that uses count is a list in expressions, so the usual list syntax applies.

Source: Terraform Docs — Splat expressions and Terraform Docs — The count meta-argument.

docker_container.catalog_api[*].name is the splat form of the for expression in the last output. When catalog_api_replicas is zero the list is empty and both forms return an empty list, but docker_container.catalog_api[0].name fails because the instance does not exist. That is why the "zero or one" idiom below always indexes with care.

The most common use of count is not repetition at all but a conditional resource: a value of 1 creates the resource and 0 removes it.

Source: Terraform Docs — The count meta-argument and Terraform Docs — one function.

Two details make this idiom comfortable. A resource that is behind count must always be indexed, even when only one instance can exist (docker_image.redis[0]), and a resource that depends on a conditional one must be conditional too, otherwise the reference docker_image.redis[0] fails when Redis is disabled. The one() function converts the list of zero or one elements into either null or the single object, which keeps outputs from exploding. OpenTofu 1.11 added a dedicated enabled argument inside lifecycle for exactly this case (see [terraform-and-opentofu-differences]).

count = length(var.services) is a very common way to repeat a block once per element of a list, and it is exactly where count becomes dangerous; the next sections explain why.

Source: Terraform Docs — The for_each meta-argument.

each is only defined inside the block that declares for_each. If a nested dynamic block needs the outer each, capture it first in a locals value or give the dynamic block an explicit iterator, because dynamic blocks bring their own iterator named after the block label. Within provisioner and connection blocks self refers to the instance and not to the whole resource.

A set is the natural input when there is nothing to say about an element except its name, such as a list of bucket or queue names. HCL has no set literal, so a list is converted with toset().

Source: Terraform Docs — The for_each meta-argument and Terraform Docs — toset function.

for_each does not convert a list or a tuple implicitly. Passing var.service_names directly is an error that says the argument must be a map or set of strings. toset() discards both duplicates and ordering, which is precisely the behaviour you want for identity: reordering the list does not change a single address. A variable declared as set(string) avoids the conversion altogether. When each instance needs different arguments, use a map (as in the previous example) and carry the per-instance data in each.value.

Often the source data is a list of objects. A for expression turns it into a map whose keys are stable names.

Source: Terraform Docs — For expressions and Terraform Docs — The for_each meta-argument.

The key must be unique: the for expression above fails if two objects share a name, which is a useful validation in disguise. Choose keys that describe the thing and do not change (a service name, a region, an environment), not keys built from an attribute that may be edited later, because the key is the identity of the instance.

A resource that uses for_each over another resource that uses for_each inherits its keys. The container resource above reads docker_image.service[each.key]. The same idea works with the whole resource, since a block with for_each is a map of instances:

Source: Terraform Docs — The for_each meta-argument.

Chaining is safe because the keys of docker_container.service are known at plan time, and each instance of the sidecar lives and dies with its counterpart. Only the keys have to be known before apply; each.value may contain attributes that are known only after apply, such as each.value.id. This distinction is the root of the workarounds in Unknown values: known only after apply.

Two levels of repetition, such as "every database of every service", cannot be expressed with a single for_each over a nested structure. Flatten the combinations into one list of objects, give each one a composite key, and iterate over the resulting map.

Source: Terraform Docs — flatten function and Terraform Docs — The for_each meta-argument.

The instances are terraform_data.grant["catalog-api.catalog"], terraform_data.grant["catalog-api.catalog_audit"] and terraform_data.grant["reviews-api.reviews"]. For a full cross product of two independent collections setproduct() returns every pair, and the same composite key technique applies. The functions are introduced in Functions.

for_each and count are available on data sources exactly as on resources, and on module blocks (see Meta-arguments on modules). A data source with for_each is read once per key, which is how a configuration looks up many objects with one block.

Source: Terraform Docs — The for_each meta-argument and Terraform Docs — data block reference.

terraform state list prints one address per line, which makes it the quickest way to see which instances Terraform believes exist. The output below shows the Bookshelf stack of this page after applying the count and for_each examples.

Source: Terraform Docs — terraform state list and Terraform Docs — terraform state show.

Quoting matters in a shell. The double quotes inside a for_each address are consumed by the shell unless the whole address is in single quotes, as above (or each inner quote is escaped with a backslash). In PowerShell and cmd.exe the rules differ again, and the official documentation lists the variants. A bare address such as docker_container.service selects every instance of the block.

The -target option of plan, apply and destroy restricts an operation to one address and the objects it depends on. The address may be a whole block or one instance.

Source: Terraform Docs — terraform plan and Terraform Docs — Resource addressing.

-target is meant for exceptional situations: recovering from an error, or working around an unknown value (see below). Terraform prints a warning after a targeted plan because the rest of the configuration was ignored, so the state can legitimately differ from the configuration afterwards. A routine workflow that depends on -target is a sign that the configuration should be split into smaller root modules. OpenTofu also offers -exclude, the inverse option, which plans everything except the given address and its dependents. The planning options are described in The Dependency Graph and the Plan and the commands in CLI Essentials.

Source: Terraform Docs — The count meta-argument and Terraform Docs — The for_each meta-argument.

The documentation itself gives the same advice: use count when the instances are nearly identical, and use for_each when some of their arguments must have distinct values that cannot be derived from an integer. In practice, default to for_each whenever the instances have names, and keep count for the on/off switch and for truly interchangeable replicas whose number only ever grows or shrinks at the end.

Changing an existing resource from count to for_each changes every address, so a plain edit makes Terraform plan to destroy all the old instances and create all the new ones. The state can be rewritten without touching the infrastructure by declaring a moved block for each instance.

Source: Terraform Docs — moved block reference and Terraform Docs — Refactoring.

The plan then reports has moved to lines instead of destroy and create actions. The older command-line equivalent is terraform state mv with the same addresses, which edits the state immediately and cannot be reviewed in a pull request. Refactoring, including the removed block, is the subject of Refactoring: moved and removed.

When the rule is violated, the plan stops with an error that names the argument and says that it depends on a value that cannot be determined until apply. The text varies a little between versions; these are the usual shapes.

Source: Terraform Docs — The for_each meta-argument.

For count the message is Invalid count argument, with the sentence The "count" value depends on resource attributes that cannot be determined until apply, so Terraform cannot predict how many instances will be created. To work around this, use the -target argument to first apply only the resources that the count depends on. The wording above is reproduced from the behaviour of recent releases in abbreviated form; the documentation pages describe the condition ("dependencies that cannot be determined before apply") without quoting the message, so treat the exact text as indicative.

The distinction that resolves most cases is between the keys of a collection and its values. A for_each map may contain unknown values: they just have to be associated with keys that are known. Compare the two configurations below.

Source: Terraform Docs — The for_each meta-argument.

In good, Terraform knows during planning that two instances exist, terraform_data.good["frontend"] and terraform_data.good["backend"], because the keys of docker_network.created are the static strings from the toset() literal. The input is "known after apply", and that is fine.

Source: Terraform Docs — The for_each meta-argument and Terraform Docs — The count meta-argument.

A frequent trap is count = length(aws_subnet.private[*].id) or for_each = data.some_thing.all.ids over a data source whose result depends on a resource in the same configuration: as soon as the data source’s read is deferred until apply, every consumer fails with the error above. The remedy is the same: derive the repetition from inputs the configuration already knows. Data sources whose configuration is fully known are read during planning (see Resources and Data Sources), and a data source is deferred only when its arguments are unknown or when depends_on names a resource with pending changes.

Keys appear in the plan, in state and in the UI, so Terraform refuses them if they are sensitive. A sensitive map can still drive for_each if the keys are made non-sensitive explicitly.

Source: Terraform Docs — The for_each meta-argument and Terraform Docs — nonsensitive function.

Calling nonsensitive() is a promise that the names themselves are not secret. Do not use it on values whose disclosure matters. OpenTofu 1.8 improved the error message for a for_each over a sensitive value of an unsuitable type.

Terraform 1.17 contains an experimental "deferred actions" feature, available only in alpha builds and enabled with terraform plan -allow-deferral. It lets count and for_each have unknown values by deferring the dependent objects to a later plan, and lets providers react to unknown values. It is not in stable releases, so stable configurations must still follow the rules above.

Source: Terraform CHANGELOG (v1.17).

The documentation calls depends_on a last resort for a reason. With a reference such as docker_image.catalog_api.image_id, Terraform can tell that the dependent object only needs to change when that one attribute changes. With depends_on, the dependent object must be treated as "possibly affected by anything" in the dependency, so the plan tends to be more conservative: more values show as "known after apply", and more objects are planned for update or replacement than strictly necessary. The effect is largest with a whole module as dependency.

Prefer, in this order:

Source: Terraform Docs — The depends_on meta-argument.

Always write a comment next to a depends_on: it is the only record of why the edge exists, and without it the next maintainer cannot tell whether it can be deleted.

A data source is normally read during the plan when its arguments are known, so that the plan can use the result. If a data source declares depends_on on a resource that has pending changes, the read is deferred until the apply, because the dependency must complete first, and every value derived from the data source becomes "known after apply". That can in turn trigger the unknown-value errors from the previous section when the result is used in count or for_each. Therefore, give a data source a depends_on only when it genuinely needs to see changes made during the same run, and prefer arguments that reference the dependency, so that Terraform knows when the read is safe.

The same meta-argument is how a check waits for infrastructure to exist. A data block nested in a check block may use depends_on so the assertion is evaluated after another resource has been created, and until that resource exists Terraform shows a "known after apply" warning rather than a failure.

Source: Terraform Docs — The depends_on meta-argument and Terraform Docs — check block reference.

The http data source belongs to the hashicorp/http provider, declared in required_providers. If the check references the resource directly in its arguments, every change to the resource produces the warning, which makes the check noisy; depends_on is the better choice when the data block does not otherwise reference the resource. Checks are described in Lifecycle, Validation and Checks.

An output rarely needs depends_on, because it normally references the values it exposes. When an output must wait for something that is not part of its value (for example, a module output that is only meaningful once a policy attachment has completed), add depends_on and say why in a comment. The output page covers this in Variables, Outputs and Locals.

A resource that depends on another one is not necessarily replaced when the other one is replaced. Dependencies control ordering, and the changes are driven by differences in arguments. If a container must be recreated when a configuration file changes, a reference alone is not enough; the replace_triggered_by lifecycle argument expresses that relationship explicitly, and it is described in Lifecycle, Validation and Checks.

Source: Terraform Docs — The provider meta-argument.

The value is a reference of the form PROVIDER.ALIAS without quotes. It must be a static reference: Terraform needs it while building the graph, so arbitrary expressions, variables and conditionals are not permitted. This is why a single resource with for_each cannot pick a different provider per key in Terraform. Each resource implicitly depends on its provider, which is fully configured before any action on the resource runs. The provider argument is also valid in data, ephemeral, import, check and list blocks; a list block does not get the implicit default and needs it explicitly.

Everything about provider configuration itself, aliases, authentication and multi-region setups is in Providers.

A child module inherits every default (non-aliased) provider configuration of its caller. It never inherits aliased configurations automatically. The providers argument of a module block changes this: it maps each provider name used inside the module to a configuration of the caller.

Source: Terraform Docs — The providers meta-argument.

Specifying providers cancels the default behavior: the child only receives the configurations listed. When a module needs two configurations of the same provider (for example a source and a destination region), it declares them with configuration_aliases in its own required_providers, and the caller maps both.

Source: Terraform Docs — The providers meta-argument and Terraform Docs — Providers within modules.

Two rules from modules matter here. Child modules should not contain their own provider blocks: a module with its own provider configuration cannot be used with count, for_each or depends_on, and cannot be removed cleanly because the provider configuration disappears together with the module. Keep provider blocks in the root module and pass them down. In Terraform the providers map is static, like provider; you cannot compute it.

Source: Terraform Docs — module block reference and Terraform Docs — The for_each meta-argument.

Every resource inside the module gets the module instance as a prefix: module.environment["dev"].docker_network.main and module.environment["staging"].docker_network.main. Referencing outputs works as with a resource: module.environment["dev"].url for one instance, or a for expression over module.environment for all of them. The same rules apply as on resources: count and for_each cannot be used together, must be known during planning, and the instance identity is the index or key. Removing one key destroys one environment.

A module-level depends_on makes every resource and data source inside the module wait for the dependency. It is rarely needed and expensive, for the reasons given above, because any change to the dependency can cascade to every object in the module.

Source: Terraform Docs — module block reference and Terraform Docs — The depends_on meta-argument.

A cheaper alternative is to pass something from the dependency as an input, such as the network name, and use it in the child module. That creates a precise reference instead of a blanket ordering.

Source: OpenTofu Docs — Provider Configuration.

The provider reference is static, but the key expression inside the square brackets may be dynamic. All instances of one resource must bind to the same provider block, though each may use a different instance of it. The provider’s for_each should be a superset of the resource’s: removing a provider instance that still manages resources in state is an error, so remove the resources first (for example with a targeted destroy), or keep the provider’s collection larger and filter the resource’s collection instead. A child module receives such a provider through its providers argument, and declares the aliases it expects with configuration_aliases.