What is a destroy-time provisioner in Terraform, and what restrictions apply to what it can reference?

## The mechanics By default a provisioner is a *creation-time* provisioner: it runs after the resource is created. Adding `when = destroy` converts it: ```hcl resource "aws_instance" "node" { ami = var.ami_id instance_type = "t3.micro" provisioner "remote-exec" { when = destroy inline = ["/opt/drain-node.sh"] } } ``` Note `destroy` is a bare keyword, not a quoted string, exactly like `on_failure = continue`. A single resource can carry both kinds; each provisioner block declares its own `when`. Terraform runs destroy-time provisioners *before* it calls the provider's delete operation, which is the whole point — the resource still exists, so you can still talk to it. Typical uses are draining connections from a node, deregistering an agent from a monitoring or service-discovery system, or copying a final log bundle off the machine. ## Restriction one: what you may reference This is the part interviewers probe. A destroy-time provisioner, and the `connection` block it uses, may only reference: - `self` — attributes of the resource being destroyed - `count.index` - `each.key` Anything else — an input variable, a `local`, another resource's attribute, a data source — produces an error stating that destroy-time provisioners and their connection configurations may only reference attributes of the related resource. The reasoning is about ordering and lifetime. When the resource is being destroyed, the rest of the configuration around it may be being destroyed too, or may already be gone; Terraform would have to guarantee that whatever you referenced still exists and still holds a usable value at that moment. Rather than invent ordering rules for that, the language forbids the reference. The practical consequence bites hardest on `connection`: you cannot write `private_key = var.ssh_key`. Anything the destroy step needs must already be an attribute of the resource — which usually means baking the credential path or the drain script into the image, or storing what you need on the instance itself. ## Restriction two: it must be in the configuration at destroy time Provisioners are not stored in state as executable content; Terraform reads them from the configuration at run time. So if you delete the `resource` block, the provisioner goes with it, and the destroy runs with no hook at all. The workflow to remove a resource that has a destroy-time provisioner is therefore two steps: 1. Keep the block in place, remove it from the desired set some other way (or run `terraform destroy -target`), and let the provisioner fire. 2. Then delete the block from the configuration. The same trap applies to *adding* one: a destroy-time provisioner added today does nothing for resources that already exist unless the configuration is still in place when they are eventually destroyed — which it will be, since the block lives in the config rather than in state. The failure mode people actually hit is the deletion order. ## Failure behaviour differs from creation-time A failed creation-time provisioner taints the resource, so the next apply replaces it. A failed destroy-time provisioner cannot do that — the resource is on its way out. Instead the apply errors, the resource stays in state undeleted, and Terraform will attempt the provisioner again on the next destroy. HashiCorp's documentation therefore warns explicitly that destroy-time provisioners must be safe to run multiple times: a drain script that half-completed will be re-run from the top. ## Why they are rarer than people expect Most of the jobs destroy-time provisioners are reached for have better homes: - Draining a load-balancer target is usually a platform feature — a deregistration delay or connection-draining timeout configured on the target group as an attribute. - Deregistering from service discovery is normally the agent's own responsibility on shutdown, or a TTL expiry. - Graceful termination on a VM is a shutdown hook inside the operating system, which fires whether the termination came from Terraform, an autoscaler, or a hardware failure — the last of which no Terraform provisioner can help with. That last point is the strongest argument: Terraform only runs a destroy-time provisioner when *Terraform* performs the destroy. An instance killed by a spot interruption, an autoscaling event, or a console click never runs it. Depending on one for correctness builds a cleanup path with holes in it. Treat destroy-time provisioners as best-effort convenience, and put anything that must happen in the machine's own shutdown path or in the platform's configuration.