Helm vs Kustomize for Kubernetes applications

Deploy the same representative API with Universal Helm Chart values and with Kustomize overlays—then decide where each tool owns the contract, without crowning a false winner.

Same app, two configuration models

Target workload: one HTTP API (demo-api) with probes, resources, env, Service on port 8080, and an HTTPRoute attached to a platform Gateway. Dev and prod differ by replicas, resources, APP_ENV, and hostname.

Helm path: one chart release + values files. Kustomize path: base manifests + overlays that patch the same fields. Neither path creates the Gateway—that stays platform-owned.

Helm values (dev excerpt)

image: ghcr.io/example-org/demo-api
imageTag: "1.2.0"
imagePullPolicy: IfNotPresent
replicaCount: 1
serviceAccount:
  create: true
  automount: false
service:
  port: 8080
env:
  - name: APP_ENV
    value: dev
route:
  enabled: true
  gateway: external
  gatewayNamespace: kgateway-system
  sectionName: https
  hostname: demo-api-dev.example.com
  path: /
  pathMatchType: PathPrefix

route.gatewayNamespace must match the platform Gateway namespace. This series uses lab/platform kgateway-system (aligned with the kgateway articles). Replace if your platform uses another NS—do not invent a chart default.

Hardening: set chart key serviceAccount.automount: false when the workload does not call the Kubernetes API (default chart value is true). Kustomize base mirrors automountServiceAccountToken: false on the ServiceAccount.

Full files: examples/helm-vs-kustomize/helm/values-dev.yaml and values-prod.yaml (replicaCount: 3, larger resources, demo-api.example.com).

Kustomize overlay (dev)

Base ships Deployment, Service, ServiceAccount, and HTTPRoute. The dev overlay patches env and hostname; prod also patches resources and sets replicas: 3.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
replicas:
  - name: demo-api
    count: 1
patches:
  - target:
      kind: HTTPRoute
      name: demo-api
    patch: |-
      - op: replace
        path: /spec/hostnames/0
        value: demo-api-dev.example.com

Render and compare

helm repo add universal https://chaser100.github.io/u-helm-chart
helm repo update
helm template demo-api-dev universal/application --version 0.4.3 \
  -f examples/helm-vs-kustomize/helm/values-dev.yaml | rg '^kind:'
kustomize build examples/helm-vs-kustomize/kustomize/overlays/dev | rg '^kind:'

Measured: both paths emit the same kind set—Deployment, Service, ServiceAccount, HTTPRoute. Hostnames and replica counts match the encoded env intent. Line counts differ (Helm templates carry chart labels/helpers; Kustomize base is minimal YAML)—that is structure, not a speed claim.

Packaging and distribution

• Helm — versioned chart package (.tgz), Helm repo / OCI, Artifact Hub. Consumers pin --version 0.4.3. Official: Helm Charts.
• Kustomize — Git directories (base + overlays). Distribution is the repo (or a published kustomization root), not a chart tarball. Official: Kustomize.

Recommendation: when many services share Deployment/Service/HTTPRoute shape, package once (Helm chart) and vary values. When you already own final YAML and need env deltas, overlays stay lighter.

Values vs overlays

• Values map intent to chart templates. Universal Helm Chart exposes image/imageTag, replicaCount, service.port, env, probes, resources, route.* / ingress.*.
• Overlays patch concrete fields on rendered objects (replicas, JSON6902 patches, strategic merge). You maintain the base YAML yourself (or generate it).

Complement: offline or CI helm template → commit into a Kustomize base when platform policy must patch labels/sidecars after packaging. Argo CD composition (accurate): a single Application source is either Helm (chart) or Kustomize (path)—Argo CD does not natively chain Helm render then Kustomize as a built-in post-render step on one source. Combine via (a) multi-source Applications (chart + Git values), (b) a Config Management Plugin that you own, or (c) render Helm offline and sync the resulting Kustomize directory. Validate your Argo CD version docs before relying on multi-source or CMP.

Schema validation

Measured: application 0.4.3 ships values.schema.json; helm lint -f values-*.yaml passes on the evidence pack. Schema uses JSON Schema with additionalProperties: true—unknown keys are not rejected by default; still prefer documented keys only.

Kustomize validates kustomization structure at build time; it does not provide an application-level values schema equivalent to Helm’s chart schema. Policy engines (Kyverno, OPA Gatekeeper) apply after render for both paths.

Official: Helm schema files.

Dependencies

• Helm — optional Chart.yaml dependencies / subcharts (chart dependencies). Measured for this chart: Universal Helm Chart application 0.4.3 is a leaf chart (type: application, no dependencies entry)—it does not pull Redis/Postgres as subcharts. Wire data stores as separate releases.
• Kustomize — compose with resources, components, and remote bases. No Helm-style dependency resolver; version pins are Git refs / tags you choose.

Diff and debug ergonomics

# Helm: render + diff values layers
helm template demo-api universal/application --version 0.4.3 -f values-dev.yaml > /tmp/dev.yaml
helm template demo-api universal/application --version 0.4.3 -f values-prod.yaml > /tmp/prod.yaml
diff -u /tmp/dev.yaml /tmp/prod.yaml | head

# Kustomize: overlay diff
diff -u \
  <(kustomize build examples/helm-vs-kustomize/kustomize/overlays/dev) \
  <(kustomize build examples/helm-vs-kustomize/kustomize/overlays/prod) | head

# Cluster-facing (either path)
kubectl diff -f <(helm template ...)   # or kustomize build
helm get values <release>              # Helm release state only

Helm keeps release history / values on the cluster when installed via Helm. Pure Kustomize/GitOps often has no release secret—source of truth is Git. Neither fact implies fewer outages; it changes where you look when debugging.

Argo CD behavior

