Skip to main content

Documentation Index

Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt

Use this file to discover all available pages before exploring further.

In this guide, you’ll learn how to maintain a shared base configuration and apply environment-specific changes using Overlays in Kustomize. Overlays let you centralize common resources in a base/ directory and then customize or extend them for dev, stg, prod, or any other environment.
The image is a diagram labeled "Overlays" showing a hierarchy with "Env" at the top, branching into "dev," "stg," and "prod" environments.
Below is a typical Kustomize directory 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
DirectoryContentsPurpose
base/nginx-depl.yaml, service.yaml, redis-depl.yamlShared deployments and services
overlays/devconfig-map.yaml + kustomization fileDev-specific patches (e.g., replica count)
overlays/stgconfig-map.yaml + kustomization fileStaging tweaks
overlays/prodconfig-map.yaml + kustomization fileProduction patches and extra resources

​
1. Base kustomization

The base holds all common Kubernetes manifests. 
# base/kustomization.yaml
resources:
  - nginx-depl.yaml
  - service.yaml
  - redis-depl.yaml
Example of a base Deployment: 
# base/nginx-depl.yaml
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:latest
Make sure each file listed under resources: has a valid manifest. You can validate your YAML with kubectl apply --dry-run=client -f.

​
2. Dev Overlay

The Dev overlay references the base and patches the replica count using JSON 6902. 
# overlays/dev/kustomization.yaml
resources:
  - ../../base

patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: nginx-deployment
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 2

# Generate dev manifests
kustomize build overlays/dev
FieldDescription
resources:Relative path to the shared base directory
patchesJson6902JSON 6902 patch to modify /spec/replicas to 2

​
3. Production Overlay

For production, you can both patch existing resources and add new ones (e.g., a Grafana deployment). 
k8s/
└── overlays/
    └── prod/
        ├── kustomization.yaml
        ├── config-map.yaml
        └── grafana-depl.yaml

# overlays/prod/kustomization.yaml
resources:
  - ../../base
  - grafana-depl.yaml

patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: nginx-deployment
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 3

# overlays/prod/grafana-depl.yaml
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
Ensure new resources like grafana-depl.yaml are listed under resources: in the overlay’s kustomization.yaml. Otherwise, they won’t be rendered.

​
4. Flexible Directory Structures

Kustomize supports organizing both base and overlays in nested feature folders. For example: 
k8s/
├── base/
│   ├── kustomization.yaml
│   ├── db/
│   │   ├── db-depl.yaml
│   │   ├── db-svc.yaml
│   │   └── kustomization.yaml
│   └── api/
│       ├── api-depl.yaml
│       ├── api-svc.yaml
│       └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   ├── db/
    │   │   ├── db-patch.yaml
    │   │   └── kustomization.yaml
    │   └── api/
    │       ├── api-patch.yaml
    │       └── kustomization.yaml
    └── prod/
        ├── kustomization.yaml
        └── api/
            ├── api-patch.yaml
            └── kustomization.yaml
  • Feature-based grouping: Split base/ into db/ and api/ with individual kustomization.yaml.
  • Overlay mirroring: Maintain a similar hierarchy under each overlay for targeted patches.
  • Cross-references: Each overlay’s kustomization file imports the correct child resources and patches.

​
References

Watch Video

Practice Lab