ADR-004: Use Helm for Third-Party Charts, Kustomize for Custom Overlays¶
Status¶
Accepted
Date¶
2026-03-07
Context¶
Kubernetes manifests need a templating and packaging strategy. Two dominant tools exist in the CNCF ecosystem: Helm (package manager with templating) and Kustomize (overlay-based, no templating). FluxCD natively supports both.
Decision¶
Use both tools for their respective strengths:
| Layer | Tool | Rationale |
|---|---|---|
| Third-party software (cert-manager, ingress-nginx, Prometheus) | Helm via HelmRelease |
Upstream charts are maintained by their communities; values override is simpler than forking |
| Custom app overlays and cluster-specific config | Kustomize via Kustomization |
No templating needed for simple patches; built into kubectl; GitOps-native |
| Kustomization ordering/dependency | Flux Kustomization CRD | dependsOn field provides explicit deployment ordering |
Alternatives Considered¶
| Tool | Reason Not Chosen as Sole Solution |
|---|---|
| Helm only | Custom resources (namespaces, ClusterIssuer) feel unnatural as Helm charts; lifecycle management is more complex |
| Kustomize only | Upstream charts would need to be vendored and manually updated; significant maintenance burden |
| Jsonnet / CUE | Powerful but steep learning curve; not standard in most production environments |
Consequences¶
Positive¶
- Community-maintained Helm charts receive security patches automatically via
version: "1.x"ranges - Kustomize patches keep environment-specific overrides small and auditable
- Flux manages both natively — no additional tooling needed
- Learning both tools covers the majority of real-world K8s workflows
Negative¶
- Two mental models to maintain (Helm values vs Kustomize patches)
- Helm chart upgrades can contain breaking value changes — requires reading changelogs
Trade-offs¶
Pragmatic tool selection per use case is prioritised over uniformity. The slight cognitive overhead of two tools is offset by reduced maintenance burden.