How to upgrade a Helm release on Kubernetes

Helm manages Kubernetes applications as named releases, with each release holding the chart, values, and revision history for the installed resources. When an application is already under Helm, a chart update, image change, replica count, service setting, or environment-specific override should move through a release upgrade instead of direct kubectl edits.

Helm records each successful upgrade as a new release revision in the target namespace. The release name and chart argument must still point to the application being managed, while --reuse-values carries the last release values forward before applying the new overrides.

An upgrade can replace workloads, run chart hooks, and create a rollback point, but it does not undo application data migrations or persistent-volume changes if the new release behaves badly. Keep the previous revision visible in history and run a workload-level smoke test before widening traffic.

Related: How to install a Helm chart on Kubernetes
Related: How to roll back a Helm release on Kubernetes

Steps to upgrade a Helm release on Kubernetes:

  1. Open a terminal with kubectl access to the target cluster and Helm available on PATH.
  2. Check the values currently saved on the release. 
    $ helm get values web --namespace web
USER-SUPPLIED VALUES:
fullnameOverride: web
image:
  repository: nginx
  tag: 1.27.5-alpine
replicaCount: 1

    Use the release name and namespace that match your installed chart. Release web starts with one replica and uses a local chart path named ./web-chart.

  3. Record the current release history before changing the release. 
    $ helm history web --namespace web
REVISION	UPDATED                 	STATUS  	CHART          	APP VERSION	DESCRIPTION
1       	Fri Jun 26 20:50:08 2026	deployed	web-chart-0.1.0	1.16.0     	Install complete

    Revision 1 is the rollback point if the upgrade needs to be reversed.

  4. Upgrade the release and wait for supported resources to become ready. 
    $ helm upgrade web ./web-chart --namespace web --reuse-values --set replicaCount=2 --wait --timeout 5m
Release "web" has been upgraded. Happy Helming!
NAME: web
LAST DEPLOYED: Fri Jun 26 20:50:33 2026
NAMESPACE: web
STATUS: deployed
REVISION: 2
DESCRIPTION: Upgrade complete
##### snipped #####

    --reuse-values carries forward prior custom values, --set changes only replicaCount, and --wait waits up to --timeout for supported resources to become ready.

    Prepare the application rollback or data restore path before upgrading charts that run migrations, change persistent storage, or modify external services.

  5. Confirm that Helm recorded a new deployed revision. 
    $ helm history web --namespace web
REVISION	UPDATED                 	STATUS    	CHART          	APP VERSION	DESCRIPTION
1       	Fri Jun 26 20:50:08 2026	superseded	web-chart-0.1.0	1.16.0     	Install complete
2       	Fri Jun 26 20:50:33 2026	deployed  	web-chart-0.1.0	1.16.0     	Upgrade complete
  6. Check release status for the upgraded resource state. 
    $ helm status web --namespace web
NAME: web
LAST DEPLOYED: Fri Jun 26 20:50:33 2026
NAMESPACE: web
STATUS: deployed
REVISION: 2
DESCRIPTION: Upgrade complete
RESOURCES:
==> v1/Deployment
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    2/2     2            2           25s
##### snipped #####

    The Deployment row confirms the release resources reflect the upgraded replica count.

  7. Wait for the Deployment rollout to complete. 
    $ kubectl rollout status deployment/web --namespace web --timeout=180s
deployment "web" successfully rolled out
  8. List the release-owned workload objects. 
    $ kubectl get deployment,pod --namespace web --selector app.kubernetes.io/instance=web
NAME                  READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/web   2/2     2            2           25s

NAME                       READY   STATUS    RESTARTS   AGE
pod/web-86d897f6ff-5kqs7   1/1     Running   0          1s
pod/web-86d897f6ff-mk6sz   1/1     Running   0          22s

    Both Pods running under the release selector confirm the values change reached Kubernetes and the upgraded workload converged.