Overlays

After authoring kustomization.yaml files and exploring Kustomize features, the next step is to assemble everything and apply environment-specific changes. Kustomize exists to let you take a shared “base” Kubernetes configuration and customize it per environment (development, staging, production, etc.) without duplicating manifests. A typical Kustomize project separates reusable manifests (the base) from environment-specific overlays (patches and extras). This approach improves maintainability, reduces duplication, and makes deployments predictable. Example project layout

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

Reference the base kustomization from an overlay using a relative path. Older Kustomize versions used the bases field; the recommended practice is to reference the base via resources: - ../../base so Kustomize includes the base kustomization.

How base + overlays work

Base: contains shared manifests used by multiple environments (deployments, services, config maps common to all).
Overlay: references the base using a relative path and applies environment-specific patches or adds resources unique to that environment.

Base: shared resources base/kustomization.yaml

resources:
  - nginx-depl.yaml
  - service.yaml
  - redis-depl.yaml

base/nginx-depl.yaml (snippet)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:stable
          ports:
            - containerPort: 80

Example: change replicas per environment If the base declares 1 replica but your development environment needs 2, add an overlay that references the base and applies a strategic merge patch. overlays/dev/kustomization.yaml

resources:
  - ../../base

patchesStrategicMerge:
  - replica-patch.yaml

overlays/dev/replica-patch.yaml

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

Notes on relative paths:

Overlay file: k8s/overlays/dev/kustomization.yaml
../../base resolves by moving from dev → overlays → k8s and into base, importing the base kustomization.

Production overlay example For production, you might apply a different patch: overlays/prod/kustomization.yaml

resources:
  - ../../base

patchesStrategicMerge:
  - replica-patch.yaml

overlays/prod/replica-patch.yaml

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

Add new resources in overlays Overlays can also include entirely new resources not present in the base (e.g., monitoring or logging components). Example layout with Grafana in prod:

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

overlays/prod/kustomization.yaml

resources:
  - ../../base
  - grafana-depl.yaml

patchesStrategicMerge:
  - replica-patch.yaml

overlays/prod/grafana-depl.yaml (snippet)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: grafana
spec:
  replicas: 1
  selector:
    matchLabels:
      app: grafana
  template:
    metadata:
      labels:
        app: grafana
    spec:
      containers:
        - name: grafana
          image: grafana/grafana:latest
          ports:
            - containerPort: 3000

Flexible directory structures Kustomize is flexible — you can break the base into feature subdirectories (for example, db/ and api/) and mirror or reorganize overlays however makes sense for your team. Each kustomization.yaml should import required resources (including sub-kustomizations) and keep environment patches close to the overlay they modify. Example of a more modular layout:

k8s/
├── base/
│   ├── kustomization.yaml
│   ├── db/
│   │   ├── db-depl.yaml
│   │   ├── db-service.yaml
│   │   └── kustomization.yaml
│   └── api/
│       ├── api-depl.yaml
│       ├── api-service.yaml
│       └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   ├── db/
    │   │   ├── db-patch.yaml
    │   │   └── kustomization.yaml
    │   └── api/
    │       ├── api-patch.yaml
    │       └── kustomization.yaml
    └── prod/
        ├── kustomization.yaml
        ├── db/
        │   ├── db-patch.yaml
        │   └── kustomization.yaml
        └── api/
            ├── api-patch.yaml
            └── kustomization.yaml

Quick commands: build and apply an overlay

Build the manifests for an overlay:
- kustomize build overlays/dev or kubectl kustomize overlays/dev
Apply directly with kubectl:
- kubectl apply -k overlays/dev

Comparison: base vs overlay

Concept	Purpose	Example
Base	Shared manifests for all environments	`base/nginx-depl.yaml` with `replicas: 1`
Overlay	Environment-specific patches or extra resources	`overlays/prod/grafana-depl.yaml` or `patchesStrategicMerge` to change replicas
Patch types	Ways to change resources in overlays	`patchesStrategicMerge` (simple field overrides) or `patchesJson6902` (JSON Patch)

Best practices

Keep the base minimal and generic — only the common configuration used across environments.
Place environment-specific settings in overlays, close to the overlay’s kustomization.yaml.
Prefer patchesStrategicMerge for simple field overrides like replicas or container images. Use patchesJson6902 for precise JSON Patch-style changes when needed.
Use relative paths for referencing the base (resources: - ../../base) to keep overlays portable.
Add new resources in overlays when a component should exist only in specific environments (monitoring, debug tools, etc.).

Summary

Use a base/ directory for shared configuration.
Create an overlays/ directory with one overlay per environment that references the base via a relative path.
Apply environment-specific changes using patches (e.g., patchesStrategicMerge).
Overlays can also add new resources that don’t exist in the base.
Organize directories in the structure that best fits your project—Kustomize is flexible.

If you need JSON Patch-style modifications, you can use patchesJson6902 instead of patchesStrategicMerge. Strategic merge patches are often simpler for changing fields like replicas.

Links and references

Kustomize official: https://kustomize.io/
Kubernetes: https://kubernetes.io/
kubectl kustomize: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

Watch Video

Practice Lab