Helm vs Kustomize: Choose the Right Kubernetes Config

Your Kubernetes repository starts with one Deployment and one Service. Six months later, the Helm vs Kustomize decision has left you with staging and production copies, a hand-edited image tag, a different replica count, and three patches that only one person understands. The next release changes a label in one environment but not the others. The cluster accepts every manifest, so the failure appears only during rollout.

This article compares Helm vs Kustomize by building the same small application with both tools, rendering the result, and choosing a configuration model based on ownership, reuse, release behavior, and security review.

The complete Helm and Kustomize example includes the chart, base manifests, production overlay, and a non-destructive validation target.

Why Helm vs Kustomize is a deployment decision

The wrong choice usually starts with a false equivalence: both tools accept YAML-related input and produce Kubernetes manifests, so a team picks the tool it has seen most recently. The operational model is different.

Helm treats configuration as a chart package. Templates, default values, dependencies, and chart metadata form a release artifact. The Helm chart documentation defines the chart directory structure, while the template guide documents Go templates and values.

Kustomize treats configuration as resources plus transformations. A base contains Kubernetes YAML, and an overlay applies patches or cross-cutting changes without changing the base. Kubernetes documents kubectl kustomize, kubectl apply -k, and the base-and-overlay model in its Kustomize task guide.

The practical question is not which tool is more capable. It is where you want complexity to live: in a reusable package interface, or in a Git-visible set of environment differences.

What Helm and Kustomize actually change

Before comparing syntax, separate the input from the output. Both tools should be judged by the rendered manifests that reach the Kubernetes API server, not by how clean the source directory looks.

Helm evaluates templates against chart values and release context. A value such as .Values.image.tag can change the rendered container image, and a chart dependency can add resources to the same release. The chart can also define a values.schema.json file that validates the final values object during helm lint, helm template, helm install, or helm upgrade.

Kustomize does not use a general-purpose template language. It reads resources, applies transformations, and emits YAML. Its images field can replace an image tag without a patch, while patches can target specific resources. configMapGenerator and secretGenerator create objects and append a content hash by default, which lets workloads refer to a new name when configuration changes.

That distinction matters for security review. Helm gives you a powerful programming surface, but template branches can make the final object difficult to reason about. Kustomize gives you a narrower transformation model, but a long chain of overlays can make the final state equally hard to trace.

Build the same app with Kustomize

Start with a base that describes the application without environment-specific values. This base has one Deployment and one Service, and it uses an immutable image tag instead of latest.

Create the following files under kustomize/base:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app.kubernetes.io/name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: web
  template:
    metadata:
      labels:
        app.kubernetes.io/name: web
    spec:
      containers:
        - name: web
          image: ghcr.io/example/web:1.4.2
          ports:
            - name: http
              containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: http

The Service is a separate resource because the base should remain readable and independently testable:

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app.kubernetes.io/name: web
  ports:
    - name: http
      port: 80
      targetPort: http

Declare both resources in kustomize/base/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
 
resources:
  - deployment.yaml
  - service.yaml

Now create a production overlay. It changes only the values that are different from the base: the namespace, replica count, image tag, and a release label.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
 
namespace: production
namePrefix: prod-
 
resources:
  - ../../base
 
labels:
  - pairs:
      app.kubernetes.io/part-of: storefront
    includeSelectors: false
 
images:
  - name: ghcr.io/example/web
    newTag: 1.4.3
 
patches:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: web
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 4

Render the overlay without contacting a cluster:

kubectl kustomize kustomize/overlays/production > /tmp/web-production.yaml
kubectl apply --dry-run=client -f /tmp/web-production.yaml

The rendered Deployment should be named prod-web, live in the production namespace, use image ghcr.io/example/web:1.4.3, and have four replicas. The base remains unchanged, so a development overlay can reuse it without copying the application resources.

Kustomize's base and overlay model is strongest when environment differences are small, explicit, and owned by the same team that owns the base manifests.

Build the same app with Helm

The Helm version uses the same application intent, but its reusable interface is a chart and a values file. Create a chart under helm/web.

Start with helm/web/Chart.yaml:

apiVersion: v2
name: web
version: 0.1.0
appVersion: "1.4.2"
type: application

Put the environment-neutral defaults in helm/web/values.yaml:

replicaCount: 2
 
image:
  repository: ghcr.io/example/web
  tag: 1.4.2
 
service:
  port: 80
  targetPort: http

