# Kustomize base and overlays

> One base with the manifests, one overlay per environment that changes only the image tag, replicas and config.

- Canonical: https://js-on-k8s.dev/recipes/manifests/kustomize
- Site: JavaScript on Kubernetes (https://js-on-k8s.dev)
- Updated: 2026-09-10
- Part of: https://js-on-k8s.dev/recipes/manifests
- Tags: kustomize, manifests, environments
- Example: https://github.com/vojtechmares/js-on-k8s/tree/main/examples/full/k8s
- Full example: https://github.com/vojtechmares/js-on-k8s/tree/main/examples/full

Kustomize needs no templating. The base holds the real manifests; overlays patch what
differs between environments.

## Layout

```
k8s/
  base/
    kustomization.yaml
    deployment.yaml
    service.yaml
    pdb.yaml
  overlays/
    staging/
      kustomization.yaml
    production/
      kustomization.yaml
```

## Base

```yaml
# k8s/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - pdb.yaml
configMapGenerator:
  - name: app
    literals:
      - LOG_LEVEL=info
```

## Overlay

```yaml
# k8s/overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: app-production
resources:
  - ../../base
images:
  - name: ghcr.io/you/app
    newTag: 1.0.0
replicas:
  - name: app
    count: 3
configMapGenerator:
  - name: app
    behavior: merge
    literals:
      - LOG_LEVEL=warn
```

## Apply

```sh
kubectl apply -k k8s/overlays/production
# or from CI
cd k8s/overlays/production && kustomize edit set image ghcr.io/you/app=ghcr.io/you/app:${GIT_SHA}
```

## Notes

- `configMapGenerator` appends a hash to the ConfigMap name and updates references,
  so a config change rolls the Deployment.
- Keep patches small. If an overlay rewrites most of the base, the base is wrong.
- Kustomize is built into `kubectl`, and Argo CD and Flux render it natively.