Helm & Kustomize · Lesson 5 of 7 · 5 min read
Kustomize in depth
Base and overlays
apps/orders/
base/
kustomization.yaml
deployment.yaml
service.yaml
overlays/
staging/
kustomization.yaml
replicas-patch.yaml
prod/
kustomization.yaml
resources-patch.yaml
hpa.yaml
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.
# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
labels:
- pairs: { app.kubernetes.io/name: orders }
includeSelectors: false
# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: orders
resources:
- ../../base
- hpa.yaml
images:
- name: orders
newName: 123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders
newTag: "a1b2c3d"
replicas:
- name: orders
count: 4
patches:
- path: resources-patch.yaml
- target: { kind: Deployment, name: orders }
patch: |-
- op: add
path: /spec/template/spec/containers/0/env/-
value: { name: SPRING_PROFILES_ACTIVE, value: prod }
configMapGenerator:
- name: orders-config
envs: [config.env]
kubectl kustomize overlays/prod # render (or: kustomize build overlays/prod)
kubectl apply -k overlays/prod
kustomize edit set image orders=*:a1b2c3d # what CI does to bump a tag
kubectl diff -k overlays/prod
Transformers and generators
| Feature | Use |
|---|---|
namespace, namePrefix, nameSuffix |
Applied to all resources (references are updated too) |
labels / commonLabels (deprecated) / commonAnnotations |
Add metadata; commonLabels also changes selectors — risky on existing Deployments |
images |
Change image name/tag/digest without patches |
replicas |
Set replica counts |
patches |
Strategic merge patches (partial YAML) or JSON 6902 patches (op/path/value), with target selectors for many resources |
configMapGenerator / secretGenerator |
Generate ConfigMaps/Secrets from files/literals with a content-hash suffix; references are rewritten, so a config change rolls the Deployment |
components |
Reusable optional bundles (e.g. "enable-monitoring") mixed into several overlays |
replacements |
Copy a field value from one resource into others (replaces old vars) |
helmCharts |
Inflate a Helm chart (needs --enable-helm) |
Strategic merge vs JSON patch: strategic merge understands Kubernetes list merge keys (containers by name), so you can patch one container by name; JSON 6902 works by index/path and is precise for adds/removes.
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.
Kustomize with Flux (a typical setup)
A Flux Kustomization points at a path in a GitRepository source and applies the rendered output, with pruning and health checks:
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata: { name: orders-prod, namespace: flux-system }
spec:
interval: 5m
path: ./apps/orders/overlays/prod
prune: true
sourceRef: { kind: GitRepository, name: platform-gitops }
targetNamespace: orders
dependsOn: [{ name: infra-controllers }]
healthChecks:
- { apiVersion: apps/v1, kind: Deployment, name: orders, namespace: orders }
decryption: { provider: sops, secretRef: { name: sops-age } }
postBuild:
substituteFrom: [{ kind: ConfigMap, name: cluster-vars }]
Don't confuse the Flux Kustomization CRD (kustomize.toolkit.fluxcd.io) with the kustomization.yaml file (kustomize.config.k8s.io). Flux runs kustomize build on the path even if no kustomization.yaml exists (it generates one).
For Helm, Flux uses HelmRepository/OCIRepository sources and a HelmRelease:
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata: { name: cert-manager, namespace: cert-manager }
spec:
interval: 30m
chart:
spec:
chart: cert-manager
version: "1.19.x" # pinned minor; patch updates allowed
sourceRef: { kind: HelmRepository, name: jetstack, namespace: flux-system }
install: { remediation: { retries: 3 } }
upgrade: { remediation: { retries: 3, remediateLastFailure: true } }
values:
crds: { enabled: true }
replicaCount: 2
valuesFrom:
- kind: ConfigMap
name: cert-manager-values-prod
postRenderers:
- kustomize:
patches:
- target: { kind: Deployment, name: cert-manager }
patch: |
- op: add
path: /spec/template/metadata/annotations/team
value: platform