6.14 Kubernetes Server Side Apply Behavior

Kubernetes Server Side Apply Behavior is the practical, operational experience of using server-side apply in real manifest-driven workflows, covering how it is invoked, how multiple cooperating actors coexist around a single object in practice, and the common operational patterns and pitfalls encountered when adopting it as the primary mechanism for applying manifests, building on top of the underlying ownership-tracking mechanics it relies on.

Invoking Server-Side Apply

The --server-side Flag

kubectl apply supports an explicit --server-side flag, switching from the historical client-side three-way merge behavior to true server-side apply, sending the manifest as an apply-patch request and letting the API server compute the merge and manage field ownership rather than doing so client-side.

Specifying a Field Manager Name

Server-side apply requests carry a field manager identifier, defaulting to a generic name for kubectl invocations but overridable via --field-manager, a detail that matters when multiple distinct pipelines or tools apply manifests against the same objects and need to be individually distinguishable in managedFields.

Coexistence of Multiple Actors

Humans and Controllers Sharing an Object

A common real-world pattern is a human-authored manifest managing most of a Deployment's spec, while a separate controller, such as a Horizontal Pod Autoscaler, independently manages just the replicas field through its own field manager, with server-side apply's field-level tracking allowing both to coexist without one clobbering the other's area of responsibility.

GitOps Tooling as a Field Manager

GitOps reconciliation agents that continuously apply manifests from a Git repository typically operate as their own distinct field manager, meaning any field intentionally left out of the tracked manifests remains free for other actors, such as an autoscaler or an admission-time defaulting mutation, to manage without triggering conflicts against the GitOps tool's own reapplications.

Handling Conflicts in Practice

Recognizing a Conflict Error

When a server-side apply request is rejected due to a field ownership conflict, the error response identifies exactly which field or fields are contested and which field manager currently owns them, giving an operator or pipeline immediately actionable information about where the disagreement lies.

Resolving Conflicts Deliberately

The appropriate resolution depends on context: sometimes it means removing the contested field from the applying manifest so the other manager's ownership is respected, and sometimes it means using --force-conflicts to deliberately take over ownership, a decision that should be made with awareness of what the other field manager was doing with that field and why.

Migrating Existing Objects to Server-Side Apply

Objects With No Prior Managed Fields History

An object created before server-side apply was adopted, or created through means other than apply entirely, has no prior field ownership history; the first server-side apply request against such an object establishes ownership for whichever fields the manifest specifies, without needing any special migration step.

Transitioning From Client-Side Apply

Objects previously managed exclusively through client-side kubectl apply carry a last-applied-configuration annotation but no meaningful managedFields history for that client; kubectl handles the transition automatically, treating the switch to server-side apply as establishing fresh field ownership based on the current manifest content going forward.

Practical Guardrails and Recommendations

Being Deliberate About What a Manifest Manages

Because server-side apply's conflict detection is only as useful as the precision of what each manifest actually declares, teams adopting it benefit from keeping manifests focused on exactly the fields they intend to own, avoiding accidentally including fields, such as ones copied wholesale from a live object export, that were never meant to be actively managed by that manifest's pipeline.

CI Pipeline Integration

Automated pipelines applying manifests via server-side apply generally treat an unexpected conflict as a failure condition requiring human review rather than automatically forcing the change, since a conflict typically signals either a genuine ownership disagreement worth investigating or a misconfigured pipeline that should not have been managing that field in the first place.

Observability Into Ownership State

Inspecting managedFields Directly

Operators can inspect an object's managedFields directly, typically through kubectl get -o yaml or a dedicated flag surfacing this information more readably, to understand exactly which field manager currently owns which parts of an object, a useful diagnostic step when investigating unexpected apply conflicts or unexpected field values.