Patches Dictionary

This lesson shows how to update a key inside a dictionary (specifically: labels on a Pod template) in a Kubernetes resource using both JSON Patch (RFC 6902) and Strategic Merge Patch via Kustomize. You’ll see concise examples that replace, add, and remove a label key on a Deployment and the exact kustomization/patch files required.

When you change labels on a Pod template, consider whether spec.selector.matchLabels also needs to be updated so the Deployment continues to select the updated Pods. Failing to update the selector may cause unexpected Deployment behavior.

Summary: When to use JSON 6902 vs Strategic Merge Patch

Patch Type	Typical Use Case	Example snippet
JSON 6902 (RFC 6902)	Precise, atomic ops: `add`, `replace`, `remove` on a JSON path	`- op: replace\n path: /spec/template/metadata/labels/component\n value: web`
Strategic Merge Patch	Declarative merge that preserves unspecified fields; convenient for simple key additions/replacements	`spec:\n template:\n metadata:\n labels:\n org: KodeKloud`

Replace a key in a dictionary using JSON 6902

Original Deployment (api-deployment.yaml):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
    spec:
      containers:
      - name: nginx
        image: nginx

kustomization.yaml with an inline JSON 6902 patch that replaces the component label under the Pod template:

patches:
- target:
    kind: Deployment
    name: api-deployment
  patch: |-
    - op: replace
      path: /spec/template/metadata/labels/component
      value: web

Result (after applying the patch): the Pod template component label becomes web while the Deployment’s spec.selector.matchLabels still contains the original api value (update the selector if you intend to match the new label).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: web
    spec:
      containers:
      - name: nginx
        image: nginx

Replace a key in a dictionary using a Strategic Merge Patch

Use an external patch file and reference it from kustomization.yaml. kustomization.yaml:

patches:
  - label-patch.yaml

label-patch.yaml (strategic merge patch — include only identifying fields and the fields to change):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    metadata:
      labels:
        component: web

Kustomize will merge label-patch.yaml into the original Deployment, resulting in the Pod template label component: web (again, update spec.selector.matchLabels if you need the selector to match the updated Pods). Resulting fragment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    metadata:
      labels:
        component: web

Add a new key in a dictionary using JSON 6902

Original Deployment (api-deployment.yaml):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
    spec:
      containers:
      - name: nginx
        image: nginx

kustomization.yaml with an inline JSON 6902 patch that adds a new label org: KodeKloud under the Pod template:

patches:
- target:
    kind: Deployment
    name: api-deployment
  patch: |-
    - op: add
      path: /spec/template/metadata/labels/org
      value: KodeKloud

Result: the Pod template includes both component: api and org: KodeKloud.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
        org: KodeKloud
    spec:
      containers:
      - name: nginx
        image: nginx

Add a new key in a dictionary using a Strategic Merge Patch

Using an external patch file referenced by kustomization.yaml: kustomization.yaml:

patches:
  - label-patch.yaml

label-patch.yaml (strategic merge patch):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    metadata:
      labels:
        org: KodeKloud

Kustomize will merge the new label into the existing Pod template metadata, resulting in:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    metadata:
      labels:
        component: api
        org: KodeKloud

Remove a key from a dictionary using JSON 6902

Original Deployment (api-deployment.yaml) contains two labels:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
        org: KodeKloud
    spec:
      containers:
      - name: nginx
        image: nginx

kustomization.yaml with an inline JSON 6902 patch that removes the org label:

patches:
- target:
    kind: Deployment
    name: api-deployment
  patch: |-
    - op: remove
      path: /spec/template/metadata/labels/org

Result: the org label is removed from the Pod template; only component: api remains.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
    spec:
      containers:
      - name: nginx
        image: nginx

Remove a key from a dictionary using a Strategic Merge Patch

With Strategic Merge Patch you indicate deletion by setting a key to null in the patch file. kustomization.yaml:

patches:
  - label-patch.yaml

label-patch.yaml (strategic merge patch to remove the org label):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    metadata:
      labels:
        org: null

Kustomize interprets org: null as “remove this key” and merges accordingly, yielding:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    metadata:
      labels:
        component: api

Best practices and tips

Use JSON 6902 for precise, targeted operations when you need to guarantee the exact change (add/replace/remove a single field).
Use Strategic Merge Patch for declarative, easy-to-read patches that merge cleanly with existing objects.
Always re-evaluate spec.selector.matchLabels when changing Pod template labels to ensure Deployment selection remains correct.
Keep patch files small and focused — include only the identifying fields and the fields you intend to change.

Links and references

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

Patches Dictionary

Replace a key in a dictionary using JSON 6902

Replace a key in a dictionary using a Strategic Merge Patch

Add a new key in a dictionary using JSON 6902

Add a new key in a dictionary using a Strategic Merge Patch

Remove a key from a dictionary using JSON 6902

Remove a key from a dictionary using a Strategic Merge Patch

Watch Video

​Replace a key in a dictionary using JSON 6902

​Replace a key in a dictionary using a Strategic Merge Patch

​Add a new key in a dictionary using JSON 6902

​Add a new key in a dictionary using a Strategic Merge Patch

​Remove a key from a dictionary using JSON 6902

​Remove a key from a dictionary using a Strategic Merge Patch

Watch Video

Replace a key in a dictionary using JSON 6902

Replace a key in a dictionary using a Strategic Merge Patch

Add a new key in a dictionary using JSON 6902

Add a new key in a dictionary using a Strategic Merge Patch

Remove a key from a dictionary using JSON 6902

Remove a key from a dictionary using a Strategic Merge Patch