Terraform has long been excellent at describing what infrastructure should exist. The awkward part has been everything that must happen immediately before or after infrastructure stops existing: take a final database backup, deregister a service, release an address in an external system, archive compliance evidence, or remove a record from a configuration database. Those steps often lived in a second automation system, a CI job, or a runbook that operators had to remember during an already risky change.
Terraform 1.16 closes much of that gap by extending Actions to the destruction phase. The new before_destroy and after_destroy lifecycle events allow provider-defined operations to participate in Terraform’s dependency graph and plan-and-apply workflow. This is more than a convenience feature. It gives platform teams a way to model teardown as part of the infrastructure contract. But it also requires sharper decisions about failure behavior, configuration removal, retries, and observability.
The practical thesis is simple: destroy Actions can make decommissioning safer only when teams treat teardown as a designed workflow, not as a hidden script attached to deletion. The first implementation target should be a narrow, auditable operation with an explicit answer for what happens when it fails.
What Terraform 1.16 actually changes
Terraform Actions are provider-defined operations that do not map neatly to the traditional create, read, update, and delete methods for a resource. Earlier Action support covered create and update events. Version 1.16 adds the missing destruction boundaries: an Action may now execute before Terraform deletes a resource or after deletion completes.
A before_destroy Action is appropriate when the operation needs the resource to remain available. Examples include requesting a final backup, draining a node, exporting configuration, revoking a lease through the live service, or asking an external control plane to prepare for removal. An after_destroy Action fits work that should happen only after the infrastructure object is gone, such as clearing an inventory record, closing a decommission ticket, or releasing a reservation held outside the resource provider.
The Action is planned with the resource operation, and Terraform respects resource dependencies when invoking it. Version 1.16 also exposes a caller object so the Action can use values from the resource instance that triggered it. This matters at destroy time because the useful identifiers are often in state rather than in a newly created object.
The release also introduces three on_failure modes for resource action triggers:
halt: the default. Terraform stops the apply and reports an error.continue: Terraform reports the failure as a warning and proceeds.taint: Terraform stops and marks a newly created resource for replacement on the next apply.
That third option needs care in teardown designs. HashiCorp explicitly notes that taint does not make a failed destroy Action retriable. For destroy-time work, teams should generally reason in terms of halt or continue and build idempotency into the external operation rather than expect taint to provide a recovery mechanism.
Why teardown belongs in the infrastructure contract
Creation paths receive extensive engineering attention because they run frequently and block delivery when broken. Destruction paths are less common, but their failures can have a larger blast radius. A deleted database without a verified final backup is not equivalent to a failed deployment. A load balancer removed before its target is drained can create an outage. A cloud resource deleted while its entitlement remains active can leave both cost and security residue.
When these steps live outside Terraform, the organization maintains two partial models of the same lifecycle. Terraform knows the resource dependency graph, while a pipeline or runbook knows the operational prerequisites for removal. The two systems can drift. A module may be reused without its companion CI job, or an engineer may run Terraform from a different workflow that never invokes the cleanup script.
Destroy Actions let a module author place the teardown operation alongside the resource and its lifecycle rules. That improves portability and makes the requirement visible during review. It also gives Terraform an opportunity to order the operation relative to dependent resources. The benefit is not that every shell command can now be stuffed into configuration. The benefit is that provider-backed, lifecycle-specific operations can be planned as part of the same change.
Choose the event boundary before choosing the Action
The most important design decision is whether success must occur before deletion or whether cleanup can safely follow it. Platform teams should classify each proposed operation using three questions:
- Does the operation require the resource to be reachable? If so, it belongs before destruction.
- Does the operation prove that deletion completed? If so, it belongs after destruction.
- Can the operation be repeated without making the situation worse? If not, it is a poor candidate until it is made idempotent.
A final backup is the clearest before_destroy example, but the Action should do more than submit an asynchronous request and declare victory. Decide whether the contract requires a request ID, a completed snapshot, or independent verification that the artifact is usable. The correct boundary depends on the recovery objective, not on whichever API call is easiest to invoke.
Similarly, an after_destroy inventory cleanup should tolerate the target record already being absent. If an apply is retried or an operator completes cleanup manually, the Action should converge on the same outcome. A decommissioning operation that fails on “not found” creates unnecessary incidents.
Make failure policy a service-level decision
on_failure should not be selected by coding preference. It encodes business policy. A failed final backup for a production datastore should probably halt deletion. Failure to send a courtesy notification may warrant a warning and continued processing. The platform should define classes of teardown work and map them to a default response.
- Data protection and compliance controls: favor
halt. Require an operator to resolve or explicitly override the condition. - Traffic safety and dependency detachment: usually favor
halt, because proceeding can create an outage or orphan a dependency. - Inventory synchronization and notifications: consider
continueonly when a reconciliation process will detect and repair missed cleanup. - Cost and entitlement cleanup: choose based on the larger risk. Continuing may leave residue; halting may keep an expensive resource alive.
For every continue policy, name the compensating control. That might be a daily reconciliation job, a queue with retries, an alert on stale inventory, or a report comparing Terraform state with the external system. “Continue” without reconciliation means “silently accept drift,” even if Terraform emits a warning during the apply.
Account for the configuration-removal trap
Destroy Actions have a constraint that can surprise experienced Terraform users: the trigger must still exist in configuration when Terraform plans the destroy. If a pull request deletes the entire resource block, it also deletes the action_trigger. Terraform cannot invoke lifecycle logic that is no longer present.
HashiCorp’s guidance is to preserve the resource block and trigger while first setting count = 0 for the planned removal, then delete the block in a later change. Teams using for_each need an equivalent staged migration that removes the target instance while keeping the lifecycle configuration available. This changes the review and rollout process: decommissioning may require two commits or two applies rather than one.
Encode that pattern in module documentation, pull-request templates, and policy checks. A platform can also provide a dedicated decommission input that makes the first phase obvious. The goal is to prevent a well-intentioned cleanup pull request from bypassing the very Action meant to protect deletion.
Another planning constraint is that destroy Action configuration and its trigger condition must be known at plan time. Terraform stores the planned values for apply, so ephemeral values cannot supply destroy Action configuration. Teams should verify that identifiers, policy inputs, and Action arguments are available from configuration or state before adopting the pattern.
A safe adoption playbook
1. Inventory the side-channel teardown work
Search deployment repositories, CI workflows, service catalogs, and operations runbooks for tasks coupled to Terraform destruction. Record the resource, timing requirement, external system, owner, current retry behavior, and consequence of failure. Do not migrate everything at once. Select one operation with a clear API and limited blast radius.
2. Confirm provider support and semantics
Actions are provider-defined, so Terraform core support alone does not guarantee that the operation you need exists. Review the provider’s Action documentation, authentication requirements, timeout behavior, and return values. Verify whether an invocation waits for completion or only starts a remote job. Pin both Terraform and provider versions so development, CI, and production share the same behavior.
3. Define an observable success condition
Write down what success means before adding the trigger. For a backup, specify whether success is an accepted request or a restorable artifact. Emit an external correlation ID and resource identity into the system that receives the Action. Keep secrets out of logs, but ensure operators can connect a Terraform run to the remote operation.
4. Design for retries and partial completion
Assume the Action can succeed remotely while Terraform loses the response. Use idempotency keys where the provider and API support them. Make deletion and cleanup endpoints tolerate repeated calls. Document manual recovery for the case in which Terraform halted after the external side effect completed.
5. Test the destructive path in isolation
Create a disposable environment that exercises the full plan, Action invocation, resource deletion, and external verification. Test timeouts, permission denial, unavailable APIs, and a repeated apply. Validate both the chosen failure mode and the operator-facing error. A successful happy path is insufficient evidence for a teardown control.
6. Roll out with policy and review guardrails
Begin with non-production resources, observe several real decommissions, and then expand. Add review rules for changes that remove protected resource blocks. Where possible, require a staged decommission input and block direct removal. Track Action failures and cleanup drift as platform reliability metrics rather than burying them in individual apply logs.
What platform teams should avoid
Destroy Actions should not become a new home for arbitrary orchestration. Long-running business workflows, multi-system approvals, or operations needing human judgment are still better handled by a purpose-built workflow engine. Terraform can initiate or gate those workflows, but an apply should not remain the only record of a complex decommission process.
Avoid wrapping unversioned shell scripts when a provider-backed Action is available. Avoid continue merely to keep pipelines green. Do not assume that a failed after-destroy operation can be recovered by rerunning the same plan, because the triggering resource may already be absent. And do not remove the resource configuration until the phase containing its destroy trigger has run successfully.
The operational payoff
Terraform 1.16 gives platform engineers a better place to express a class of work that has historically fallen between infrastructure code and operational procedure. The feature is valuable because it can keep teardown intent with the module, place it in the dependency graph, and expose it during planning. Its value disappears if teams use it as an invisible hook with vague success criteria.
The strongest first use case is a single, provider-supported teardown operation where the timing boundary is unambiguous and the failure consequence is understood. Treat its failure policy as a service-level decision, preserve the trigger during staged removal, and add reconciliation for any operation allowed to continue after failure. With those controls, destruction becomes a governed lifecycle phase rather than the moment automation hands responsibility back to a runbook.
