Kustomize JSON 6902 Patches

A JSON 6902 patch applies ordered add, replace, and remove operations at exact JSON pointer paths.

When strategic-merge cannot express a change (for example editing one item in a list by index), JSON 6902 gives surgical control via RFC 6902 operations.

What it does

A JSON 6902 patch is a list of operations, each with an op (add, replace, remove, copy, move, test), a path written as a JSON pointer, and for add/replace a value. Kustomize applies them in order to the targeted resource. The patch needs a target so Kustomize knows which resource to edit.

Common usage

kustomization.yaml

# kustomization.yaml
patches:
  - target:
      kind: Deployment
      name: myapp
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: TIER
          value: prod

Operations

op	What it does
add	Insert a value at path (use - to append to an array)
replace	Overwrite the value at path
remove	Delete the value at path
copy / move	Copy or move a value between paths
test	Assert a value, aborting the patch if it differs

In CI

JSON pointer paths are zero-indexed and must escape / as ~1 and ~ as ~0. To append to a list use the trailing /-. Render with kustomize build and diff before applying so an index-based path that drifted with the base shows up in review.

Common errors in CI

"add operation does not apply: doc is missing path" means the parent path does not exist yet, so add the parent first or use a path that exists. "replace operation does not apply: doc is missing path" is the same cause for replace. "remove operation does not apply" means the path is already absent. An out-of-range array index also produces a missing-path error.