Kubernetes API Patch Model

Kubernetes API Patch Model is the set of partial-update mechanisms the API server supports for modifying an existing object without requiring a client to submit the object's entire content, offering several distinct patch strategies — each with different semantics for how the submitted content is merged into the object's current stored state — that clients choose between depending on whether they need to overwrite a field wholesale, merge structured content intelligently, or express fine-grained list and map operations. Patching exists because most real-world updates touch only a small fraction of an object's fields, and forcing every client to read, modify, and rewrite the complete object invites both unnecessary payload size and a higher chance of clobbering concurrent changes from other clients.

JSON Patch

Operation-Based Updates

JSON Patch (media type application/json-patch+json) expresses a change as an explicit sequence of operations — add, remove, replace, move, copy, and test — each targeting a specific path within the object, giving precise, unambiguous control over exactly what changes, including the ability to fail the entire patch if a test operation finds an unexpected current value.

Precision at the Cost of Verbosity

Because every operation must specify an exact path and, for most operation types, an exact value, JSON Patch requires the client to already know the object's current structure in enough detail to construct valid operations, making it precise but comparatively verbose and less forgiving of concurrent structural changes than merge-based approaches.

JSON Merge Patch

Structural Merging Semantics

JSON Merge Patch (media type application/merge-patch+json) expresses a change as a partial object to be recursively merged into the existing object, where present fields overwrite corresponding fields in the target and a field explicitly set to null requests deletion of that field, but critically, arrays are always replaced wholesale rather than merged element by element.

Limitations for List Fields

Because JSON Merge Patch cannot express "add one element to this list without touching the others," it is poorly suited to Kubernetes objects with meaningful list fields such as a Pod's containers or a Service's ports, which is a major reason Kubernetes developed its own extended patch type specifically to handle these structures more usefully.

Strategic Merge Patch

Kubernetes-Specific List Merging

Strategic Merge Patch (media type application/strategic-merge-patch+json) extends JSON Merge Patch's semantics with Kubernetes-specific annotations embedded in the API types themselves — patchMergeKey and patchStrategy struct tags — that tell the API server how to merge list elements by a designated key field (such as a container's name) rather than replacing the whole list, allowing a patch to add or update a single container without needing to restate every other container in the Pod spec.

Availability Limited to Built-In Types

Because strategic merge patch relies on Go struct tags compiled into the API server, it is only available for built-in types that carry these annotations; CustomResourceDefinitions do not support strategic merge patch and must instead use JSON Merge Patch, JSON Patch, or Server-Side Apply for partial updates.

Server-Side Apply

A Different Model: Field Ownership

Server-Side Apply (using media type application/apply-patch+yaml) represents a distinct approach rather than a fourth patch format applied the same way as the others: instead of computing a merge based purely on the patch content, the API server tracks which fields each named client ("field manager") has claimed ownership of, recorded in metadata.managedFields, and uses that ownership history to resolve conflicts between multiple clients managing overlapping parts of the same object.

Conflict Detection Instead of Silent Overwrite

When two different field managers attempt to set the same field to different values, Server-Side Apply returns a conflict error rather than silently letting the later write win, requiring the conflicting client to either force the change or adjust its request, which directly addresses the class of bugs where two controllers stomping on each other's fields would otherwise produce flapping, unpredictable object state under the older patch strategies.