6.22 Kubernetes Manifest Deletion Intent

Kubernetes Manifest Deletion Intent is the problem of how a purely declarative, apply-based workflow expresses that an object should cease to exist, a case the apply operation itself does not handle, since apply is fundamentally additive and merge-oriented, meaning removing an object entirely requires either an explicit delete action or opt-in pruning behavior layered on top of the basic apply model.

Why Apply Alone Cannot Express Deletion

Apply Only Knows What Is Present

An apply operation processes whatever manifests are supplied to it; if a manifest that previously declared an object is simply removed from the input set, or deleted from a repository entirely, the apply operation for the remaining manifests has no way of knowing that object ever existed, let alone that its absence signals an intent to delete it.

Absence Is Ambiguous Without Additional Context

A manifest's absence from a given apply invocation could mean many things: the object was never meant to be managed by this particular pipeline, the pipeline is only applying a subset of manifests this run, or the object genuinely should be deleted; apply's merge-based model has no built-in mechanism to distinguish between these very different intents.

Explicit Deletion as Direct Intent

kubectl delete -f

The most direct way to express deletion intent is issuing an explicit delete request against the manifest's identity, such as kubectl delete -f manifest.yaml, which reads the manifest purely to determine the target object's identity and issues a delete request, independent of whatever apply-based workflow otherwise manages that object.

Deletion as a Deliberate, Separate Action

Because explicit deletion is a distinct operation from apply, expressing deletion intent this way requires a deliberate, separate step in whatever workflow or pipeline manages the manifest's lifecycle, rather than being something that falls naturally out of simply removing a manifest from a repository.

Pruning as Automated Deletion Intent

Inferring Deletion From Absence

Pruning-capable tools solve the ambiguity problem by tracking which objects were previously applied as part of a defined set, typically via a tracking label or annotation, and treating any previously tracked object no longer present in the current manifest set as carrying implicit deletion intent, deleting it automatically as part of the apply operation.

The Role of Tracking Labels

A pruning-aware apply typically stamps every object it manages with a label identifying the specific set or application it belongs to, and on each run, queries the cluster for all objects carrying that label, comparing the result against the current manifest set to identify candidates whose absence now represents deletion intent.

GitOps Sync Policies

GitOps tools commonly expose pruning as an explicit, configurable sync policy option, since automatically deleting objects based on manifest absence carries meaningfully higher risk than only ever creating and updating, making it a deliberate opt-in choice rather than default behavior for most such tools.

Risks of Automated Deletion Intent

False Positives From Partial Manifest Sets

If a pipeline is inadvertently run against only a subset of its intended manifests, pruning logic can misinterpret the missing manifests as deletion intent and remove objects that were never actually meant to be deleted, making the correctness of the tracked manifest set a critical dependency for safe pruning.

Namespace and Scope Boundaries for Pruning

To limit the blast radius of a pruning mistake, pruning is commonly scoped to a specific namespace, label selector, or otherwise bounded set of resource types, rather than being allowed to consider the entire cluster as candidates for deletion based on a single manifest set's absence.

Explicit Deletion Markers as an Alternative Pattern

Annotating Intent Rather Than Removing the Manifest

Some workflows favor an alternative pattern of explicitly marking an object for deletion within its still-present manifest, such as through a dedicated annotation a controller or pipeline recognizes, rather than relying purely on the manifest's absence, trading the convenience of simple removal for a more explicit, auditable record of deletion intent within version control history.

Auditability Trade-Offs

An explicit deletion marker leaves a clear commit in history showing the deliberate intent to remove an object, whereas simply deleting the manifest file removes the object's configuration from the repository entirely, potentially making it harder to later understand why a given object was removed without digging through prior commit history.