5.16 Kubernetes Server Side Apply Model

Kubernetes Server Side Apply Model is a declarative update mechanism in which the API server itself, rather than the client, performs the work of merging a submitted configuration into an object's live state, tracking which field manager owns each individual field so that multiple actors can cooperatively manage different parts of the same object without silently overwriting one another's changes.

The Problem It Solves

Limits of Client-Side Apply

Before server-side apply, kubectl apply computed a three-way merge entirely on the client, comparing a locally stored last-applied-configuration annotation, the live object, and the newly submitted configuration, an approach that broke down when other tools or controllers modified the object outside of that specific client's tracked history, since the client had no visibility into changes it did not itself make.

The Need for Field-Level Ownership

In a cluster where a user manages a Deployment's spec.replicas initially, but a Horizontal Pod Autoscaler subsequently takes over adjusting that same field, naive full-object updates from either actor risk clobbering the other's most recent change; server-side apply solves this by tracking ownership at the level of individual fields rather than the object as a whole.

How Field Ownership Works

The managedFields Structure

Every object modified through server-side apply accumulates entries in its metadata.managedFields, each recording a field manager's identity, the API version used, the operation type, and a compact representation of exactly which fields that manager last set, giving the API server the information it needs to detect and mediate conflicts.

Field Managers

A field manager is identified by a name supplied with each apply request, typically corresponding to the tool or controller performing the operation, such as kubectl or a specific controller's binary name, and the ownership recorded against that manager persists across subsequent requests from the same or different managers.

Shared Ownership of Unset Fields

Fields that a client's apply request does not mention are left untouched and their ownership, if any, remains with whichever manager previously set them, meaning an apply request only asserts intent over the specific fields present in the submitted configuration, not the object as a whole.

Conflict Detection and Resolution

Detecting Conflicting Writes

If an apply request attempts to set a field currently owned by a different field manager, the API server returns a conflict error rather than silently applying the change, surfacing the disagreement explicitly to the client rather than allowing an unnoticed overwrite.

Forcing Ownership

A client can override a detected conflict by including a force parameter in its apply request, explicitly taking ownership of the contested field away from its previous manager, an action that should be used deliberately since it can disrupt whatever process previously depended on managing that field.

Shared Field Values

If multiple managers apply the exact same value for a field, no conflict is registered, since server-side apply treats identical values from different managers as compatible rather than contentious, only flagging genuine disagreements in the intended value.

Apply Versus Update Semantics

Apply as the Primary Verb

Server-side apply introduces its own dedicated PATCH content type, application/apply-patch+yaml, distinct from a standard update, and is intended to be the primary way declarative configuration is submitted repeatedly over an object's lifetime, in contrast to a full PUT update, which asserts ownership over the entire object body regardless of which fields actually changed.

Interaction With Non-Apply Updates

Objects can still be modified through ordinary PUT or PATCH requests from clients not using server-side apply, and the API server continues to record ownership information for those requests as well, though such default field managers do not benefit from the same fine-grained, intent-driven ownership tracking that a well-behaved apply client provides.

Practical Adoption Patterns

Controllers Managing Their Own Subset of Fields

Well-designed controllers use server-side apply to manage only the specific fields they are responsible for, such as a status-reporting controller applying only status fields, allowing them to coexist cleanly with other controllers or users managing different parts of the same object without needing explicit coordination between them.

Migrating From Client-Side Apply

Objects previously managed with kubectl apply's older client-side three-way merge can transition to server-side apply, with kubectl handling the migration of ownership information, though care is needed the first time this transition occurs to avoid unexpected conflicts against fields whose prior ownership history was not tracked under the new model.