Argo CD syncs one source type per source entry: Helm charts (source.chart + helm.valueFiles / valuesObject) or Kustomize directories (source.path). That is composition of Application sources—not a native Helm→Kustomize post-render pipeline inside one source. Illustrative Applications (marked DO NOT APPLY AS-IS): examples/helm-vs-kustomize/argocd/applications.illustrative.yaml.

• Helm source: Argo CD renders with its bundled Helm; set repoURL to the Helm repo (https://chaser100.github.io/u-helm-chart), not the chart’s Git remote, when using chart:; pin targetRevision to 0.4.3.
• Kustomize source: Argo CD builds the overlay path; repoURL is a public or private Git remote you control (illustrative pack uses https://github.com/example-org/gitops-bridge.git—replace it); pin Git targetRevision.
• Combining tools: use multi-source Applications, an owned CMP, or offline helm template into a Kustomize tree—do not assume Argo CD auto-runs Kustomize after Helm for a single source.
• Drift: both use Git desired state + sync/selfHeal. Helm CLI releases outside Argo CD can fight GitOps—pick one controller for a given app.

Official: Argo CD Helm, Argo CD Kustomize.

Not measured here: live Argo CD sync timings on a cluster. Render parity is verified offline; treat Application YAML as pattern documentation until your GitOps repo adopts it.

Shared Gateway, per-app HTTPRoute, kgateway policies

Scoped comparison for templating vs overlays (not a full Gateway migration guide):

• Shared Gateway (platform): one Gateway in kgateway-system (illustrative: examples/helm-vs-kustomize/kgateway/shared-gateway.illustrative.yaml). Neither Helm values nor app overlays should create it in production.
• Per-app HTTPRoute: Helm encodes attachment via portable route.* (gateway, gatewayNamespace, hostname, …). Kustomize keeps the HTTPRoute in base and patches hostnames/env per overlay—same ownership split, different config model.
• kgateway-specific policy: CORS/rate-limit style controls use TrafficPolicy (CRD), not chart route.*. Helm ships it through extraManifests (snippet: kgateway/values-extraManifests.snippet.yaml). Kustomize adds the same YAML as an overlay resources entry. Label networking.contract/kind: kgateway-specific and review against kgateway docs.

Measured limitation: Universal Helm Chart application 0.4.3 has no first-class route.cors / TrafficPolicy keys—escape hatch only. See also kgateway migration patterns and examples/gateway-api-helm-contract/.

Ownership boundaries

• Platform — Gateway/GatewayClass, cluster policies, shared chart version bumps, Argo CD AppProjects.
• App team (Helm) — values files (image tag, route hostname, resources); rarely templates.
• App team (Kustomize) — base YAML + overlays; they own structural patches when the base lacks a values knob.

With Universal Helm Chart, app teams stay on values; escape hatches (extraManifests, extraDeployments) exist when the model is insufficient—see Why one Helm chart is enough.

Upgrades, drift, and long-term maintenance

• Chart upgrade: publishing chart 0.4.4 does not move pinned consumers automatically. Every Application / CI job that pins targetRevision: 0.4.3 or --version 0.4.3 must bump its own pin. Shared packaging reduces template drift; it does not collapse N pins into one silent upgrade.
• Overlay upgrade: rebase base manifests (or regenerate from helm template) when APIs or label conventions change—N bases if teams forked YAML; each overlay consumer still reviews its own patches.
• Drift: GitOps selfHeal converges both. Manual kubectl edit is equally wrong in either model.

Recommendation: prefer a shared chart package for fleet-wide defaults, but treat every pinned consumer bump as an explicit change; keep Kustomize for environment-specific last-mile patches or non-chart workloads.

Failure modes

• route.enabled: true without route.gateway — template required() fails at helm template/install (route.gateway is required when route.enabled=true); JSON Schema alone does not reject the empty default. Example fixture: examples/helm-vs-kustomize/negative/helm-missing-gateway.yaml.
• HTTPRoute rendered but Gateway missing / not Programmed — traffic fails; not a Helm-vs-Kustomize difference.
• Kustomize JSON6902 path that does not exist — kustomize build fails. Example fixture: examples/helm-vs-kustomize/negative/kustomize-bad-patch/.
• Kustomize nameSuffix on HTTPRoute without updating backendRefs — Service name drift (avoided in this pack by stable names).
• Unknown values keys — accepted when additionalProperties: true; silent no-ops if no template consumes them.
• Argo CD Helm version skew vs local Helm — pin chart version; compare helm template to Argo CD hard refresh manifests.
• Leaving serviceAccount.automount: true on workloads that never call the API — unnecessary token exposure; this pack sets false.

Decision table

Where they complement each other

Universal Helm Chart is the reusable packaging contract. Kustomize is the YAML patch toolkit. Teams that already standardize on the chart should not rewrite templates as overlays just to “use Kustomize.” Teams with mature overlay libraries should not invent a private chart if a shared chart already encodes the same objects—unless they need escape hatches the values model cannot express.

Recommendation: Helm for the application contract; Kustomize for platform-wide mutations and exceptions; Argo CD to reconcile Helm or Kustomize sources (compose deliberately—do not assume native Helm→Kustomize chaining).

Editorial checklist

• Stage: published (Platform + SEO dual PASS @ 6f3f53e; noindex removed)
• Evidence pack + verify script PASS
• No invented chart flags; Official Helm / Kustomize / Argo CD / Gateway API links present
• Internal links: Why one Helm chart is enough, Gateway API examples, Examples, Getting started

Related: Why one Helm chart is enough → · Gateway API vs Ingress → · Getting started →

Related in this series

Why one Helm chart is enough → · One chart vs many → · GitOps repository structure → · Gateway API vs Ingress →