Kustomize Problem Statement idealogy

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.

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.

Recommended Folder Structure

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.

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.

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.

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.