# Kustomize JSON 6902 Patches

> JSON 6902 patches apply precise add/replace/remove operations to manifests. Reference for the op/path/value syntax, targets, and the path errors in CI.

Source: https://latchkey.dev/learn/command-reference/kustomize-patches-json6902  
Updated: 2026-06-30

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.

## 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.

```Terminal
# 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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### Kustomize JSON 6902 Patches?

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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt