Helm

Helm Rollback: Version Management and Safe Deployments

Beginner
10 minutes
Updated October 2026

Manage Helm releases with rollback, upgrade history, and safe deployment patterns to recover from failed releases.

Table of Contents

Release History

Every Helm operation creates a revision — tracked in secrets (or ConfigMaps) in the namespace.

# See release history
helm history my-release
# REVISION  UPDATED                   STATUS       CHART          DESCRIPTION
# 1         Mon Oct  6 10:00:00 2026  deployed     myapp-1.0.0    Install complete
# 2         Mon Oct  6 11:30:00 2026  deployed     myapp-1.1.0    Upgrade complete
# 3         Mon Oct  7 09:00:00 2026  failed       myapp-1.2.0    Upgrade "myapp-1.2.0" failed
# See detailed info about a specific revision
helm get all my-release --revision 2
helm get manifest my-release --revision 2
helm get values my-release --revision 2

What Rollback Actually Does

Helm's versioning model is worth understanding before you rely on it — rollback reverts the chart state, not necessarily what your users see:

  • Reverts to the previous chart version + values — if you upgraded with --set image.tag=v2, a rollback goes back to whatever was in the previous revision's values, which is often v1. The image tag, config values, and resource definitions all revert together.
  • Does NOT roll back data changes — database migrations that ran during the upgrade, PVC contents, or external state are unaffected. A schema migration that added a column stays added; your rollback only changes the Kubernetes resources Helm manages.
  • Creates a NEW revision — rollback isn't "undo" — it's a fresh deployment with the old chart's manifest. helm history shows it as a new revision, not a return to an old one.

This is why --atomic on upgrade is safer than manual rollback after the fact — the failure detection and reversion happen automatically, before a broken release sits in "failed" for minutes while users hit it.

Rollback Basics

Roll Back to Previous Version

helm rollback my-release

Rolls back to the previous successful revision — skips failed ones.

Roll Back to Specific Revision

helm rollback my-release 1

Check What Changed

# Diff between revisions
helm diff revision my-release 1 3
# (requires helm-diff plugin: helm plugin install https://github.com/databus23/helm-diff)

Upgrade Patterns

Safe Upgrade with Rollback Ready

# Always use --wait and --timeout for production
helm upgrade my-release ./myapp \
  --wait \
  --timeout 5m \
  --atomic            # auto-rollback on failure

Upgrade with Specific Values

helm upgrade my-release ./myapp \
  --set image.tag=1.2.0 \
  --set replicaCount=3 \
  --reuse-values        # keep existing values, override specific ones

Dry Run Before Upgrading

helm upgrade my-release ./myapp \
  --set image.tag=1.2.0 \
  --dry-run --debug     # see what would change without applying

Failed Release Recovery

Stuck in "pending-upgrade" or "failed"

# Option 1: Rollback to last good version
helm rollback my-release

# Option 2: Uninstall and reinstall (destructive)
helm uninstall my-release
helm install my-release ./myapp

# Option 3: Force complete the release (risky)
helm upgrade my-release ./myapp --force

Release Stuck in "pending-install"

helm status my-release
# STATUS: pending-install — helm is waiting for something

# Force the release
helm upgrade my-release ./myapp --force

Atomic Upgrades

--atomic = auto-rollback if the upgrade fails:

helm upgrade my-release ./myapp \
  --atomic \
  --wait \
  --timeout 5m

Equivalent to:

helm upgrade my-release ./myapp --wait --timeout 5m || helm rollback my-release

In CI/CD Pipelines

#!/bin/bash
set -e

echo "Deploying..."
if helm upgrade --install my-release ./myapp \
    --namespace production \
    --wait \
    --timeout 5m \
    --atomic; then
  echo "Deploy successful"
else
  echo "Deploy failed, rolled back"
  exit 1
fi

Helmfile Alternative

For managing multiple releases:

# helmfile.yaml
releases:
  - name: myapp
    namespace: production
    chart: ./myapp
    values:
      - values-prod.yaml
helmfile -e production diff    # preview changes
helmfile -e production apply   # apply with rollback tracking

The helm-diff Plugin (Essential)

helm upgrade with --dry-run shows what would happen — helm diff shows what will change:

helm plugin install https://github.com/databus23/helm-diff

# See exactly what changes before upgrading
helm diff upgrade my-release ./myapp --set image.tag=1.2.0

# See what a rollback would do
helm diff revision my-release 1 3

The output is a proper diff of the rendered manifests — added/removed/changed resources, highlighted. It's the difference between "I think this upgrade changes the image tag" and "I can see it changes the image tag, the resource limits, and adds a new ConfigMap." Install it before your first production deploy.

Best Practices

1. Always Use --wait --atomic in Production

helm upgrade myapp ./chart --wait --atomic --timeout 5m

Without --wait, Helm marks the release "deployed" even if pods crash.

2. Keep History Manageable

# Limit history (default keeps all revisions)
helm upgrade myapp ./chart --history-max 10

3. Backup Critical Data Before Upgrades

# If the chart has database migrations, snapshot first
kubectl create job db-backup --image=postgres:16 -- pg_dump -h db -U postgres mydb > backup.sql
helm upgrade myapp ./chart --wait --atomic

4. Use --cleanup-on-fail

helm upgrade myapp ./chart \
  --atomic \
  --cleanup-on-fail    # removes resources created during failed upgrade

5. Test Rollback Path

# Before deploying to production, test rollback on staging
helm upgrade myapp ./chart --namespace staging --wait
# Verify it works
helm rollback myapp --namespace staging
# Verify rollback restores previous version

Common Issues

"cannot rollback to release ... already exists"

The release has resources that conflict with the rollback. Usually means the failed upgrade partially created resources that now block rollback.

# Check what's there
kubectl get all -n <namespace>

# Manually delete conflicting resources, then rollback
kubectl delete deployment bad-deploy -n <namespace>
helm rollback my-release

Rollback Deploys Old Image

Helm rolls back to the chart version, which may have the old image tag:

# If you upgraded with --set image.tag=v2, rollback goes to v1
# To rollback to a specific image, do a new upgrade:
helm upgrade myapp ./chart --set image.tag=v1 --wait --atomic

Secrets/Certs Not Rolled Back

Resources created outside Helm (hooks, init jobs, manually applied) aren't tracked and won't roll back. Keep all resources in templates.

Helm Hooks and Rollback Edge Cases

Hooks (helm.sh/hook) run outside the normal resource lifecycle — a pre-upgrade hook that ran during a failed upgrade still ran:

# This job runs before every upgrade — including failed ones
annotations:
  "helm.sh/hook": pre-upgrade
  "helm.sh/hook-weight": "5"

A migration hook that succeeded then rolled back leaves the DB in the post-migration state — your rollback brings back code that expects the old schema. Test hooks with rollback on staging before assuming they're safe.

Quick Reference

# List releases
helm list -n <namespace>

# Release status
helm status my-release -n <namespace>

# History
helm history my-release -n <namespace>

# Rollback
helm rollback my-release [revision] -n <namespace>

# Safe upgrade
helm upgrade my-release ./chart --wait --atomic --timeout 5m

# Preview changes
helm template my-release ./chart --set image.tag=new

# Uninstall
helm uninstall my-release -n <namespace>
Written & Reviewed by Yasir Masood, CloudOpsGuide Editor

Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.