6.9 Kubernetes Manifest Apply Flow

Kubernetes Manifest Apply Flow is the concrete, step-by-step sequence of actions that occurs from the moment a user or automation pipeline invokes an apply operation against one or more manifests to the moment the resulting objects are persisted in the cluster, spanning local file reading, identity resolution, merge computation, and submission to the API server.

Reading and Parsing Input

Gathering Manifest Sources

The apply flow begins with the client, typically kubectl apply -f, gathering manifest content from one or more sources, which may be individual files, an entire directory processed recursively, or content piped from standard input, and parsing each into one or more discrete object documents, respecting multi-document YAML separators where present.

Local Syntax and Schema Checks

Before any network request is made, the client can optionally perform local validation against cached or fetched OpenAPI schema data, catching structural errors, such as an unrecognized field or an incorrect type, before spending a round trip to the API server only to have the request rejected.

Resolving Target Identity

Determining the Target Object

For each parsed manifest document, the client determines its resource identity, kind, API version, namespace, and name, as covered by the manifest resource identity concept, and queries the API server to check whether an object matching that identity already exists.

Branching on Existence

If no matching object exists, the flow proceeds toward a create operation; if a matching object is found, the flow proceeds toward a merge-based update instead, with the specific merge behavior depending on whether server-side or client-side apply is in use.

Merge Computation

Server-Side Apply Path

When using server-side apply, the client submits the manifest directly as an apply-patch request, and the API server itself performs the merge against the live object, using tracked field ownership to detect and, unless forced, reject any conflicting changes, as detailed in the server-side apply model.

Client-Side Three-Way Merge Path

When using the older client-side apply behavior, the client computes a three-way merge locally, comparing the last-applied-configuration annotation stored on the live object, the live object's current full state, and the newly supplied manifest, producing a patch that captures both the newly intended changes and any fields the manifest previously set but has since removed.

Submission to the API Server

The Actual HTTP Request

Once the merge or apply patch has been computed, the client issues the corresponding HTTP request, a PATCH for both merge styles, or occasionally a POST for genuinely new objects under certain client implementations, carrying the computed patch body and appropriate content type header identifying which patch format is being used.

Admission and Persistence

The request then flows through the same admission chain, mutating and validating webhooks, and built-in validation, that any other API request passes through, before the API server persists the resulting merged object to etcd and returns the updated object in its response.

Handling the Response

Reporting Outcome to the User

The client reports back whether each object was created, configured (updated with changes), or unchanged (updated with no actual difference detected), giving the invoking user or pipeline immediate, per-object feedback about the outcome of the apply operation across potentially many manifests processed in a single invocation.

Surfacing Conflicts

If server-side apply detects a field ownership conflict and the client did not request forced application, the flow halts for that specific object with a conflict error, requiring the user to either adjust the manifest, coordinate with the conflicting field manager, or explicitly force the change before the apply can proceed for that object.

Optional Pruning Behavior

Detecting Removed Manifests

Some apply workflows support a pruning mode, in which the client also identifies previously applied objects, tracked via a label or the recorded set of applied identities, that no longer correspond to any manifest in the current input set, and deletes them as part of the same apply invocation.

Pruning as a Deliberate, Opt-In Step

Because pruning can delete objects, it is typically an explicitly opt-in flag rather than default behavior, reflecting the higher blast radius of an apply flow that can both create and destroy resources compared to one that only ever creates or updates what is explicitly present in the supplied manifests.

Dry Run as a Preview Step

Validating Without Persisting

Both server-side and client-side apply flows support a dry-run mode, in which every step up through admission processing occurs normally, but the final persistence to etcd is skipped, allowing the flow to be used purely to preview what would happen, including surfacing conflicts or validation errors, without committing any actual change to the cluster.