Kustomize is a configuration management tool built directly into Kubernetes (via kubectl kustomize or kubectl apply -k). It allows you to customize raw, template-free YAML files for multiple environments (like Development, Staging, and Production) without duplicating code.

Before Kustomize, teams used tools like Helm, which rely on a “string replacement template” approach (e.g., image: {{ .Values.imageName }}). Kustomize takes a different path: it reads standard Kubernetes YAML files as structured data objects and merges them together using a Base and Overlay design pattern.

1. The Core Concept: Base and Overlays

Think of Kustomize like transparent layers in a photo-editing app.

• The Base: This is your foundation. It contains the standard, plain Kubernetes manifests (Deployments, Services, etc.) that represent how your application looks generally, regardless of where it runs.
• The Overlays: These are the specific modifications (the “patches”) for each environment. You create an overlay folder for development and another for production. The overlays only contain the specific values that need to change (like changing a replica count from 1 to 10, or changing a database URL).

2. A Real-World Directory Layout

A typical Kustomize project is organized into strict directory structures:

Plaintext

├── my-app/
│   ├── base/                         # The shared foundation
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── kustomization.yaml        # Lists the resources above
│   │
│   └── overlays/                     # Environment variations
│       ├── development/
│       │   ├── kustomization.yaml    # Points to base + applies dev patches
│       │   └── replica-patch.yaml
│       │
│       └── production/
│           ├── kustomization.yaml    # Points to base + applies prod patches
│           └── replica-patch.yaml

3. How the Files Look (An Example)

Let’s say your base/deployment.yaml specifies a web app with 1 replica. Here is how you use an overlay to scale that up to 5 replicas in Production without copying the entire deployment file.

Step A: The Production Overlay Configuration (overlays/production/kustomization.yaml)

This file tells Kustomize where the base is and what changes to apply over it.

YAML

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
# 1. Point to the shared foundation
resources:
  - ../../base
# 2. Add an environment-specific prefix to all resource names (e.g., "prod-my-app")
namePrefix: prod-
# 3. Apply the custom patches
patches:
  - path: replica-patch.yaml

Step B: The Production Patch (overlays/production/replica-patch.yaml)

Instead of rewriting a 50-line deployment manifest, your patch file only targets the exact field you want to modify:

YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app # Must match the name in the base exactly
spec:
  replicas: 5  # Override the base value of 1

When you run kubectl apply -k overlays/production/, Kustomize intelligently compiles these files in memory and outputs a final, standard Kubernetes manifest with 5 replicas and a prod- prefix.

4. Powerful Built-in Features

Beyond basic overriding, Kustomize includes specialized tools called Generators and Transformers:

• ConfigMap and Secret Generators: Instead of writing complex ConfigMap YAMLs, you point Kustomize to a plain configuration file (like config.properties). It reads the file, generates the Kubernetes ConfigMap, and appends a unique hash to the name (e.g., my-config-f597dh7). If the content of that properties file changes, the hash changes, forcing Kubernetes to perform a rolling update of your pods automatically.
• Common Labels and Annotations: You can define a single label rule in your overlay configuration (like env: production), and Kustomize will automatically inject that label into every single Deployment, Pod, Service, and Ingress rule inside that folder hierarchy.

Summary: Kustomize vs. Helm