Opscraft
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 diagrambaseDeployment, Serviceoverlays/stagingreplicas 2overlays/prodreplicas 6, bigger limits, HPAkustomize build overlays/prod → base + prod patches
Figure 1. Kustomize base and overlays: the base is the shared, valid YAML; each environment overlay changes only what differs.
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 diagramedit app.propertiesnew nameorders-config-7k2m9Deploymentupdatedreference rewrittenpods rollwith the new config
Figure 2. configMapGenerator adds a content hash to the name, so changing config changes the pod template and triggers a rollout.
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 diagramGitRepositoryplatform-gitopsKustomizationapps/orders/overlays/prodclusterapplied, pruned,health-checkedinterval: 5m · prune: true · wait / healthChecks
Figure 3. A typical GitOps layout: Flux watches the repo and applies an overlay per cluster, pruning what was removed from Git.
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