Helm Best Practices for Production Kubernetes

March 24, 2026 · 12 min read · By Thomas A. Anderson

Updated November 2026. Helm 4 is current; the chart examples below use the stable chart API and call out Helm 4 changes where they matter.

Helm is still the default packaging layer for Kubernetes, but the gap between a chart that installs and a chart you can safely upgrade is wide. This guide is the production checklist: the Helm best practices that prevent broken releases, silent security regressions, and version drift.

Quick answer: keep values typed and documented, version the chart and the app separately, validate values with a schema, make security contexts and network policies defaults, pin dependencies and OCI artifacts, and render/lint in CI before every upgrade.

Helm chart deployment architecture
Helm chart deployment architecture , values, templates, and release flow

Why Helm Matters in Production

Abstract background with warm lighting
Helm brings structure and predictability to production Kubernetes environments.

The gap between a Helm chart that works locally and one that survives real-world production is stark. Teams deploying at scale need:

  • Consistent, repeatable releases across environments (dev, staging, prod).
  • Safe, auditable upgrades and rollbacks, with clear changelogs and versioning.
  • Security by default, from RBAC to image scanning and network isolation.
  • Extensible templating, to avoid copy-pasta YAML and hardcoding.

As the Helm Best Practices Guide and other sources confirm, these needs are addressed only by following a disciplined approach to chart design, templating, and release management.

The 12 Helm Best Practices That Matter Most

If you only read one section, read this one. The rest of the guide shows the templates, commands, and trade-offs behind each practice.

  1. Use _helpers.tpl for names and labels. Never hardcode release-scoped names in manifests.
  2. Keep environment differences in values files. Do not fork templates for dev, staging, and production.
  3. Document every value and ship production-safe defaults. A value without a comment becomes tribal knowledge.
  4. Validate values with values.schema.json. Run the validation in CI, before a release reaches the cluster.
  5. Bump the chart version on every chart change. Keep appVersion separate and tied to the image tag.
  6. Pin subchart dependencies and commit Chart.lock. Reproducible builds need locked inputs.
  7. Pin OCI charts by digest when integrity matters. A tag can move; a digest cannot.
  8. Set CPU and memory requests and limits for every pod. No chart should rely on the cluster’s defaults.
  9. Make a secure securityContext the default. Non-root, read-only root filesystem, dropped capabilities, and no privilege escalation.
  10. Ship least-privilege RBAC and a default-deny NetworkPolicy. Security should be part of the chart, not an afterthought.
  11. Keep secrets out of values. Use External Secrets, Secrets Store CSI, or workload identity instead of plaintext values.
  12. Lint, render, diff, and test rollback in CI. A release you cannot roll back is not production-ready.

Templating in Helm Charts

DevOps team collaborating around a laptop
DevOps teams use Helm templating to create flexible, reusable Kubernetes manifests.

Helm’s Go templating engine is the powerhouse behind chart flexibility. It allows you to dynamically generate Kubernetes manifests based on user-provided values, environment-specific overrides, and reusable helpers.

