strategicMerge

Strategic Merge Patch is a patching mechanism used by Kubernetes to modify objects by merging a patch document with the existing object. It is one of the patch types supported by the Kubernetes API, alongside JSON Merge Patch and JSON Patch. Strategic Merge Patch preserves fields not mentioned in the patch and applies changes in a way that can update nested structures without replacing the entire object.

A key feature is the merging of lists using merge keys. For lists, the resource type may declare a patchStrategy and patchMergeKey for the field. When merging, items in the patch list are matched by the patchMergeKey; matching items are updated, new items are added, and items not present in the patch may remain. If no patchMergeKey is defined, list items may be appended or replaced depending on the field and schema.

Usage commonly involves the Kubernetes API via kubectl patch with a strategic-merge-patch type, or when patches are sent by clients to update resources. It is especially useful for updating specific elements within a list (such as containers in a Pod template, labels, or environment variables) while leaving other parts of the object intact. For example, to update the image of a container named "web" in a Deployment, a strategic merge patch would identify the container by its name and set a new image, without altering other containers.

Limitations include reliance on the target resource defining patchStrategy and patchMergeKey, and not all fields supporting merging. Complex structural changes may require alternative patch types or full object replacement.

See also: Kubernetes patch types, JSON Merge Patch, JSON Patch, kubectl patch.