6.10 Kubernetes Declarative Apply Behavior

Kubernetes Declarative Apply Behavior is the specific set of semantic guarantees and edge-case handling that distinguishes an apply operation from simpler alternatives like create or replace, defining how repeated applications of an evolving manifest over an object's lifetime correctly add, modify, and remove fields to keep the live object continuously aligned with whatever the manifest currently declares, rather than merely reflecting a single point-in-time snapshot.

Apply as a Repeated, Longitudinal Operation

Designed for a Manifest's Entire Lifetime

Unlike a one-time create operation, apply is designed to be the primary verb used every time a manifest changes and needs to be pushed to the cluster again, meaning its behavior must remain correct not just for the first invocation but across an arbitrary, ongoing sequence of manifest revisions applied over the life of the corresponding object.

Contrast With Replace

A replace operation, using a full PUT, requires the caller to submit the complete current state of the object and simply overwrites it wholesale, offering no help in determining which fields the caller actually intends to manage versus which happen to be present because they were read back from the live object; apply, by contrast, is specifically designed around the concept of a caller managing only a subset of an object's total fields over time.

Handling Field Removal

The Core Challenge of Field Deletion

The central behavioral challenge apply must solve is correctly distinguishing "this field is no longer present in the manifest because the field manager removed it and it should be deleted from the live object" from "this field was never managed by this caller and should be left untouched," a distinction that plain JSON Merge Patch semantics cannot make on their own.

Client-Side Resolution via Last-Applied-Configuration

The older client-side apply approach resolves this by comparing the current manifest against a previously stored last-applied-configuration annotation: any field present in the prior applied configuration but absent from the new one is treated as an intentional removal and cleared, while fields never previously applied by this client are left alone regardless of their absence.

Server-Side Resolution via Field Ownership

Server-side apply resolves the same challenge more robustly by tracking exactly which fields a given field manager owns; when that manager's new apply request omits a field it previously owned, the server treats this as relinquishing that field, removing it if no other manager also claims it, a mechanism that works correctly even across multiple independent apply-based tools managing the same object.

Merge Behavior for Lists

Whole-List Replacement Versus Element Merging

A key apply behavior distinction concerns how array fields are treated: naive merge patch semantics simply replace an entire array wholesale, meaning omitting an element from a reapplied manifest silently drops it, while both strategic merge patch, for built-in types, and server-side apply's list-type schema annotations support merging individual list elements by a designated key, preserving elements managed by other field managers.

Practical Consequences for Multi-Container Pods

This list-merge distinction has direct practical consequences: applying a manifest that updates one container's image within a Pod's container list should not silently remove other containers absent from that specific manifest revision, behavior that correctly configured apply semantics preserve but naive full-array replacement would break.

Idempotent No-Op Reapplication

Detecting True No-Change Conditions

A well-behaved apply operation detects when a reapplied manifest is functionally identical to the current live state and reports the object as unchanged rather than issuing an unnecessary write, both reducing needless API server load and avoiding spuriously incrementing resourceVersion or triggering watch events for observers with no actual state change to report.

Whitespace and Ordering Insensitivity

Because manifests are text and the same logical configuration can be expressed with different formatting, key ordering, or whitespace, correct apply behavior compares the semantic content of the manifest against live state rather than performing a naive textual comparison, ensuring purely cosmetic differences in a manifest's authoring do not trigger false-positive changes.

Interaction With Externally Modified Fields

Fields Modified Outside the Applying Client

If some other actor, a different tool, a controller, or a manual kubectl edit, modifies a field that the applying client does not itself manage, correct apply behavior leaves that externally modified value untouched on the next reapplication, respecting the boundary of what the applying manifest actually declares rather than reverting unrelated changes.

Reclaiming Externally Modified Owned Fields

Conversely, if the applying client's manifest re-declares a field's value and that field had been externally modified since the last apply, a subsequent reapplication overwrites the external change back to what the manifest specifies, since the manifest remains the authoritative declaration for any field it explicitly manages, regardless of what happened to that field in between applications.