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, computes how a submitted configuration should be merged into an object's live state, tracking exactly which fields each client has expressed ownership over so that multiple controllers, tools, and users can safely co-manage different parts of the same object without their writes silently overwriting one another. It replaces the older pattern of client-side three-way diffing (as used by classic kubectl apply) with a model where ownership bookkeeping lives on the server, making conflict detection and multi-actor object management reliable regardless of which client or tool happens to be writing.

The Problem Server-Side Apply Solves

Client-Side Apply's Fragility

The original kubectl apply computed a three-way merge entirely on the client, diffing a locally cached "last applied configuration" (stored in an annotation) against the current live object and the newly submitted configuration; this approach broke down when multiple different tools or users applied configuration to the same object, since only one client's last-applied annotation could be tracked at a time, and non-kubectl writers had no visibility into that bookkeeping at all.

Multiple Controllers, One Object

Many real objects are legitimately co-managed — a Horizontal Pod Autoscaler adjusts a Deployment's replica count while a GitOps tool manages its container image — and client-side apply had no principled way to let each actor own only its own slice of the object without one silently overwriting the other's most recent change on its next reconciliation pass.

Field Managers and managedFields

Identifying the Writer

Every apply request must declare a field manager, a client-supplied name identifying which actor is performing the write (such as kubectl-client-side-apply, a specific controller's name, or a CI pipeline's identifier), and the API server records, for every field currently set on the object, which field manager most recently claimed ownership of it.

The managedFields Structure

This ownership record is persisted directly on the object as metadata.managedFields, a structured list mapping each field manager to the specific set of fields (expressed in a compact FieldsV1 format mirroring the object's own structure) that manager currently owns, giving any client inspecting the object a complete picture of who is responsible for which parts of its current configuration.

Applying and Conflict Resolution

The apply Operation

An apply request submits a fully specified, intended configuration for the fields that field manager cares about (not necessarily the whole object), using the PATCH verb with the application/apply-patch+yaml content type; the API server merges this into the live object, updating ownership records for the fields included in the request.

Detecting and Resolving Conflicts

If the incoming apply request attempts to set a field currently owned by a different field manager and the value would change, the API server rejects the request with a conflict, explicitly naming the conflicting field and its current owner; the requesting client must then either omit that field from its request, coordinate to take over ownership deliberately, or resubmit with force=true to seize ownership, which explicitly signals an intentional override.

Shared Ownership When Values Agree

When multiple field managers apply the same field with the same value, no conflict occurs and both are recorded as owners, only becoming a genuine conflict if one of them later attempts to change that field to a different value while the other manager's claim still stands.

Relationship to Update Requests

Apply Versus Traditional Update

A traditional update (or client-side PATCH) request is treated by the ownership tracking system as implicitly claiming ownership of every field it touches under a default field manager, meaning mixing traditional updates with server-side apply on the same object can still produce ownership churn if not used consistently, which is why migrating an existing object fully to server-side apply management is generally recommended over mixing update styles indefinitely.

Migration Considerations

Adopting server-side apply for an object previously managed through client-side apply or direct updates requires an initial apply that may need force=true, since the object's existing fields will be attributed to a default or prior field manager that the new apply's field manager does not yet share explicit agreement with, after which normal conflict-free applies can proceed going forward.