Patches List

The same patching techniques you use to remove, replace, and add keys in dictionaries also apply to YAML lists—such as the spec.template.spec.containers list in a Kubernetes Deployment. List fields are ordered and each item has a 0-based index. Kustomize supports two common patch styles for list operations:

JSON 6902 patches: index-based operations (precise control, insert/remove at a specific position).
Strategic merge patches: merge-key-based operations (match list items by a key such as name).

List basics:

JSON 6902 patches act on list indices (0-based).
Use - at the end of a JSON 6902 path to append to the list.
Strategic merge patches match list items by merge key (commonly name for containers).

Quick comparison

Operation	Patch type	Behavior	When to use
Replace entire list item	JSON 6902	Replace by index (e.g. `/spec/template/spec/containers/0`)	When you need exact positional replacement
Modify fields of a list item	Strategic Merge	Match item by merge key (e.g. `name`) and merge fields	When you want to update specific fields without touching others
Append or insert items	JSON 6902	Use `path: /.../containers/-` to append or `/.../containers/0` to insert	When order matters or you need a specific index
Add distinct item	Strategic Merge	Adds new list item when merge key differs	When adding a new container identified by a unique `name`
Remove an item	JSON 6902	`op: remove` at the item’s index	When you need to remove by exact position
Remove an item	Strategic Merge	Use `$patch: delete` with merge key	When you know the merge key (`name`) of the item to delete

Example base Deployment

Use this base Deployment as api-depl.yaml for the examples below.

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

Replace a container (JSON 6902)

To replace an entire container at a specific index, use a JSON 6902 patch and the replace operation. The example below replaces the container at index 0 with a new container named haproxy. kustomization.yaml (using patchesJson6902):

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - api-depl.yaml

patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: replace
        path: /spec/template/spec/containers/0
        value:
          name: haproxy
          image: haproxy

Result: the container at index 0 is replaced with the haproxy container (both name and image changed).

Using index-based (JSON 6902) operations can be fragile if prior patches or changes reorder the list. Prefer strategic merge when you only need to update specific fields by name.

Replace a container’s image (strategic merge patch)

Strategic merge patches match list items by their merge key (commonly name) and merge fields. This is ideal when you want to update a field (like image) without replacing the whole container object. kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - api-depl.yaml

patchesStrategicMerge:
  - label-patch.yaml

label-patch.yaml (strategic merge patch):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    spec:
      containers:
        - name: nginx
          image: haproxy

When Kustomize performs the strategic merge, it finds the containers item with name: nginx and updates the image field. The container retains its name but now uses the haproxy image.

Add a container (JSON 6902)

To append or insert a new container using JSON 6902, use op: add and the list path. Use a trailing - to append to the end of the list, or specify an index to insert at a particular position. kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - api-depl.yaml

patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: add
        path: /spec/template/spec/containers/-
        value:
          name: haproxy
          image: haproxy

Notes:

path: /spec/template/spec/containers/- appends the new container to the end of the list.
To insert at the front, use /spec/template/spec/containers/0; to insert as the second item, use /spec/template/spec/containers/1, etc.

Result: the Deployment will have both the original nginx container and the new haproxy container.

Add a container (strategic merge patch)

Strategic merge patches can also add new list items when the merge key differs. In this example the base Deployment includes a web container; the patch introduces a new haproxy container, and Kustomize will merge them. Base Deployment example (different base with a web container):

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

kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - api-depl.yaml

patchesStrategicMerge:
  - label-patch.yaml

label-patch.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    spec:
      containers:
        - name: haproxy
          image: haproxy

Result: both web and haproxy containers will be present because the patch adds a new container with a distinct name.

Remove a container (JSON 6902)

To remove an item from a list using JSON 6902, use op: remove and specify the exact index to remove. The example below removes the second container (index 1) from a two-container base. Base Deployment:

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

kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - api-depl.yaml

patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: remove
        path: /spec/template/spec/containers/1

Result: the database container (index 1) is removed, leaving only the web container.

Remove a container (strategic merge patch)

With strategic merge patches, deletion is expressed using the $patch: delete directive. Provide the merge key (name) to identify which list item to delete. Base Deployment (two containers):

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

kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - api-depl.yaml

patchesStrategicMerge:
  - label-patch.yaml

label-patch.yaml (strategic merge patch instructing deletion):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    spec:
      containers:
        - name: database
          $patch: delete

Explanation:

The $patch: delete directive tells Kustomize to remove the container matching name: database from the final merged resource.
If the database container is present in the base, Kustomize removes it during the merge.

Result: the database container is removed; only web remains.

These examples illustrate common list operations in Kustomize:

Use JSON 6902 patches when you need index-level operations (replace at position, insert at specific index, or remove by index).
Use strategic merge patches when you want to match items by key (like name) to add, modify, or delete entries more robustly.

Links and references:

Kustomize docs: https://kubectl.docs.kubernetes.io/references/kustomize/
JSON Patch (RFC 6902): https://tools.ietf.org/html/rfc6902
Kubernetes Deployments: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/

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

Quick comparison

Example base Deployment

Replace a container (JSON 6902)

Replace a container’s image (strategic merge patch)

Add a container (JSON 6902)

Add a container (strategic merge patch)

Remove a container (JSON 6902)

Remove a container (strategic merge patch)

Watch Video

Practice Lab

​Quick comparison

​Example base Deployment

​Replace a container (JSON 6902)

​Replace a container’s image (strategic merge patch)

​Add a container (JSON 6902)

​Add a container (strategic merge patch)

​Remove a container (JSON 6902)

​Remove a container (strategic merge patch)

Watch Video

Practice Lab

Quick comparison

Example base Deployment

Replace a container (JSON 6902)

Replace a container’s image (strategic merge patch)

Add a container (JSON 6902)

Add a container (strategic merge patch)

Remove a container (JSON 6902)

Remove a container (strategic merge patch)