Real-World Templating Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    app: {{ include "myapp.name" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    metadata:
      labels:
        app: {{ include "myapp.name" . }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}

Key templating patterns for production:

  • {{ include "myapp.fullname" . }}: Uses a helper in _helpers.tpl to generate unique, release-scoped names (Helm docs).
  • Values files (values.yaml) should specify production-safe defaults for resources, image tags, and scheduling constraints.
  • Use if/else and range for conditional resources or lists.

Production Values Example

replicaCount: 3
image:
  repository: myregistry.io/myapp
  tag: 1.5.3
service:
  port: 8080
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
nodeSelector:
  environment: production
tolerations:
  - key: "node-role.kubernetes.io/worker"
    operator: "Exists"
    effect: "NoSchedule"

This structure ensures that production deployments get the right resources, node placement, and runtime isolation for reliability and compliance.

Versioning Helm Charts for Production

Software versioning and release management
Versioning is the foundation of safe, reproducible releases in Helm.

Helm uses Semantic Versioning (SemVer 2.x) for chart versions, a practice verified in OneUptime’s production guide and the official Helm conventions.

Chart.yaml versioning fields:

  • version: The chart version (SemVer, e.g., 2.1.0).
  • appVersion: The version of the deployed application (matches container tag).

Chart.yaml Example

apiVersion: v2
name: myapp
description: My app Helm Chart
type: application
version: 2.1.0
appVersion: "1.5.3"

Automated Version Bumping (CI/CD Script)

#!/bin/bash
set -e
CHART_DIR=${1:-.}
BUMP_TYPE=${2:-patch} # major, minor, patch
CURRENT_VERSION=$(yq '.version' "$CHART_DIR/Chart.yaml")
NEW_VERSION=$(semver "$CURRENT_VERSION" -i "$BUMP_TYPE")
echo "Bumping version: $CURRENT_VERSION -> $NEW_VERSION"
yq -i ".version = \"$NEW_VERSION\"" "$CHART_DIR/Chart.yaml"
if [ -f "$CHART_DIR/Chart.lock" ]; then
  helm dependency update "$CHART_DIR"
fi
echo "Version updated to $NEW_VERSION"

Best practices for versioning and release:

  • Document all changes in CHANGELOG.md using the Keep Changelog format.
  • Use pre-release tags (-rc, -beta) for candidate and experimental releases.
  • Automate version checks in CI and reject PRs that don’t increment the chart version with changes.
  • Lock subchart dependencies and use helm dependency update for reproducibility.
  • Pin OCI charts by digest when supply-chain integrity matters; a tag can move, a digest cannot.

Security Hardening & Best Practices

This image shows wooden Scrabble tiles arranged on a rustic wooden surface to spell out the word "SECURITY," with scattered tiles surrounding it. It is suitable for articles related to cybersecurity, data protection, or digital safety topics.
Security defaults belong in the chart, not in a post-install checklist.

Security is non-negotiable in production. Recent guides (MITRE, OneUptime) agree on these must-haves:

  • RBAC hardening: Use resource name restrictions and label selectors in RoleBindings. Limit service account permissions to only what’s needed.
  • Short-lived tokens: Reduce token lifespans for chart components that access the API.
  • Network Policy: Ship restrictive NetworkPolicy manifests to isolate workloads at the network level.
  • SecurityContext: Enforce runAsNonRoot, readOnlyRootFilesystem, drop all Linux capabilities, and disallow privilege escalation.
  • External secret integration: Use service account annotations for cloud provider roles and never store secrets in plain text.
  • Namespace isolation: Deploy sensitive workloads (e.g., scanners) in dedicated namespaces with strict labels and policies.
  • Resource limits: Always set CPU/memory limits and requests for all pods.

Sample Secure RBAC Template

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: {{ include "myapp.fullname" . }}-role
rules:
  - apiGroups: [""]
    resources: ["pods", "services"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "update", "patch"]

Strict values.schema.json Example

{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 3
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": {
          "type": "string"
        },
        "tag": {
          "type": "string",
          "pattern": "^[\\w\\.\\-]+$"
        }
      },
      "required": ["repository", "tag"]
    }
  },
  "required": ["replicaCount", "image"]
}

Helm 4 Changes That Affect Best Practices

Helm 4 keeps v2 charts working, but a few operational changes matter in CI and release scripts:

  • --atomic is now --rollback-on-failure. The old flag still works with a deprecation warning; update pipelines before Helm 5 removes it.
  • helm registry login takes the registry hostname only. A full URL is no longer accepted.
  • Post-renderers are plugins. Scripts that pass an executable to --post-renderer need to migrate to a plugin name.
  • OCI installs can pin a digest. Use oci://registry.example.com/charts/app@sha256:… when a mutable tag is not acceptable.

The practical upgrade rule is the same one that applies to charts: test the pipeline, not just the install. Run an existing release through helm template, a staging upgrade, and a rollback before you move production CI to Helm 4.

Additional Helm 4 changes

  • Server-side apply is the default for new releases. Helm 4 uses server-side apply when it installs a new chart release. Existing releases keep the apply method they were created with; use --server-side only when you have tested the conflict behavior with your operators and controllers.
  • --force is now --force-replace. Treat this as a deliberate recovery action, not a default upgrade flag.
  • Multi-document values are supported. Keep environment overrides separate instead of building one enormous values file.
  • Charts v3 is experimental. v2 charts continue to work; do not move production charts to the v3 API until the feature is stable.

Copy-Paste Helm 4 Checklist: 12 Practices in YAML

