Kustomize Problem Statement and Ideology

Before we explain what Kustomize is and how to use it, let’s examine the real problem Kustomize was designed to solve and the design choices behind it. Consider a minimal NGINX Deployment that creates a single pod:

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

Now imagine you manage multiple environments — dev (local), stg (staging), and prod (production) — with environment-specific behavior such as different replica counts:

Environment	Replica count
dev	1
stg	2
prod	5

A naive approach is to copy the same YAML files into each environment directory and update only the environment-specific values (like replicas) in each copy. For example, you might duplicate the Deployment for each environment and run:

# Apply development environment manifests
$ kubectl apply -f dev/
deployment.apps/nginx-deployment created

# Apply staging environment manifests
$ kubectl apply -f stg/
deployment.apps/nginx-deployment created

This “copy and edit” method works initially but quickly becomes unmanageable. As you add more resources (Services, ConfigMaps, Secrets, additional Deployments, etc.), you must remember to copy each new or changed manifest into every environment folder. Missing a copy or forgetting to synchronize changes causes drift and inconsistent environments.

A dark-themed directory listing titled "Why Kustomize" showing dev, stg, and prod folders, each containing nginx-depl.yml and service.yml files. Folder icons are blue and file icons are red.

Kustomize addresses this duplication problem with a simple, declarative approach: keep one canonical set of manifests (the base) and express only environment-specific changes (overlays). Because Kustomize operates on plain YAML and uses non-templated patches, manifests stay readable and compatible with standard YAML tooling (linters, validators, CI/CD pipelines). Core concepts

Term	Meaning
Base	YAML resources that are common across environments — the canonical default manifests.
Overlay	A set of files describing only the differences to apply to the base for a specific environment.

Example — base (shared) NGINX Deployment:

# base/nginx-depl.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: nginx
  template:
    metadata:
      labels:
        component: nginx
    spec:
      containers:
        - name: nginx
          image: nginx

Because the base defines replicas: 1, the dev environment typically needs no replica override. For stg and prod we create small overlay patches that adjust only the replica count. Staging overlay patch:

# overlays/stg/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 2

Production overlay patch:

# overlays/prod/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 5

Each overlay requires a kustomization.yaml that references the base and the patch. For example, the staging overlay’s kustomization.yaml:

# overlays/stg/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patchesStrategicMerge:
  - replicas-patch.yaml

When you run Kustomize (or kubectl apply -k), Kustomize:

Loads the base resources,
Applies the overlay patches/transformations,
Produces the final manifests for that environment.

You never duplicate full manifests for every environment — you express only what changes. Repository layout (common pattern)

k8s/
├─ base/
│  ├─ kustomization.yaml
│  ├─ nginx-depl.yaml
│  ├─ service.yaml
│  └─ redis-depl.yaml
└─ overlays/
   ├─ dev/
   │  ├─ kustomization.yaml
   │  └─ config-map.yaml
   ├─ stg/
   │  ├─ kustomization.yaml
   │  └─ config-map.yaml
   └─ prod/
      ├─ kustomization.yaml
      └─ config-map.yaml

Workflow summary

Put shared manifests in base/.
Create one overlay folder per environment under overlays/.
In each overlay, reference the base and include only the patches/overrides and environment-specific resources.
Build and apply environment manifests with Kustomize or kubectl apply -k overlays/<env> (use backticks for angle brackets).

Kustomize is integrated into kubectl (you can use kubectl kustomize or kubectl apply -k), but the embedded Kustomize version in kubectl may lag behind the standalone Kustomize release. If you require the latest Kustomize features, consider installing the standalone Kustomize CLI.

Kustomize operates on plain YAML without introducing templating syntax. Define base resources as regular YAML and describe overlays as YAML patches — there is no templating language to learn, unlike Helm.

The Kustomize version bundled into kubectl may not include the newest features or flags. If you depend on recent Kustomize functionality, install the standalone CLI from the official Kustomize releases or follow the project documentation.

A presentation slide titled "Kustomize" with bullet points explaining that Kustomize is built into kubectl (though you may want the standalone CLI for the latest version), avoids complex templating like Helm, and uses plain YAML artifacts.

Kustomize is intentionally simple: reuse common manifests, declare only the differences per environment, and keep everything as plain, valid YAML. For more details, see the Kustomize documentation and the official Kubernetes documentation.

Introduction

Kustomize Overview

Kustomize Basics

Secret/Config Generator

Other Commands

Capstone Project

Kustomize Problem Statement and Ideology

Watch Video