Helm Best Practices for Production Kubernetes
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.

Why Helm Matters in Production

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

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.tplto 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/elseandrangefor 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

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.mdusing 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 updatefor reproducibility. - Pin OCI charts by digest when supply-chain integrity matters; a tag can move, a digest cannot.
Security Hardening & Best Practices

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
NetworkPolicymanifests 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
limitsandrequestsfor 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:
--atomicis now--rollback-on-failure. The old flag still works with a deprecation warning; update pipelines before Helm 5 removes it.helm registry logintakes the registry hostname only. A full URL is no longer accepted.- Post-renderers are plugins. Scripts that pass an executable to
--post-rendererneed 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-sideonly when you have tested the conflict behavior with your operators and controllers. --forceis 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 updateand checkChart.lock. - RBAC denied: Confirm service account permissions via
kubectl auth can-i. - Template errors: Use
helm lintandhelm templatelocally, 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.

# 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.jsonfor 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
--atomicwith--rollback-on-failureand 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...