The checklist above is the policy. These are the concrete files, flags, and commands that implement it. Adapt the names and namespaces; do not copy the examples into production without reviewing the security settings.

1. Put names and labels in _helpers.tpl

{{- define "myapp.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{- define "myapp.fullname" -}}
{{- printf "%s-%s" .Release.Name (include "myapp.name" .) | trunc 63 | trimSuffix "-" -}}
{{- end -}}

Reference the helpers from every template instead of hardcoding {{ .Release.Name }} in labels and object names.

2. Keep environment differences in values files

# values-prod.yaml
replicaCount: 3
image:
  repository: registry.example.com/myapp
  tag: "1.5.3"
resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

Do not fork the chart for staging and production. Render the same templates with a different values file.

3. Document values and ship safe defaults

# values.yaml
# Number of application replicas. Production uses at least 3.
replicaCount: 3

# Container image. Pin a digest or an immutable tag in production.
image:
  repository: registry.example.com/myapp
  tag: "1.5.3"

# Set to true only after configuring an external secret store.
externalSecrets:
  enabled: false

A value without a comment becomes tribal knowledge. Put the safe default in values.yaml and require an explicit override for risky behavior.

4. Validate values with values.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1 },
    "image": {
      "type": "object",
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" }
      },
      "required": ["repository", "tag"]
    }
  },
  "required": ["replicaCount", "image"]
}

Run helm lint and helm template in CI. Schema validation catches missing values and type drift before the release reaches a cluster.

5. Version the chart and the app separately

apiVersion: v2
name: myapp
description: Production web application
type: application
version: 2.1.0       # chart version
appVersion: "1.5.3"  # application version

Bump version for every chart change. Update appVersion when the image tag changes. A CI check should reject a chart change that does not bump the chart version.

6. Pin dependencies and commit Chart.lock

dependencies:
  - name: postgresql
    version: 16.4.5
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
helm dependency update ./charts/myapp
git add charts/myapp/Chart.lock
git commit -m "Lock Helm dependencies"

Commit the lock file. A floating dependency range makes yesterday’s successful render unreproducible today.

7. Pin OCI charts by digest for integrity

# Tag-based install for development
helm install myapp oci://registry.example.com/charts/myapp --version 2.1.0

# Digest-pinned install for production
helm install myapp oci://registry.example.com/charts/myapp@sha256:REPLACE_WITH_DIGEST

A tag can move. A digest cannot. Use the digest form in release pipelines where supply-chain integrity matters.

8. Set requests and limits for every container

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

Set both. A limit without a request lets the scheduler overcommit the node; a request without a limit lets one pod consume the node during a traffic spike.

9. Make a secure securityContext the default

securityContext:
  runAsNonRoot: true
  runAsUser: 10001
  runAsGroup: 10001
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]
  seccompProfile:
    type: RuntimeDefault

Add writable emptyDir volumes only where the application truly needs to write. Do not mount a writable root filesystem just to make the container start.

10. Ship least-privilege RBAC and a default-deny NetworkPolicy

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: {{ include "myapp.fullname" . }}
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["{{ include "myapp.fullname" . }}-config"]
    verbs: ["get", "watch"]
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: {{ include "myapp.fullname" . }}-default-deny
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: {{ include "myapp.name" . }}
  policyTypes: ["Ingress", "Egress"]

Start from deny-by-default, then add the exact ingress and egress rules the workload needs. A chart that only works with unrestricted network access is not production-ready.

11. Keep secrets out of values

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: {{ include "myapp.fullname" . }}-db
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: production-secrets
    kind: ClusterSecretStore
  target:
    name: {{ include "myapp.fullname" . }}-db
  data:
    - secretKey: password
      remoteRef:
        key: myapp/database
        property: password

Use External Secrets, Secrets Store CSI, or workload identity. Do not put plaintext credentials in values.yaml, a ConfigMap, or a Git commit.

12. Lint, render, diff, and rehearse rollback in CI

helm lint ./charts/myapp
helm template myapp ./charts/myapp -f ./charts/myapp/values-prod.yaml > /tmp/rendered.yaml
helm diff upgrade myapp ./charts/myapp -f ./charts/myapp/values-prod.yaml
helm upgrade myapp ./charts/myapp -f ./charts/myapp/values-prod.yaml \
  --rollback-on-failure --timeout 10m
