# Terraform workflow: replace tainted and unhealthy resources deliberately

## When

`terraform plan` shows replacements you did not expect, or you know a resource is unhealthy and needs rebuilding.

## Steps

1. Audit: `terraform state list` will not show taint directly; the plan output marks tainted resources. Find why each was tainted: failed provisioner, manual `terraform taint`, or a previous failed apply.
2. Verify current health in the console. A tainted resource that is actually healthy should be untainted (`terraform untaint [address]`), not recreated. Taint is a claim about health; check the claim.
3. For genuinely unhealthy resources: `terraform apply -replace=[address]` forces replacement with a reviewed plan. Prefer `-replace` over `taint` + apply: it is explicit, single-shot, and does not leave taint state lying around for the next person.
4. For config-driven replacement (replace when a secret or AMI changes): `replace_triggered_by` in lifecycle makes the replacement automatic and reviewable in the plan.

## Rules for agents

1. Never untaint a resource you have not verified. Untainting a genuinely broken object just postpones the failure to the worst moment.
2. `terraform taint` is deprecated in favor of `-replace`. If you see taint in runbooks, update the runbook.
3. Replacement of stateful resources destroys data unless the resource handles it (snapshots, replication). Check the data story before replacing anything stateful.
4. After replacement, the plan is clean and the new object is healthy in the console. Both, not either.