Helm & Kustomize: Packaging Kubernetes Manifests

The copy-paste tax

You write a clean Kubernetes Deployment. It works. Then someone says "we need it in staging too," so you copy the YAML into a new folder and change the image tag, the replica count, and the host in the Ingress. Then prod arrives, and you copy it again, three replicas this time, a different resource limit, a real TLS secret. Now you have three near-identical copies of the same manifest, and the only honest description of the difference between them lives in your head.

Three months later someone adds a new environment variable to the dev copy and forgets the other two. Prod drifts. A debugging session that should take ten minutes takes an afternoon because nobody can tell which version is the source of truth. This is the copy-paste tax, and every team that runs Kubernetes pays it until they pick a packaging tool.

The two dominant answers are Helm and Kustomize. They solve the same problem, one set of manifests, many environments, in opposite ways. This article shows how each works, gives you a small example of both, and helps you decide which one (or both) belongs in your stack.

Templates vs patches

Helm parameterizes your manifests with a templating language; Kustomize layers plain-YAML patches on top of plain-YAML bases. Same destination, two philosophies.

The cleanest way to feel the difference is an analogy. Think about how you'd produce three versions of a printed letter.

Helm treats your YAML as a template, the chart isn't valid Kubernetes YAML on its own, it's a program that *renders into* YAML. Kustomize treats your YAML as data, every file is a real, applyable manifest, and overlays just describe the diffs. That single distinction drives almost every trade-off below.

The picture

Both tools sit between your source manifests and the cluster. You author once, then a per-environment input produces per-environment output, which finally lands in a namespace. Here is the shape of it:

1. 1

   Author the base once

   Write the Deployment, Service, and Ingress with sensible defaults. This is the single source of truth that every environment shares.

2. 2

   Describe what differs per environment

   With Helm, that's a values file per env. With Kustomize, that's an overlay folder with a kustomization.yaml and small patches.

3. 3

   Render the final YAML

   `helm template` or `kustomize build` turns base + env-input into concrete, fully-resolved manifests. No placeholders left.

4. 4

   Apply to the matching namespace

   The rendered output goes to the cluster, either directly via the CLI, or (better) committed to Git and reconciled by a GitOps controller.

Helm vs Kustomize: a head-to-head

The two tools overlap in purpose but diverge in mechanics. The table is the fast way to internalize the trade-offs before we look at code.

The same app, both ways

Imagine a small web app with a Deployment. Below is the Helm side, a values snippet that prod would supply to override the chart defaults. Notice the values file is *not* Kubernetes YAML; it's the data that fills the chart's {{ .Values.* }} placeholders.

# Overrides the chart defaults for production.
# The chart's templates read these via {{ .Values.* }}.
replicaCount: 3

image:
  repository: registry.example.com/web
  tag: "1.8.0"

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 512Mi

ingress:
  enabled: true
  host: app.example.com
  tls: true

# Install with:
#   helm upgrade --install web ./web-chart -f values-prod.yaml

Now the Kustomize side. The base is real, applyable YAML; the prod overlay is a tiny kustomization.yaml plus a patch that changes only what differs. No placeholders anywhere, every file would kubectl apply on its own.

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: prod
resources:
  - ../../base          # the shared, real manifests

images:
  - name: registry.example.com/web
    newTag: "1.8.0"     # bump the tag without editing the base

replicas:
  - name: web
    count: 3

patches:
  - patch: |-
      - op: replace
        path: /spec/template/spec/containers/0/resources/limits/memory
        value: 512Mi
    target:
      kind: Deployment
      name: web

# Render with:
#   kubectl kustomize overlays/prod   (or: kustomize build overlays/prod)

How they fit GitOps

Neither tool is a deployment system, they both just *produce YAML*. That makes them a perfect fit for GitOps, where Git is the source of truth and a controller continuously reconciles the cluster to match. You commit the chart-plus-values or the base-plus-overlays, and the controller renders and applies them for you.

Both ArgoCD and Flux speak Helm and Kustomize natively. Point Argo at a chart and a values file, or at an overlay folder, and it runs helm template / kustomize build under the hood, diffs the result against live state, and self-heals drift. The win: humans never run helm install or kubectl apply against prod, they open a pull request, and the merge *is* the deploy.

• Render in the pipeline, not the cluster, let the GitOps controller own helm template / kustomize build so what's in Git is exactly what runs.
• One repo, many overlays, keep base/ plus overlays/dev|stage|prod (or one chart with per-env values) so a diff between environments is a real, reviewable diff.
• Pin versions in Git, image tags and chart versions live in committed files, so every change has an author, a timestamp, and a one-click revert.

Common mistakes that cost hours

1. Over-templating Helm charts. Exposing forty knobs in values.yaml for an app three teams use makes the chart unreadable and every upgrade scary. Template only what genuinely varies; hardcode the rest.
2. Putting logic in templates. Nested {{ if }}/{{ range }} blocks turn a manifest into a program nobody can debug. When you find yourself writing conditionals around conditionals, the answer is usually a second values file, or Kustomize.
3. Letting environments drift. Hand-editing live resources with kubectl edit, or applying an overlay manually "just this once," silently desyncs the cluster from Git. Render from source every time and let GitOps catch drift.
4. Forgetting Kustomize has no rollback. It emits YAML and walks away. If you need versioned releases and helm rollback, that lifecycle is on you (or on your GitOps controller via Git history), don't assume the tool provides it.
5. Mixing both without a reason. Helm-inside-Kustomize and Kustomize-post-rendering-Helm are valid but advanced. Pick one as your default and only reach for the combo when a concrete need forces it.

Takeaways

Where to go next

Packaging is one piece of running Kubernetes well. Pair it with the operational and delivery practices around it:

• Read Kubernetes in Production: Beyond the Tutorial for the reliability concerns your manifests need to encode.
• Read GitOps: Declarative Delivery with ArgoCD & Flux to see how rendered manifests get continuously reconciled.
• Practice in the Helm lab and the kubectl lab, author a chart, build an overlay, diff the output.
• Follow the full DevOps Engineer path to put packaging, pipelines, and observability together.