5.15 Kubernetes API Patch Model

Kubernetes API Patch Model is the set of partial-update formats the API server supports for modifying an existing object without requiring the client to submit its entire body, encompassing JSON Patch, JSON Merge Patch, strategic merge patch, and server-side apply, each offering a different tradeoff between expressiveness, list-handling behavior, and conflict resolution when multiple clients modify the same object.

Why Partial Updates Matter

Avoiding Full-Object Round Trips

A full update via HTTP PUT requires submitting the complete object, meaning a client must first read the current object, modify it, and submit the whole thing back, an approach vulnerable to overwriting concurrent changes made by other clients between the read and the write; patch operations instead express only the intended change, reducing both payload size and the risk of clobbering unrelated fields.

Concurrent Modification Scenarios

Kubernetes objects are frequently modified by multiple independent actors, a user through kubectl, a controller updating status, and an autoscaler adjusting replica count, all potentially targeting the same object; patch formats are designed with this multi-writer reality in mind, differing significantly in how gracefully they handle such concurrent, partial modifications.

JSON Patch

Operation-Based Format

JSON Patch, identified by the content type application/json-patch+json, expresses changes as an explicit sequence of operations, add, remove, replace, move, copy, and test, each targeting a specific path within the document, giving precise, low-level control over exactly what changes and how.

Precision at the Cost of Verbosity

Because every operation must specify an exact path and, for array elements, an exact index, JSON Patch requires the client to know the precise current structure of the document, making it powerful for exact, targeted changes but comparatively verbose and brittle if the underlying document's structure shifts unexpectedly between when the patch was constructed and when it is applied.

JSON Merge Patch

Simplified Merge Semantics

JSON Merge Patch, identified by content type application/merge-patch+json, expresses a change as a partial document to be merged into the existing object, with null values signaling field removal, offering a simpler mental model than JSON Patch at the cost of being unable to express certain operations, such as inserting into the middle of an array without replacing the entire array.

Strategic Merge Patch

Kubernetes-Specific List Handling

Strategic merge patch, identified by content type application/strategic-merge-patch+json, is a Kubernetes-specific format that improves on JSON Merge Patch's blunt array replacement behavior by using schema annotations, patchStrategy and patchMergeKey, embedded in the API's generated type definitions, to merge list elements intelligently based on a designated key field rather than replacing the entire list wholesale.

Merge Key Example

For a Pod's container list, the strategic merge patch strategy merges by the name field of each container entry, meaning a patch updating a single named container's image does not require the client to also resend every other container in the list, unlike JSON Merge Patch, which would need the full array to avoid losing unlisted entries.

Limitation to Built-In Types

Because strategic merge patch relies on schema annotations baked into the API server's generated Go types, it is only supported for built-in Kubernetes resources and is not available for Custom Resources, which instead rely on JSON Patch, JSON Merge Patch, or server-side apply.

Server-Side Apply

Declarative, Field-Ownership-Aware Merging

Server-side apply, using content type application/apply-patch+yaml, represents a fundamentally different model: rather than the client computing a diff or patch itself, it submits its complete desired configuration for the fields it manages, and the API server merges this against the live object while tracking, per field, which client last set each value, recorded in the object's managedFields.

Conflict Detection

If two different field managers attempt to set conflicting values for the same field, server-side apply returns a conflict error rather than silently overwriting, unless the request explicitly forces the change, giving multi-actor scenarios an explicit, surfaced signal rather than a silent last-writer-wins outcome.

Replacing Client-Side Three-Way Merge

Server-side apply was introduced specifically to replace the older kubectl apply client-side three-way merge, which relied on a locally stored last-applied-configuration annotation and was prone to subtle bugs when multiple tools modified the same object outside of that specific client's awareness.

Choosing Among Patch Formats

Matching Format to Use Case

JSON Patch suits precise, programmatic single-field or structural changes; JSON Merge Patch suits simple, small updates to non-list fields; strategic merge patch suits built-in resources with list fields needing intelligent merging; and server-side apply suits any scenario, especially involving Custom Resources or multiple cooperating controllers, where declarative, conflict-aware, field-level ownership tracking is valuable.