kubectl patch: Usage, Options & Common CI Errors

Surgically update one field from a script - pick the right patch type.

kubectl patch applies a partial update to a resource and is the scriptable alternative to edit. Choosing the correct --type (strategic, merge, or json) is what makes it work the way you expect.

What it does

kubectl patch RESOURCE NAME -p '<patch>' merges a fragment into the live object. --type=strategic (the default) understands Kubernetes list-merge semantics; --type=merge is a plain RFC 7386 JSON merge that replaces lists wholesale; --type=json applies an RFC 6902 operation list (add/replace/remove at explicit paths). Pick by whether you need list-aware merging or precise path edits.

Common usage

Terminal

kubectl patch deploy/web -p '{"spec":{"replicas":3}}'
kubectl patch deploy/web --type=json \
  -p '[{"op":"replace","path":"/spec/replicas","value":3}]'
kubectl patch svc/web --type=merge -p '{"spec":{"type":"LoadBalancer"}}'

Common errors in CI

The most common mistake is the wrong --type: a strategic-merge patch on a custom resource (which has no merge metadata) silently misbehaves - use --type=merge or --type=json for CRDs. "The order in patch list ... doesn't match" or a list being replaced instead of merged means you needed strategic but used merge. A JSON-patch "op" against a path that does not exist fails with "the server rejected our request"; add the parent first or use add. And patching an immutable field returns "field is immutable" - the field cannot change in place at all.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl edit: Usage, Options & Common CI Errorskubectl edit opens a resource in your editor for in-place changes. Why it is an anti-pattern in CI, and the i… kubectl set: Usage, Options & Common CI Errorskubectl set updates specific fields on existing resources - image, env, resources. The go-to command for CI i… kubectl "field is immutable" - Fix Immutable Field Updates in CIFix kubectl "field is immutable" on apply in CI - changing a Deployment selector, Job template, PVC spec, or…