11.01 Kustomize

Abstract

Kustomize is a Kubernetes-native configuration management tool used to customize YAML manifests for different environments without duplicating complete files.

It helps manage dev, staging, and production configurations using a clean base + overlay structure.

Why Kustomize?

In real Kubernetes environments, the same application often needs different settings per environment.

Example:

Environment	Replicas
dev	1
stg	2
prod	5

A basic nginx-deployment.yml may look like this:

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

Question

How do we reuse this deployment for multiple environments while changing only the required values?

Problem with Duplicate YAML Files

A simple approach is to create separate files for each environment:

dev/nginx.yml
stg/nginx.yml
prod/nginx.yml

Each file has mostly the same content, but different replica counts.

# dev/nginx.yml
replicas: 1

# stg/nginx.yml
replicas: 2

# prod/nginx.yml
replicas: 5

This works, but it does not scale well.

Warning

Duplicating full Kubernetes YAML files across environments creates maintenance problems.

If you add a new Service, ConfigMap, or Deployment change, you must remember to update every environment folder.

What Kustomize Solves

Kustomize avoids repeated YAML by separating configuration into:

Concept	Purpose
Base	Common/default Kubernetes manifests
Overlay	Environment-specific changes
Final Manifest	Output generated by combining base + overlay

Base + Overlay = Final Kubernetes Manifests

Success

Kustomize lets you reuse common manifests and patch only what changes per environment.

Kustomize Workflow

base/
  common YAML manifests
      +
overlays/
  dev/
  stg/
  prod/
      ↓
kustomize build
      ↓
final Kubernetes manifests

You can apply the final output directly:

kubectl apply -k overlays/dev
kubectl apply -k overlays/stg
kubectl apply -k overlays/prod

Note

Kustomize is built into kubectl, so you can use kubectl apply -k without installing a separate tool.

Recommended Folder Structure

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

Folder	Description
`base/`	Shared/default configs across all environments
`overlays/dev/`	Development-specific changes
`overlays/stg/`	Staging-specific changes
`overlays/prod/`	Production-specific changes

Tip

Keep common resources in base/ and only environment-specific changes in overlays/.

Base Configuration

The base contains Kubernetes manifests that are common across environments.

`base/nginx-depl.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

`base/kustomization.yaml`

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

resources:
  - nginx-depl.yml

Note

The base can contain default values. These defaults can be changed later by overlays.

Overlay Configuration

Overlays modify the base configuration for a specific environment.

Example: production needs more replicas.

`overlays/prod/replica-patch.yml`

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 5

`overlays/prod/kustomization.yaml`

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

resources:
  - ../../base

patches:
  - path: replica-patch.yml

Apply production configuration:

kubectl apply -k overlays/prod

Example

The production overlay reuses the base deployment and changes only replicas from 1 to 5.

Dev, Staging, and Production Example

DevStagingProduction

# overlays/dev/replica-patch.yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1

kubectl apply -k overlays/dev

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

kubectl apply -k overlays/stg

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

kubectl apply -k overlays/prod

Preview Before Applying

Before applying changes, generate the final manifest:

kubectl kustomize overlays/prod

or with standalone Kustomize:

kustomize build overlays/prod

Apply directly:

kubectl apply -k overlays/prod

Tip

Always preview generated manifests before applying production changes.

Kustomize vs Helm

Feature	Kustomize	Helm
Uses plain YAML	Yes	Uses templates
Built into kubectl	Yes	Separate CLI
Templating language	No	Yes
Best for	Environment overlays	Application packaging
Release tracking	No	Yes
Rollback support	No native release rollback	Yes

Note

Kustomize is best when you want simple YAML customization. Helm is better when you need package management, releases, upgrades, and rollbacks.

Common Kustomize Use Cases

Different replicas per environment
Different image tags per environment
Different ConfigMaps per environment
Adding environment-specific labels
Adding namespace per environment
Patching resource limits
Patching Ingress hostnames
Changing Service type
Applying production-only security settings

Production Best Practices

Recommended

Keep base/ clean and environment-neutral
Use overlays for dev, stg, and prod
Preview manifests using kubectl kustomize
Store all Kustomize files in Git
Use GitOps tools like Argo CD or Flux for production delivery
Keep production overlays minimal and explicit
Use separate namespaces for environments
Use resource requests and limits in production
Use immutable image tags instead of latest

Do's

Use base/ for shared Kubernetes manifests
Use overlays for environment-specific patches
Keep patches small and focused
Use clear folder names like dev, stg, and prod
Validate generated manifests before applying
Review production diffs before deployment
Keep secrets out of plain YAML files

Don'ts

Don't duplicate full YAML files for every environment
Don't put production-only changes in the base
Don't use latest image tags in production
Don't make overlays too complex
Don't store raw secrets in Git
Don't apply production overlays without reviewing output
Don't mix unrelated applications in one Kustomize base

Security Considerations

Danger

Never commit plaintext secrets into Kustomize manifests.

Use safer options such as:

Kubernetes Secrets managed by external secret tools
Sealed Secrets
External Secrets Operator
cloud secret managers
GitOps secret encryption workflows

Troubleshooting

Question

Kustomize output is not what you expected?

Check:

Is the overlay pointing to the correct base?
Does the patch metadata.name match the target resource?
Is the YAML indentation correct?
Are you using kubectl apply -k and not kubectl apply -f?
Did you preview with kubectl kustomize first?

Useful commands:

kubectl kustomize overlays/dev
kubectl kustomize overlays/stg
kubectl kustomize overlays/prod

kubectl apply -k overlays/dev
kubectl apply -k overlays/stg
kubectl apply -k overlays/prod

Exam / Interview Notes

Quote

Kustomize uses base + overlay
Base contains common/default manifests
Overlays contain environment-specific changes
It avoids duplicating YAML across environments
It uses plain YAML, not templates
It is built into kubectl with kubectl apply -k

Summary

Quote

Kustomize customizes Kubernetes YAML without duplicating files
Base stores shared configuration
Overlays modify base per environment
Final manifests are generated from base + overlay
Use it for clean dev/stg/prod configuration management
In production, preview output and manage changes through GitOps