PatchesStrategicMerge

PatchesStrategicMerge is a patching mechanism used by Kustomize to apply patches to resources defined in a base manifest. It leverages Kubernetes strategic merge patch semantics, meaning patches modify specific fields of target resources rather than replacing entire objects.

Patch files intended for patchesStrategicMerge must identify the target resource by apiVersion, kind, and metadata.name. The content of the patch contains only the fields to be changed or added. During the merge, fields not mentioned in the patch are preserved, and lists are merged according to the resource’s defined merge rules using merge keys. This makes patchesStrategicMerge well suited for updating portions of complex objects such as Deployment or ConfigMap specs.

In a kustomization.yaml file, patchesStrategicMerge is a list of patch files. Each patch file applies to the corresponding resource in the base, and multiple patches can target different resources. Patches are applied in sequence; the order can influence the final result because later patches may override earlier changes.

Use cases include updating container images, environment variables, replica counts, resource requests and limits, or metadata across one or more resources without duplicating entire manifest files. Because the mechanism relies on the structure and merge semantics of the target resource, patches must be written with awareness of the resource’s schema and merge behavior.

Limitations include that not all resource types support strategic merge semantics in the same way, and some fields may require alternative patch approaches for precise control. For exact, operation-based changes, other patching strategies such as JSON6902 patches or full replacements may be more appropriate.