Kustomize Overlay Generator

Kustomize is a template-free Kubernetes configuration management tool built into kubectl (kubectl apply -k). Instead of templating, it uses a patching and overlay system — you start with plain Kubernetes YAML files (base) and layer environment-specific customizations (overlays) on top using patches, image replacements, and generators. Helm uses a Go templating engine with values files to parameterize charts. Key differences: Kustomize works with plain YAML and needs no installation (it's in kubectl); Helm manages releases with lifecycle hooks and rollbacks. Many teams use both — Helm for third-party charts, Kustomize for their own app manifests.

A base is a directory containing your core Kubernetes manifests and a kustomization.yaml that references them. It's environment-agnostic — shared configuration valid for all environments. An overlay is a directory with its own kustomization.yaml that references the base (using resources: - ../../base) and adds environment-specific customizations: different replica counts, image tags, namespaces, resource limits, config values, and ingress rules. You never directly edit base files per environment — instead, overlays apply patches on top. The result: kubectl apply -k overlays/prod/ deploys the base + all prod patches.

Kustomize's images field in kustomization.yaml replaces Docker image references without modifying your base Deployment YAML. You specify the original image name (as used in the base) and Kustomize rewrites it to newName and/or newTag at render time. Example: if your base deployment uses image: nginx, your prod overlay can override to image: my-registry.com/nginx:v1.2.3 by setting name: nginx, newName: my-registry.com/nginx, newTag: v1.2.3. This is far safer than editing YAML strings — Kustomize only replaces exact image name matches, preventing partial string bugs. CI/CD pipelines often use kustomize edit set image to update tags automatically.

configMapGenerator in kustomization.yaml generates ConfigMap resources from literals or files, and — crucially — automatically appends a content hash to the ConfigMap name (e.g., app-config-7t2d48k). When ConfigMap content changes, the hash changes, which triggers a rolling update in Deployments that reference it. This solves a common Kubernetes problem: ConfigMap changes don't automatically restart pods. With plain ConfigMaps, you must manually trigger restarts. Use configMapGenerator for application configuration that should trigger pod restarts on change. Use disableNameSuffixHash: true if you manage restarts yourself or reference ConfigMaps by exact name.

A strategic merge patch is a partial Kubernetes YAML fragment that gets merged into the base resource using Kubernetes merge logic. You only specify the fields you want to change — Kustomize merges it intelligently (e.g., lists are merged by name key, not replaced). Example: a patch with spec.replicas: 3 sets replicas without affecting any other fields. Strategic merge patches are readable and work well for most cases. JSON patches (RFC 6902) are lower-level operations: add, remove, replace, copy, move. Use JSON patches when you need to remove a field, operate on list items by index, or when strategic merge doesn't behave as expected (e.g., for resources without merge keys). Strategic merge is preferred for its readability.

The standard pattern is a base/ directory plus an overlays/ directory with one subdirectory per environment: overlays/dev/, overlays/staging/, overlays/prod/. Each overlay references ../../base and only overrides what differs. For multi-team setups, teams can have their own base that references a shared company-wide base (multi-layer composition). Store the entire k8s/ directory in Git alongside your application code. In CI/CD, run kubectl apply -k overlays/$ENVIRONMENT/ or kustomize build | kubectl apply -f - per environment. For secrets, never put them in kustomization.yaml — use External Secrets Operator, Sealed Secrets, or Vault Agent Injector to manage secrets separately.