hashicorp / hashicorp/web-unified-docs

`create_before_destroy` behavior on `count`/`for_each` resources is not clearly documented

Open
#720 3 comments 5 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

### 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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.