Skip to main content
Before exploring what Kustomize is and how to use it, this article examines the challenges it addresses and explains the motivation behind its creation.

​
The Traditional Approach

Consider a simple example of a single NGINX deployment defined in a YAML file. This deployment creates one NGINX 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
Imagine you have multiple environments like development, staging, and production. You might require the same deployment to behave differently in each environment. For example, on a local development machine you need only one replica, staging might require two or three, and production could need five or more. A common solution is to duplicate the YAML file into individual directories for each environment and then modify environment-specific parameters (such as replica counts). For instance: 
# dev/nginx.yml
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

# stg/nginx.yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      component: nginx
  template:
    metadata:
      labels:
        component: nginx
    spec:
      containers:
        - name: nginx
          image: nginx

# prod/nginx.yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 5
  selector:
    matchLabels:
      component: nginx
  template:
    metadata:
      labels:
        component: nginx
    spec:
      containers:
        - name: nginx
          image: nginx
To apply these configurations, you would run a command like: 
$ kubectl apply -f dev/
deployment.apps/nginx-deployment created
And similarly for the staging and production directories. While this approach can work for a handful of resources, it becomes both tedious and error-prone as more resources are added. Every new resource (like a service defined in service.yaml) must be copied across every environment directory. Over time, this leads to mismatched configurations and unnecessary maintenance overhead.
To maintain consistency and reduce redundancy, it is essential to preserve a single source of truth for configurations, modifying only what is needed per environment.

​
The Need for a Better Approach

The key challenge is to reuse Kubernetes configurations while only modifying what differs by environment. Instead of duplicating elaborate configuration files for each environment, a solution is needed to treat configurations like code—with a central base configuration and specific layers of changes applied on top.

​
Enter Kustomize

Kustomize provides an elegant solution by introducing two key components: Base configuration and Overlays.

​
Base Configuration

The Base configuration contains resources common to all environments. It represents default values that every environment uses unless explicitly overridden. For example, consider the following base NGINX deployment with one replica by default: 
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

​
Overlays

Overlays allow customization of the base configuration for each environment. Each overlay—whether for development, staging, or production—defines changes specific to that environment. In a development overlay, the default configuration might remain unchanged, while staging and production overlays could modify the replica count to suit their requirements. Kustomize recommends the following folder structure to organize configurations: 
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
In this structure, the base directory holds the common configuration, while the overlays directory contains subdirectories for each environment with their respective configuration adjustments.
The image shows a directory structure for Kubernetes configurations with folders for dev, stg, and prod environments, each containing "nginx-depl.yml" and "service.yml" files.

​
How Kustomize Works

Kustomize takes the Base configuration and the overlays to produce a final, environment-specific Kubernetes manifest that you can apply to your cluster. One major benefit is that Kustomize is built into kubectl, eliminating the need for additional installation (though you can opt to install a newer version if desired). Unlike templating systems such as Helm, Kustomize operates directly on standard YAML files—no templating language to learn. This results in configuration files that are simple, easy to validate, and maintain.
The image illustrates the Kustomize process, combining a base and overlay to produce final manifests.

​
Simplicity and Scalability

By separating the common configuration (Base) from environment-specific modifications (Overlays), Kustomize streamlines application deployment. Each overlay contains only the necessary changes for its environment, reducing duplication and minimizing errors during updates.
The image describes Kustomize's integration with kubectl, its simplicity over templating systems, and its use of plain YAML for validation and processing.
Kustomize embraces simplicity by keeping every artifact as plain YAML—no extra templating syntax or processing overhead is required. This advantage is pivotal for efficiently managing Kubernetes deployments across various environments.
Kustomize offers a scalable and maintainable way to manage environment-specific configuration changes without duplicating entire sets of configuration files. Its use of base configurations and overlays minimizes errors and streamlines the deployment process.

Watch Video