hashicorp / hashicorp/web-unified-docs
`create_before_destroy` behavior on `count`/`for_each` resources is not clearly documented
- Dominant language
- MDX
- Stars
- 86
- Forks
- 275
- Avg merge
- 3d 18h
- Merged PRs (30d)
- 199
Description
### Terraform Version
```shell
Terraform v1.4.2
on darwin_arm64
+ provider registry.terraform.io/hashicorp/aws v4.67.0
Your version of Terraform is out of date! The latest version
is 1.11.3. You can update by downloading from https://www.terraform.io/downloads.html
```
### Affected Pages
* https://developer.hashicorp.com/terraform/language/meta-arguments/count
* https://developer.hashicorp.com/terraform/language/meta-arguments/for_each
* https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle
### What is the docs issue?
The behavior of `create_before_destroy` on a resource collection type using `count` or `for_each` isn't clear from documentation. There are two ways it could be interpreted to behave:
1. Every resource in the collection is an individual resource and `create_before_destroy` is applied to each separately. If a plan wants to both add and delete resources with separate `for_each` keys or `count` indices from the collection, the creates and destroys happen in an undefined order.
2. `create_before_destroy` applies to the collection as a whole. If a plan wants to both add and delete resources with separate `for_each` keys or `count` indices from the collection, all resources to add will be created before any resources to remove are destroyed.
We had a brief production outage because we assumed the latter, but we think we observed the former. The docs do not make it clear which behavior to expect.
### Proposal
Explicitly document how `create_before_destroy` and maybe `lifecycle` arguments in general are applied to resources in a collection and whether any of them apply to the collection as a whole.
### References
_No response_
Contributor guide
Research direction
Start by reading the count, for_each, and lifecycle pages listed under Affected Pages, then verify how create_before_destroy behaves when collection instances are added and removed. Done means the relevant documentation explicitly explains whether lifecycle behavior applies per instance or to the collection as a whole, including the ordering users should expect.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- terraform
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100