Skip to main content
In this lesson we cover Kustomize patches: a targeted, surgical way to modify specific parts of Kubernetes resources. Use a transformer when you want to apply the same change across many resources (for example, adding a label or assigning a namespace to all objects). Use a patch when you want to change one or a few specific objects — for example, updating the number of replicas on a particular Deployment. To create a patch you must provide three things:
  • Operation type — the action to take (add, remove, replace, etc.).
  • Target — criteria to match the resource(s) to patch (fields such as kind, apiVersion/group, name, namespace, labelSelector, annotationSelector).
  • Value — the new data to add or replace (not required for remove operations).
A dark-themed presentation slide titled "Patches" explaining Kustomize patches as a way to modify Kubernetes configs. It lists required parameters and bullets like operation type (add/remove/replace), target (kind, version/group, name, namespace, labelSelector, annotationSelector) and value.
You can combine multiple match criteria in the target to precisely select which resource(s) to patch.
For a remove operation you only need to specify the target and the path to remove — no value is required.
How operations work (most common ones)
  • add — insert a value (for example, add a container to a Pod spec list).
  • remove — delete a value (for example, remove a label or an element from a list).
  • replace — swap an existing value with a new one (for example, change replicas from 5 to 10).
JSON Pointer paths (for example, /metadata/name, /spec/replicas) indicate where in the YAML tree the operation applies.

​
Examples

Below are two common patch scenarios using JSON Patch (RFC 6902) inline patches in a kustomization.yaml. These demonstrate how to target and change specific fields in a Deployment. Example 1 — Replace metadata.name
Goal: change a Deployment named api-deployment to web-deployment. Base Deployment:
kustomization.yaml using a JSON 6902 inline patch:
Resulting Deployment after kustomize build:
Notes about the inline JSON 6902 patch:
  • The patch: entry uses the YAML block scalar |- to embed the patch content inline.
  • The patch content is a JSON Patch (RFC 6902) represented in YAML: a list of operations with keys op, path, and optionally value.
  • JSON Patch supports other operations as well (move, copy, test), but add, remove, and replace are the most common.
Example 2 — Replace spec.replicas
Goal: change replicas from 1 to 5 on the same Deployment. Base Deployment (same as above, with replicas: 1). kustomization.yaml using a JSON 6902 inline patch:
Resulting Deployment after kustomize build:

​
Two patch styles supported by Kustomize

Kustomize supports two primary patch formats. Choose the one that best fits your use case. Example of a strategic merge patch:
How strategic merge patches work:
  • Kustomize uses the metadata (for example, name, namespace) to identify which resource to patch.
  • The YAML snippet contains only the fields you want to change; Kustomize merges them into the original object to produce the final manifest.
  • Strategic merge patches are often easier to author because they look like normal Kubernetes YAML.
Be careful with list merging when using strategic merge patches. Lists are merged using merge keys defined for the resource (often name), and incorrect assumptions about merging can unintentionally replace or duplicate list entries. Use JSON 6902 when you need predictable, element-level operations on lists.
Both methods are valid — choose based on readability, precision, and the nature of the change:
  • Use JSON 6902 patches for explicit, targeted operations using JSON Pointer paths.
  • Use strategic merge patches for readability and when changing conventional Kubernetes fields.
These resources will help you decide which patch style to use and how to construct patches safely in your Kustomize manifests.

Watch Video