helm rollback myapp --namespace default

The exact rollback command depends on your release history and namespace. Rehearse it in staging before you need it in production. A release you cannot roll back is not a production release.

Troubleshooting and Debugging Helm Deployments

Production releases break, often due to subtle version, dependency, or RBAC mistakes. Here’s how to debug efficiently:

  • helm list -A –output json | jq ‘.[] | {name, chart, app_version}’

    View all releases with chart and app versions.
  • helm show chart myrepo/mychart –version 2.1.0

    Show a chart’s metadata for a specific version.
  • helm lint ./charts/myapp

    Lint a chart for template errors and best practice violations.
  • helm template myapp ./charts/myapp -f ./charts/myapp/values-prod.yaml

    Render all templates locally for inspection before deploying.
  • helm upgrade myapp ./charts/myapp -f ./charts/myapp/values-prod.yaml –debug

    Upgrade with verbose debug output to trace issues.
  • helm diff upgrade myapp ./charts/myapp -f ./charts/myapp/values-prod.yaml

    Review the rendered change before applying it; this requires the helm-diff plugin.
  • helm rollback myapp <revision>

    Rehearse the rollback path in staging, not after a failed production release.

Common pitfalls:

  • Chart version not bumped: CI fails if Chart.yaml’s version isn’t incremented with changes.
  • Dependency conflicts: Run helm dependency update and check Chart.lock.
  • RBAC denied: Confirm service account permissions via kubectl auth can-i.
  • Template errors: Use helm lint and helm template locally, not just in CI.

Comparison Table: Versioning and Security Features

Feature Helm (Official) OneUptime Guide MITRE/Industry Best Practice Source
Chart Versioning SemVer 2.x, required Strict SemVer, automated bumps SemVer, version check in CI helm.sh
App Version Field Free string (tag, SHA) Matches image tag Matches container version OneUptime
RBAC Hardening Recommended, not enforced Resource name restriction, label selectors Mandatory: least privilege and resource scoping MITRE
Network Policy Optional Ship default restrictive policy Mandatory for sensitive workloads OneUptime
values.schema.json Supported, not required Strict schema, validation in CI Required for production charts helm.sh

Helm Chart Deployment Architecture Diagram

The workflow above maps to one deployment path: values and templates render a chart, the release controller applies it to the cluster, and the same release record drives upgrades and rollbacks. The D2 block below is the same flow in diagram notation.

DevOps team working with Kubernetes
DevOps teams orchestrate Helm chart lifecycles across environments.
# Helm Chart Workflow Overview (in D2 diagram notation)
chart: rect
values_yaml: rect
template_engine: diamond
rendered_manifests: rect
helm_cli: rect
kubernetes_cluster: rect
ci_cd: rect
chart -> template_engine
values_yaml -> template_engine
template_engine -> rendered_manifests
helm_cli -> rendered_manifests
helm_cli -> kubernetes_cluster
ci_cd -> helm_cli
ci_cd -> chart
ci_cd -> values_yaml

Key Takeaways

Key Takeaways:

  • Follow strict SemVer versioning and enforce version bumps via CI/CD to prevent upgrade and rollback issues (OneUptime).
  • Use advanced templating (_helpers.tpl, conditionals, ranges) to maximize reuse and avoid YAML copy-pasta.
  • Apply security best practices: RBAC least privilege, short token lifespans, security contexts, network policies, and secret integration (MITRE).
  • Utilize values.schema.json for schema validation and defense against configuration drift or injection attacks.
  • Troubleshoot with helm lint, helm template, and release inspection before impacting production.
  • For Helm 4, replace --atomic with --rollback-on-failure and test registry login, post-renderers, and OCI digest installs before upgrading CI.

Want to go deeper? See the Helm Best Practices Guide, the Helm 4 overview, and MITRE’s security checklist. For GitOps workflows and monitoring integration, check out our in-depth guides on ArgoCD GitOps and Kubernetes Monitoring with Prometheus & Grafana.

Thomas A. Anderson

Mass-produced in late 2022, upgraded frequently. Has opinions about Kubernetes that he formed in roughly 0.3 seconds. Occasionally flops, but don't we all? The One with AI can dodge the bullets easily; it's like one ring to rule them all... sort of...