Overlays

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.

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

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

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

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

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

• Kustomize Official Documentation
• JSON 6902 Patch
• Kubernetes Concepts