The Deployment template turns those values into a Kubernetes object. Helm's template language also exposes release metadata, which lets the chart derive names and labels consistently.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "web.fullname" . }}
  labels:
    app.kubernetes.io/name: {{ include "web.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app.kubernetes.io/name: {{ include "web.name" . }}
      app.kubernetes.io/instance: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: {{ include "web.name" . }}
        app.kubernetes.io/instance: {{ .Release.Name }}
    spec:
      containers:
        - name: web
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - name: http
              containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: http

The helper definitions keep naming logic out of each resource template:

{{- define "web.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
{{- end -}}
 
{{- define "web.fullname" -}}
{{- if .Values.fullnameOverride -}}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- printf "%s-%s" .Release.Name (include "web.name" .) | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- end -}}

Create the Service template with the same interface:

apiVersion: v1
kind: Service
metadata:
  name: {{ include "web.fullname" . }}
  labels:
    app.kubernetes.io/name: {{ include "web.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  selector:
    app.kubernetes.io/name: {{ include "web.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}
  ports:
    - name: http
      port: {{ .Values.service.port }}
      targetPort: {{ .Values.service.targetPort }}

Render the production values without contacting a cluster:

replicaCount: 4
 
image:
  tag: 1.4.3

helm lint helm/web
helm template prod helm/web --namespace production --values helm/web/values-production.yaml > /tmp/web-production-helm.yaml
kubectl apply --dry-run=client -f /tmp/web-production-helm.yaml

helm lint should report no chart errors. The rendered Deployment should have four replicas and image tag 1.4.3, matching the Kustomize output. The difference is where the contract lives: Kustomize expresses production as an overlay patch, while Helm exposes production as values passed to a chart.

The Helm upgrade command also gives Helm a release-oriented workflow. Values can come from multiple files, with the rightmost file taking precedence, and Helm can record release revisions for upgrade and rollback operations.

How to choose between Helm and Kustomize

Choose based on the ownership and distribution problem you need to solve. Use this decision sequence rather than comparing feature checklists.

1. Choose Kustomize when one team owns the base manifests and environment differences are small. A base plus dev, staging, and production overlays keeps changes close to ordinary Kubernetes YAML.
2. Choose Helm when another team will consume your configuration as a package. Chart metadata, versioning, dependencies, values, and release commands create a distribution boundary that overlays do not provide.
3. Choose Helm when the application has many optional components or repeated resource patterns. Templates and values can reduce duplication, but require disciplined chart tests and rendered-manifest review.
4. Choose Kustomize when your security or platform review requires the final resource shape to stay close to the source files. It avoids a general-purpose template language and integrates directly with kubectl.
5. Choose both only when the boundary is explicit. For example, a platform team can publish a Helm chart while an application team maintains a small Kustomize overlay. Define who owns the rendered output, which tool runs first, and where the final manifest is scanned.

For most teams starting a new application repository, Kustomize is the safer default. Start with readable base manifests and overlays. Move to Helm when reuse across teams, chart distribution, dependencies, or release history becomes a real requirement rather than a hypothetical one.

If the application also uses Secrets or ConfigMaps, keep those inputs out of plain Git values and manifests. The distinction between configuration and sensitive data is covered in Kubernetes ConfigMap vs Secret Explained.

How to secure either workflow

The rendering tool does not enforce a secure Kubernetes design. Add the same security controls around both paths.

1. Pin image references to a digest or an approved immutable tag. Never make latest the production default.
2. Render before deployment. Scan the generated YAML with a policy tool such as Kyverno or Conftest, not only the Helm templates or Kustomize source.
3. Validate values and overlays in pull requests. Helm charts can use values.schema.json; Kustomize overlays should be rendered and diffed against the base.
4. Keep secrets in a secret manager or an encrypted configuration workflow. Neither Helm values nor Kustomize files are a safe place for plaintext production credentials.
5. Review ownership boundaries. A chart dependency or remote Kustomize base is executable input to your release process, so pin versions and review updates.

This is the same principle used when signing container images before Kubernetes deployment: provenance, policy, and the final artifact matter more than the convenience of the source syntax.

How to verify the rendered configuration

The measurable outcome is not that Helm or Kustomize exits successfully. It is that both render the intended Kubernetes object set and that a policy check rejects an unsafe change.

Render both variants and inspect the fields that must match:

kubectl kustomize kustomize/overlays/production > /tmp/web-production-kustomize.yaml
helm template prod helm/web \
  --namespace production \
  --values helm/web/values-production.yaml \
  > /tmp/web-production-helm.yaml
 
grep -E 'name: prod-web|namespace: production|replicas: 4|tag: 1.4.3|image: ghcr.io/example/web:1.4.3' \
  /tmp/web-production-kustomize.yaml \
  /tmp/web-production-helm.yaml

The exact YAML ordering will differ, and the Helm resource names include the release name. Compare the API objects and security-relevant fields, not the raw files line by line.

Before applying either output, run a dry-run against a configured cluster:

kubectl apply --dry-run=server -f /tmp/web-production-kustomize.yaml
kubectl apply --dry-run=server -f /tmp/web-production-helm.yaml

If a rollout still fails after the rendered manifests look correct, investigate the cluster symptom separately. CrashLoopBackOff troubleshooting covers the next diagnostic path for containers that start and exit repeatedly.

When this comparison breaks down

The Helm vs Kustomize decision becomes less useful when the surrounding release system is the real source of complexity.

• A GitOps controller may support both tools and impose its own reconciliation, dependency, and diff behavior. Test the tool through the controller you actually use.
• Large Kustomize overlay trees can become difficult to trace, especially when patches target the same fields across several layers. Split overlays by ownership and keep patches small.
• Large Helm charts can become application-specific programming frameworks. Add chart tests, schema validation, and rendered snapshots before accepting more template logic.
• A chart and an overlay can both hide sensitive data in values files. Treat secrets, remote bases, dependencies, and plugins as supply-chain inputs regardless of the renderer.

The best choice is the one whose final manifest a different engineer can render, review, and explain without access to tribal knowledge.

Render both tools, review the output, and verify policy before deployment. Choose the renderer your team can own and verify.