Kustomize vs Helm — when to use which

Kustomize and Helm are the two main Kubernetes configuration tools. They overlap but are not interchangeable. This lesson walks the trade-offs, the hybrid approach, and the discipline.

The fundamental difference

flowchart LR
    A[Kustomize] --> B[YAML is the input]
    B --> C[Patches modify YAML]
    C --> D[Rendered YAML is valid Kubernetes]
    E[Helm] --> F[Go templates generate YAML]
    F --> G[Values configure templates]
    G --> H[Rendered YAML is valid Kubernetes]

The fundamental difference:

• Kustomize. YAML is the input; patches modify YAML declaratively. The base is valid YAML; the overlay is a transformation.
• Helm. Go templates generate YAML from values. The template is a program; values are inputs.

Kustomize is a transformation tool; Helm is a templating tool.

The trade-offs

flowchart LR
    A[Kustomize] --> A1[+ No templating; clear base]
    A --> A2[+ Built into kubectl]
    A --> A3[+ Environment overlays are declarative]
    A --> A4[- Less flexibility for complex logic]
    A --> A5["- No version history / rollback"]
    A --> A6["- No subcharts / dependencies"]
    B[Helm] --> B1[+ Powerful templating]
    B --> B2["+ Version history / rollback"]
    B --> B3[+ Subcharts and dependencies]
    B --> B4[- Requires helm CLI]
    B --> B5[- Release state in Secrets]
    B --> B6[- Steeper learning curve]

The trade-offs:

Kustomize:

• Pros: No templating; clear base; built into kubectl; environment overlays are declarative.
• Cons: Less flexibility for complex logic; no version history; no subcharts.

Helm:

• Pros: Powerful templating; version history and rollback; subcharts and dependencies.
• Cons: Requires helm CLI; release state in Secrets; steeper learning curve.

When to use each

flowchart TD
    A[Use case] --> B{Third-party package?}
    B -->|Yes| C[Helm]
    B -->|No| D{Environment overlays?}
    D -->|Yes| E[Kustomize]
    D -->|No| F[Raw YAML]
    A --> G{Complex templating?}
    G -->|Yes| C
    G -->|No, simple config| E

The choice:

• Third-party package (ingress-nginx, cert-manager, Prometheus). Use Helm. The package is templated; values are the configuration.
• Application manifest with environment overlays. Use Kustomize. The base is the application; overlays add environment-specific configuration.
• Simple manifest with no environment variation. Use raw YAML. Kustomize and Helm add complexity without benefit.
• Complex templating needs. Use Helm. Go templating can express loops, conditionals, and function calls that Kustomize cannot.

The hybrid approach

flowchart LR
    A[Production deployment] --> B["Helm: platform components"]
    A --> C["Kustomize: application manifests"]
    B --> B1[ingress-nginx]
    B --> B2[cert-manager]
    B --> B3[Argo CD]
    B --> B4[Velero]
    C --> C1["base/"]
    C --> C2["overlays/dev/"]
    C --> C3["overlays/staging/"]
    C --> C4["overlays/prod/"]

The hybrid approach: Helm for platform components, Kustomize for application manifests.

• Helm manages the platform: ingress-nginx, cert-manager, Argo CD, Velero, the monitoring stack.
• Kustomize manages the application manifests with environment overlays.

This is the most common production pattern. Each tool does what it does best.

The integration

# Argo CD Application for platform (Helm)
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: ingress-nginx
spec:
  source:
    repoURL: https://kubernetes.github.io/ingress-nginx
    chart: ingress-nginx
    targetRevision: 4.7.0
    helm:
      valueFiles:
        - values-prod.yaml

# Argo CD Application for applications (Kustomize)
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
spec:
  source:
    repoURL: https://github.com/example/manifests
    targetRevision: main
    path: overlays/prod

Argo CD supports both: the platform uses Helm sources; the applications use Kustomize sources. The same GitOps controller manages both.

Quiz

The operational discipline

Kustomize vs Helm in production rests on five non-negotiable elements:

• Helm for platform. Third-party packages with complex templating use Helm.
• Kustomize for applications. Application manifests with environment overlays use Kustomize.
• Raw YAML for simple manifests. No need for Kustomize or Helm if the manifest is simple.
• Document the choice. The runbook lists which tool is used for which manifest.
• Consistent tooling. Use one GitOps controller (Argo CD or Flux) for both.

The choice of tool is consequential. The discipline is to match the tool to the task and to use both where appropriate.