kubectl patch: Strategic Merge Patches
kubectl patch applies a partial update to a live resource; the default strategic merge patch understands Kubernetes list semantics.
When you want to flip one field without re-applying a whole manifest, patch is the surgical tool. The default strategic type merges intelligently.
What it does
kubectl patch sends a partial update to the API server. The default --type=strategic uses each field schema to merge: named lists (like containers) are merged by key rather than replaced wholesale, so you can change one container image without dropping the others.
Common usage
# bump a container image via strategic merge
kubectl patch deployment api -p \
'{"spec":{"template":{"spec":{"containers":[{"name":"api","image":"api:v2"}]}}}}'
# scale replicas
kubectl patch deployment api -p '{"spec":{"replicas":4}}'
# patch from a file
kubectl patch deploy api --patch-file patch.yamlOptions
| Flag | What it does |
|---|---|
| --type=strategic | Strategic merge patch (default), honors list-merge keys |
| -p, --patch <json> | Inline patch body |
| --patch-file <file> | Read the patch from a file |
| --subresource=status | Patch a subresource such as status or scale (1.24+) |
| --dry-run=server | Send to the API server but do not persist |
In CI
Strategic merge needs a known schema, so it only works on built-in types, not arbitrary CRDs. For a CRD, use --type=merge or --type=json. Use --dry-run=server first to confirm the patch is accepted before it mutates a live workload.
Common errors in CI
"Error from server: cannot change ... field is immutable" means you patched a field like a Service clusterIP or a selector that cannot be edited; recreate instead. "unable to find api field in struct" means the patch JSON references a field that does not exist (a typo or wrong nesting). On a CRD, strategic merge falls back to a plain merge and may replace a whole list unexpectedly; switch to a json patch for precise list edits.