Kubernetes Patch Tester
Paste an object and a patch, pick the --type
you would pass to kubectl patch, and see the
object you would end up with. The three types disagree about lists: switch
between them on the same patch and the difference is the answer.
Nothing is uploaded and no cluster is contacted: the three algorithms run in this tab.
What changed
list positions are shown as they land, because that is the part that surprises peopleResult
Common mistakes
These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.
Using a strategic merge patch on a custom resource
Strategic merge relies on Go struct tags that only exist for built-in types. On a CRD it silently falls back to a JSON merge patch, which replaces lists instead of merging them.
Instead:Use a JSON patch on custom resources, where the semantics are explicit.
Expecting a merge patch to add to a list
A JSON merge patch REPLACES an array wholesale. Patching one container in a list of three deletes the other two.
Instead:Use a strategic merge patch with the right merge key, or a JSON patch with an index.
Setting a field to null to leave it alone
In a merge patch, null means delete the key.
Instead:Omit the field to leave it unchanged.
What it knows, and what it cannot know
Strategic merge is not a general algorithm. Everything below follows from where its rules are actually stored.
The merge keys are Go struct tags
Strategic merge knows containers merge on name and ports merge on containerPort because those strings are written into patchMergeKey tags on the API server's own types. They are not in the OpenAPI schema and they are not derivable from your object. Where a path is outside the table used here, this page says so rather than inventing a key.
A custom resource has no such tags
kubectl patch with the default type against a CustomResource comes back UnsupportedMediaType and changes nothing. kubectl apply and Kustomize fall back to JSON merge patch on the same object, so every list is replaced. Same field names, same YAML, opposite result, and nothing on the object hints at it.
Atomic lists that look mergeable
tolerations, command, args, envFrom, Ingress rules, Role rules and RoleBinding subjects carry no merge key, so even the strategic default replaces them wholesale. Patching one toleration onto a Deployment discards the ones already there.
finalizers go the other way
metadata.finalizers is patchStrategy merge on a list of plain strings, which means strategic merge unions the two lists and can only ever add. That is why patching finalizers to [] appears to succeed and leaves the namespace stuck, and why the answer is --type=merge.
JSON Pointer eats your annotation keys
RFC 6901 uses / as its separator, so kubernetes.io/ingress.class has to be written kubernetes.io~1ingress.class. Unescaped, the pointer splits into two segments and the operation fails as a missing path. When that happens here, the corrected pointer is printed.
Rejected means nothing applied
A JSON Patch is atomic. A remove on a path that is not there, an index past the end of a list, or a failing test aborts the whole request, including the operations before it that would have worked on their own. The verdict names the operation and the reason.
The limits, stated rather than implied
This applies the patch algorithm and nothing else. It does not run
admission or mutating webhooks, does not apply API server defaulting, and
does not validate the result against your cluster's schema, so a result
shown here can still be rejected on submission. The merge keys come from a
table of the paths people actually patch rather than from the full API
surface: a list at a path outside it is reported as unmodelled, with the
JSON merge behaviour shown. When you have cluster access,
kubectl patch --dry-run=server is the
authoritative answer, because it asks the API server that owns the struct
tags.
kubectl patch has three algorithms and picks the dangerous one by default
kubectl patch --type takes strategic, merge or json. They agree on almost everything and disagree on lists, which is the only part anyone actually patches. The difference is not a preference: one of them will delete every container except the one you named.
JSON Merge Patch replaces lists, always
RFC 7386 is four rules long. Mappings merge recursively, a null value deletes a key, and anything else replaces what is there. A list is anything else. So a patch naming one container by name does not update that container: it replaces the containers array with a one-element array, and everything that was in the others is gone, along with every field of the named one that the patch did not restate.
original --type=merge -p
containers: containers:
- name: app - name: app
image: nginx:1.25 image: nginx:1.27
env: [LOG_LEVEL=info]
- name: metrics result
image: statsd:v0.26 containers:
- name: app
image: nginx:1.27
env gone. metrics gone. Exit code 0.Strategic merge merges lists by a key you cannot see
The Kubernetes-aware type reads patchStrategy and patchMergeKey struct tags off the Go types compiled into the API server. containers, initContainers, volumes and imagePullSecrets merge on name; ports on containerPort; env on name; volumeMounts on mountPath; hostAliases on ip; ownerReferences on uid. The same patch that destroyed the list above updates one container and leaves the rest untouched. This is the default for kubectl patch, and it is what kubectl apply and Kustomize use.
Container.Ports patchMergeKey:"containerPort"
ServiceSpec.Ports patchMergeKey:"port"
Both are called "ports". Merging a Service port
list on containerPort matches nothing and appends
a duplicate entry instead.Which lists do not merge, and it is not obvious
A field with no patchStrategy tag is atomic: strategic merge replaces it like a merge patch would. tolerations, command, args, envFrom, capabilities.add, Ingress rules and tls, Role rules, RoleBinding subjects and HPA metrics are all in this group. Meanwhile metadata.finalizers is tagged merge on a list of strings, which unions rather than replaces, so a strategic patch can add a finalizer and can never remove one.
kubectl patch ns stuck -p '{"metadata":{"finalizers":[]}}'
namespace/stuck patched <- and unchanged
kubectl patch ns stuck --type=merge -p '{"metadata":{"finalizers":[]}}'
namespace/stuck patched <- actually emptyJSON Patch is precise, positional and brittle
RFC 6902 is a list of operations: add, remove, replace, move, copy and test, each addressing a location by JSON Pointer. It is the only type that can remove one element from a list without restating the rest. The cost is that /spec/template/spec/containers/0 means whichever container is first today, so a patch stored in a repository breaks the moment a sidecar is injected ahead of it. add with an index inserts rather than overwrites, and the whole patch is rejected atomically if any operation misses.
- op: test guard against a concurrent change
path: /spec/replicas
value: 2
- op: replace
path: /spec/template/spec/containers/0/image
value: nginx:1.27
test fails -> nothing is applied, exit 1JSON Pointer escaping, which is where Kubernetes patches actually fail
In RFC 6901 a pointer segment escapes / as ~1 and ~ as ~0, and nothing else. Almost every annotation and label key in Kubernetes contains a slash, so almost every pointer at one needs escaping. Unescaped, the pointer splits into two segments and the operation reports the field as missing, which reads like the annotation is not there rather than like a syntax error. Expand ~1 before ~0 when decoding, or ~01 comes back as a slash instead of as the literal ~1 it means.
wrong /metadata/annotations/kubernetes.io/ingress.class
right /metadata/annotations/kubernetes.io~1ingress.class
wrong /metadata/labels/app.kubernetes.io/name
right /metadata/labels/app.kubernetes.io~1nameAnd none of it applies to a custom resource
Strategic merge exists only for kinds whose Go types are compiled into the API server. A CustomResource has no such type, so the API server refuses a strategic patch with UnsupportedMediaType and kubectl patch fails outright. Client-side kubectl apply and Kustomize fall back to JSON merge patch for the same reason, which means a Kustomize patch against an Argo CD Application or a Prometheus behaves like the destructive column above while the identical patch against a Deployment behaves like the safe one. Server-side apply is the exception: it reads listType and listMapKey markers out of the CRD's own schema, so it does merge lists on a custom resource.
kubectl patch prometheus main -p '{"spec":{"replicas":3}}'
Error from server (UnsupportedMediaType): the body of the
request was in an unknown format
kubectl patch prometheus main --type=merge -p '...' works
kubectl patch prometheus main --type=json -p '...' works
kubectl apply --server-side -f ... merges lists