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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes