kubectl patch --type=json: Usage, Options & Common CI Errors

Apply precise add/replace/remove operations at exact JSON paths.

kubectl patch --type=json applies an RFC 6902 JSON Patch: an ordered list of add/replace/remove/test operations against explicit paths. It is the precise tool when strategic-merge cannot express the edit, especially on custom resources.

What it does

kubectl patch RESOURCE NAME --type=json -p '[...ops...]' runs each operation in order. op is add, replace, remove, copy, move, or test; path is a JSON Pointer where / separates keys and ~1 escapes a literal / (and ~0 a ~). Array indices are numeric, and a trailing - appends to an array.

Common usage

Terminal

kubectl patch deploy/web --type=json \
  -p '[{"op":"replace","path":"/spec/replicas","value":3}]'
kubectl patch deploy/web --type=json \
  -p '[{"op":"add","path":"/spec/template/metadata/labels/tier","value":"web"}]'
kubectl patch ingress/web --type=json \
  -p '[{"op":"remove","path":"/spec/rules/0/http/paths/1"}]'

Common errors in CI

A replace or remove against a path that does not exist fails with "the server rejected our request" / "add operation does not apply: doc is missing path" - use add to create the parent first, or guard that the path exists. Annotation/label keys with dots and slashes must be escaped: /metadata/annotations/example.com~1foo for the key example.com/foo. JSON-patch is the safe choice for CRDs (which have no strategic-merge metadata) where strategic patches silently misbehave. Operations apply in order, so an add that a later remove depends on must come first.

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 replace --force: Usage, Options & Common CI Errorskubectl replace --force deletes and recreates a resource to change immutable fields. When to reach for it ove… kubectl set image: Usage, Options & Common CI Errorskubectl set image promotes a Deployment to a new image tag and triggers a rollout. The CI deploy step, contai… 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…