hashicorp / hashicorp/web-unified-docs
Documentation about 'each' ('for_each') object is ambiguous
- 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
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