Kustomize patches — strategic merge vs JSON 6902 vs images transformer

Kustomize supports multiple patch types: strategic merge, JSON 6902, and the images transformer. This lesson walks each, the trade-offs, and the discipline.

Strategic merge patches

# patch-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 5
  template:
    spec:
      containers:
        - name: myapp
          image: myapp:2.0.0
          resources:
            requests:
              cpu: 500m
              memory: 512Mi

Strategic merge patches:

• Merge by field name (not by position).
• Lists are merged by element (e.g., containers by name).
• Fields not in the patch are inherited from the base.
• Kubernetes-native: the API server uses the same merge strategy.

# kustomization.yaml
patches:
  - path: patch-deployment.yaml
    target:
      kind: Deployment
      name: myapp

The patch is applied to the resource matching the target selector.

JSON 6902 patches

# patch-deployment.yaml
- op: replace
  path: /spec/replicas
  value: 5
- op: replace
  path: /spec/template/spec/containers/0/image
  value: myapp:2.0.0
- op: add
  path: /spec/template/spec/containers/0/env
  value:
    - name: LOG_LEVEL
      value: debug

JSON 6902 patches:

• Operate on the JSON representation of the resource.
• Operations: add, remove, replace, move, copy, test.
• Paths are JSON Pointer notation.
• Precise: each operation specifies exactly what to change.

patches:
  - path: patch-deployment.yaml
    target:
      version: v1
      kind: Deployment
      name: myapp
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

Use JSON 6902 when strategic merge cannot express the change (e.g., inserting an element into a list at a specific position).

Images transformer

images:
  - name: myapp
    newName: myapp
    newTag: "2.0.0"
  - name: postgres
    newName: registry.example.com/postgres
    newTag: "16"

The images transformer rewrites image references without patching the Deployment:

• name — the original image name (without tag).
• newName — the new image name.
• newTag — the new tag.

The transformer finds every container with the original image and rewrites it. This is cleaner than patching the Deployment directly.

Choosing the right patch type

flowchart TD
    A[Patch type] --> B{Image change?}
    B -->|Yes| C[Images transformer]
    B -->|No| D{Field merge?}
    D -->|Yes| E[Strategic merge]
    D -->|No, precise operation| F[JSON 6902]

The choice:

• Image change. Use the images transformer.
• Field merge (typical overrides). Use strategic merge.
• Precise operations (insert, remove, replace at path). Use JSON 6902.

Most patches in a typical overlay are strategic merge. JSON 6902 is for the cases strategic merge cannot handle. The images transformer is for image version changes.

Quiz

The operational discipline

Kustomize patches in production rest on five non-negotiable elements:

• Use images transformer for image changes. Cleaner than patching.
• Use strategic merge for typical overrides. Kubernetes-native; predictable.
• Use JSON 6902 for precise operations. Strategic merge cannot express every change.
• Test the rendered output. Always kubectl kustomize before applying.
• Review patches in PRs. Patches are changes; they go through review like any other change.

The patch type is a tool, not a preference. The discipline is to choose the right tool for the task.