Kustomize

Kustomize Basics

Patches list

When customizing Kubernetes resources, you often need to modify lists—such as the containers array in a Deployment. Kustomize supports two patch strategies:

  • JSON 6902 patches: precise, index-based operations (add, replace, remove).
  • Strategic Merge Patches (SMP): declarative, merge-key based edits.

Below is a quick comparison:

OperationJSON 6902 PatchStrategic Merge Patch
Replace itemTargets an explicit indexMatches on name merge key
Add itemUses add with /- or an indexAppends new entries by default
Remove itemUses remove with a specific indexUses $patch: delete on the merge key

Base Deployment Example

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

Note

Every entry in spec.template.spec.containers is a YAML list item, so it begins with -.


1. Replacing a Container

1.1 JSON 6902 Patch

Add to your kustomization.yaml:

patches:
  - target:
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: replace
        path: /spec/template/spec/containers/0
        value:
          name: haproxy
          image: haproxy

Resulting section:

spec:
  template:
    spec:
      containers:
        - name: haproxy
          image: haproxy

1.2 Strategic Merge Patch

Create a file replace-container.yaml:

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

Reference it in kustomization.yaml:

patches:
  - replace-container.yaml

Kustomize finds the item with name: nginx and updates its image.


2. Adding a Container

2.1 JSON 6902 Patch

To append at the end:

patches:
  - target:
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: add
        path: /spec/template/spec/containers/-
        value:
          name: haproxy
          image: haproxy

Result:

spec:
  template:
    spec:
      containers:
        - name: nginx
          image: nginx
        - name: haproxy
          image: haproxy

You can also insert at a specific index by replacing - with 1, 2, etc.

Warning

Using path: /containers/- always appends. For precise position, specify the index.

2.2 Strategic Merge Patch

File add-container.yaml:

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

In your kustomization.yaml:

patches:
  - add-container.yaml

The new haproxy container is appended automatically.


3. Removing a Container

Assume this deployment:

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

3.1 JSON 6902 Patch

To remove the second container (index 1):

patches:
  - target:
      kind: Deployment
      name: api-deployment
    patch:
      - op: remove
        path: /spec/template/spec/containers/1

After applying, only web remains.

3.2 Strategic Merge Patch

Create remove-database.yaml:

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

Include it in kustomization.yaml:

patches:
  - remove-database.yaml

Kustomize deletes the container with name: database.


Watch Video

Watch video content

Practice Lab

Practice lab

Previous
Patches Dictionary