hashicorp / hashicorp/web-unified-docs

Documentation about 'each' ('for_each') object is ambiguous

Open
#802 1 comment 0 reactions 0 assignees View on GitHub
documentation Terraform CE
Dominant language
MDX
Stars
86
Forks
275
Avg merge
3d 18h
Merged PRs (30d)
199

Description

### Current Terraform Version

Terraform v0.13.3

This issue is related to documentation and not Terraform executable.

### Use-cases

I have this configuration:

``` tf
locals {
az_functions = ["f1", "f2"]
}

resource "azurerm_function_app" "az_fun" {
for_each = toset(local.az_functions)
name = "${lower(each.value)}-azfun"
...
}
```

So I use a list of strings to create Azure functions and `each.value` to name this functions. I wanted to use [destroy-time provisioner](https://www.terraform.io/docs/provisioners/index.html#destroy-time-provisioners), but that failed with message, that I can use only `each.key` (and `self`…), but not `each.value`. So I looked at the documentation, because I wanted to know, what is `each.key` when I do not use `map`, but just `set`.

The documentation for `each` object is ambiguous. On [Resources documentation](https://www.terraform.io/docs/configuration/resources.html#the-each-object) is says:

> `each.key` — The map key (or set member) corresponding to this instance.
> `each.value` — The map value corresponding to this instance. (If a set was provided, this is the same as `each.key`.)

So according to this, if I have a set of strings, changing `each.value` to `each.key` should be safe and produce the same results.

But in the tutorial [Manage Similar Resources With For Each](https://learn.hashicorp.com/tutorials/terraform/for-each#add-for_each-to-the-vpc) page, there is:

> … With a list or set, `each.key` will be the index of the item in the collection, and `each.value` will be the value of the item.

So according to this page, `each.key` is number (index) in the case of `set` and `list`.

So what is the truth? Finally I did not use destroy-time provisioner and so I kept `each.value` in my config and did not try to check the real behavior.

### Proposal

I propose to update the documentation so the information about `each` object is the same (and correct) on both pages. It would be nice also write the real behavior as a comment on this issue.

Contributor guide

Open the contributing guide

Research direction

Compare the `each` object section in the Resources documentation with the Manage Similar Resources With For Each tutorial, then verify the actual behavior for sets and lists in Terraform v0.13.3. Update both pages so their descriptions agree and accurately explain `each.key` and `each.value`; the documentation should clearly resolve the issue's question.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.