Helm Best Practices

A field guide to shipping Helm charts and Kustomize overlays that stay reviewable, reproducible, and safe to upgrade.

How to Use This List

Treat each item as a check you can enforce in CI or in code review.

Groups A through E move from packaging discipline through security and delivery; adopt them in order if you are starting fresh.

None of these require exotic tooling - helm, kustomize, and kubectl cover all of them.

A - Versioning and Pinning

• Pin chart dependencies by exact or narrow range. Set version in Chart.yaml dependencies and commit Chart.lock so builds are reproducible.
• Bump the chart version on every chart change. GitOps controllers key on chart version to detect drift; a missed bump hides changes.
• Keep appVersion in sync with the image. Use .Chart.AppVersion as the default image tag so the packaged app and chart agree.
• Never depend on a floating chart tag. Pin third-party charts by version, not latest, or your cluster and CI will diverge.
• Pin base images by digest. Reference application images by digest in production values so a moved tag cannot change what runs.

B - Values and Configuration

• Ship a values.schema.json. Validate user-supplied values at install and upgrade so bad input fails fast with a clear message.
• Keep the chart generic. Put environment-specific values in per-env files, not in the chart's default values.yaml.
• Document every value. Comment each key in values.yaml so consumers know what is tunable and its default.
• Prefer values files over long --set chains. Files are reviewable and version-controlled; inline --set flags are easy to lose.
• Use global values for cross-cutting settings. Share registry, image pull secrets, and labels across parent and subcharts via .Values.global.

C - Template and Overlay Hygiene

• Test rendered output in CI. Run helm template and kustomize build on every PR and diff the result so surprises surface before merge.
• Factor names and labels into helpers. Define them once in _helpers.tpl and include them so every object carries the recommended app.kubernetes.io/* labels.
• Control whitespace deliberately. Use {{-/-}} and pipe include output through nindent to avoid malformed YAML.
• Keep template logic shallow. If a template needs heavy conditionals and loops, reconsider whether an overlay would be clearer.
• Edit overlays, not bases, for env changes. Put every environment delta in its overlay so the base stays a single source of truth.
• Let generator hashes drive rollouts. Keep Kustomize configMapGenerator/secretGenerator name-suffix hashes enabled so config changes restart pods.

D - Security Defaults

• Run as non-root with a restricted context. Set runAsNonRoot: true, drop capabilities, and use seccompProfile: RuntimeDefault in templates.
• Always set requests, limits, and probes. Bake resource requests, limits, and readiness/liveness probes into the chart so every install is schedulable and self-healing.
• Scan and sign chart images. Gate releases on a Trivy or Grype scan and verify Sigstore/cosign signatures before deploy.
• Ship default-deny NetworkPolicies. Include an opt-in NetworkPolicy so charts do not deploy fully open by default.
• Never template plaintext secrets into manifests. Source secrets from an external store or sealed/external secrets, not from committed values.

E - Delivery and Lifecycle

• Make upgrades idempotent. Use helm upgrade --install in CI so the same command installs or upgrades safely.
• Guard rollouts with --atomic and --wait. Auto-rollback on failure and block until resources report ready.
• Use hooks for migrations, with cleanup policies. Set helm.sh/hook plus hook-delete-policy so migration Jobs run at the right phase and do not accumulate.
• Lint before packaging. Run helm lint in CI and only then helm package and push to your OCI registry.
• Let one GitOps controller own apply and prune. Argo CD or Flux should render and reconcile; avoid manual helm install against the same release.

When You Are Done

You should be able to render any environment offline, review a PR and see exactly what changes, and upgrade with automatic rollback on failure.

If a change to a ConfigMap does not roll pods, or a chart edit ships without a version bump, revisit groups A and C.

FAQs

Why test helm template in CI? It catches malformed YAML and unexpected rendered changes before they reach the cluster, without touching a live API server.

Pin by tag or digest? Tag for charts (semver version), digest for the underlying container images in production.

Where do environment values belong? In per-environment values or overlay files, never in the chart's default values.yaml.

How do I stop stale ConfigMaps? Keep Kustomize generator hash suffixes enabled, or roll the Deployment via a checksum annotation in Helm.

Should I use hooks for database migrations? Yes, a pre-upgrade hook Job with a hook-delete-policy is the standard pattern.

How do I make upgrades safe? Combine --install, --atomic, and --wait so failed upgrades roll back automatically.

Related

• Templating vs Overlaying Manifests
• Helm Basics
• Chart Design
• Kustomize
• Helm vs Kustomize ADR

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).