Kustomize — Trivia & Interesting Facts¶
Surprising, historical, and little-known facts about Kustomize.
Kustomize was built as the anti-Helm¶
Kustomize was created by the Kubernetes SIG-CLI team specifically because they believed Helm's template-based approach was the wrong abstraction. Their argument: YAML templates are not valid YAML, they are hard to validate, and they mix configuration logic with configuration data. Kustomize's approach — start with plain, valid YAML and patch it — keeps every manifest valid and inspectable at every stage. The philosophical tension between Helm and Kustomize remains one of the longest-running debates in the Kubernetes community.
kubectl has kustomize built in — but it is always an older version¶
Since Kubernetes 1.14 (March 2019), kubectl apply -k runs kustomize natively. However, the kustomize version bundled with kubectl lags significantly behind the standalone kustomize binary. As of 2024, kubectl shipped a kustomize version over a year old, missing features and bug fixes. This version skew has caused so many issues that the official documentation recommends installing kustomize separately.
Strategic merge patches are not standard JSON merge patches¶
Kustomize's default patching strategy is "strategic merge patch," a Kubernetes-specific extension of JSON Merge Patch (RFC 7386). The key difference: strategic merge patches understand Kubernetes list semantics. A standard JSON merge patch replaces an entire list, while a strategic merge patch can merge list items by a key field (e.g., merging container specs by container name). This is why patching a specific container in a multi-container pod works intuitively instead of replacing all containers.
The kustomization.yaml file has no Kubernetes API version — it is not a Kubernetes resource¶
Unlike every other YAML file in the Kubernetes ecosystem, kustomization.yaml does not have apiVersion and kind fields (technically it does accept them, but they are optional). It is processed entirely client-side by the kustomize binary and never sent to the Kubernetes API. This makes kustomize a pure build-time tool — the cluster never knows kustomize was involved.
Overlays were designed for the environment promotion problem¶
Kustomize's overlay system (base + dev/staging/prod overlays) was designed to solve a specific pain point: promoting configurations across environments. The base contains the canonical manifests, and each overlay applies environment-specific patches (different replica counts, resource limits, image tags). Unlike Helm values files, each overlay is itself a valid kustomization that can be inspected and validated independently.
Components allow reusable cross-cutting features¶
Kustomize Components (alpha in kustomize 3.7.0, 2020) enable reusable, composable features that can be included in any overlay. Unlike bases (which provide complete resources), components provide partial modifications — like "add Prometheus annotations" or "enable debug logging." This solved the combinatorial explosion problem where every overlay needed to duplicate cross-cutting patches.
The configMapGenerator creates unique names to force rollouts¶
Kustomize's configMapGenerator and secretGenerator append a hash suffix to resource names (e.g., my-config-abc123). When the content changes, the hash changes, the name changes, and any Deployment referencing the ConfigMap sees a new name and triggers a rollout. This elegant trick solves the "ConfigMap changed but pods did not restart" problem without requiring restart mechanisms. It is one of kustomize's most underappreciated features.
Kustomize handles image tags without modifying manifests¶
The images transformer lets you override image names and tags without writing a patch. kustomize edit set image nginx=nginx:1.21 modifies the kustomization.yaml, and all references to nginx across all manifests are replaced at build time. This is the primary mechanism for promoting image versions across environments and is significantly simpler than Helm's values-based approach for the same task.
Replacements replaced vars — and the migration was painful¶
Kustomize originally supported vars for simple string substitution (like referencing a Service name in an environment variable). Vars were deprecated in favor of replacements in kustomize 4.5.0, which is more powerful but significantly more verbose. The migration broke many existing kustomizations, and the community backlash was substantial. Vars still work but generate deprecation warnings.
Kustomize and Helm are not mutually exclusive¶
A common pattern in production is using Helm to generate base manifests (helm template) and kustomize to apply environment-specific patches on top. ArgoCD and Flux both support this hybrid approach natively. Kustomize can also render Helm charts via the helmCharts field in kustomization.yaml (requires --enable-helm flag), though this feature is considered beta and adds a Helm dependency to the build process.