Kustomization Tutorial

Nahla Thabet — Tue, 28 Oct 2025 20:56:22 +0000

What is Kustomize?

Kustomize is a configuration management solution that leverages layering to preserve the base settings of your applications and components by overlaying declarative yaml artifacts (called patches) that selectively override default settings without actually changing the original files.

Say that you have 3 env you want to deploy the same application on them but every env has different number of replica, for example this wordoress deployment, and I have staging and prod environment.

Using Kustomize: A simple guide

first we should create folder for base manifests file and create folders for every env under overlay section.

Kustomize Patching Strategies

we've set up our directory structure, let's explore the different ways to patch our WordPress deployment for different environments.

- base/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wordpress
  labels:
    app: wordpress
spec:
  replicas: 2
  selector:
    matchLabels:
      app: wordpress
  template:
    metadata:
      labels:
        app: wordpress
    spec:
      containers:
      - name: wordpress
        image: wordpress:apache  
        ports:
        - containerPort: 80
        env:
        - name: WORDPRESS_DB_HOST
          value: cluster1-haproxy.mysql-cluster.svc.cluster.local:3306
        - name: WORDPRESS_DB_NAME
          value: wordpress
        - name: WORDPRESS_DB_USER
          value: wp
        - name: WORDPRESS_DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: wp-secret
              key: wp-password
        resources:
          requests:
            memory: "256Mi"
            cpu: "200m"
          limits:
            memory: "512Mi"
            cpu: "400m"
        volumeMounts:
        - name: wordpress-data
          mountPath: /var/www/html
      volumes:
      - name: wordpress-data
        persistentVolumeClaim:
          claimName: wordpress-pvc

- base/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml

Method 1: Strategic Merge Patch

Strategic Merge Patch is the simplest approach. You define only the fields you want to change, and Kustomize intelligently merges them with the base configuration.

overlays/staging/replica-patch.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wordpress
spec:
  replicas: 3

overlays/staging/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

patchesStrategicMerge:
  - replica-patch.yaml

For production, you might want more replicas and different resource limits:

overlays/prod/deployment-patch.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wordpress
spec:
  replicas: 5
  template:
    spec:
      containers:
      - name: wordpress
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"

overlays/prod/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

patchesStrategicMerge:
  - deployment-patch.yaml

Method 2: JSON 6902 Patches

JSON 6902 patches provide more precise control over modifications using JSON Patch operations (add, remove, replace, move, copy, test).

- overlays/prod/deployment-patch.yaml

- op: replace
  path: /spec/replicas
  value: 5
- op: replace
  path: /spec/template/spec/containers/0/resources/requests/memory
  value: "512Mi"
- op: replace
  path: /spec/template/spec/containers/0/resources/limits/memory
  value: "1Gi"

- overlays/prod/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

patches:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: wordpress
    path:  deployment-patch.yaml

Install Kustomize

run the following:

curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"  | bash

Move Kustomize to your path, so that it can be accessed system wide:

sudo mv kustomize /usr/local/bin

Kustomize testing and applying

Testing Kustomize transformations
Always be sure to test Kustomize patches and transformations before applying them. Two useful commands for this are using kubectl apply -k
with the --dry-run=client -o yaml flag as well as and kubectl diffplugin.

Example usage:
kubectl apply -k <path-to-your-kustomization-directory> --dry-run=client -o yaml
This command outputs the YAML rendered by combining the base resources and applying the patches defined in the <path-to-your-kustomization-directory> directory, without actually applying any changes. You can inspect the output to ensure the patches were applied correctly.

Use kubectl diff to compare the changes between your live cluster resources and the new configurations generated by Kustomize.

Example usage:
kubectl diff -k <path-to-your-kustomization-directory>
This will compare the current state of your cluster with the resources that Kustomize would apply and show a diff of the differences.

Apply Patches
Once you have confirmed that your overlays are correct and choose which env you want to apply the changes on it, use the kubectl apply -k overlays/<env-name> command to apply the the settings to your cluster:
kubectl apply -k overlays/staging
kubectl apply -k overlays/prod

DEV Community: Nahla Thabet