Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use Helm to package Kubernetes application configuration as a chart, install that chart as a named release, then upgrade or roll back the release as your deployment changes. This guide covers the full workflow using Helm CLI commands documented across Helm 4 and Helm 3; check the reference for your installed major version if a flag behaves differently.

Understand charts, releases, and revisions

A chart is the package containing Kubernetes templates and default configuration. A release is a named instance of a chart installed in a cluster. Helm tracks changes to each release as revisions, so you can inspect its history and roll back to a prior configuration. See the Helm Project’s Introduction to Helm.

Create and validate a chart

  1. Scaffold a chart directory: helm create mychart.

  2. Review mychart/Chart.yaml for chart metadata, mychart/values.yaml for default settings, and mychart/templates/ for the Kubernetes manifests Helm renders.

  3. Replace scaffolded settings with values appropriate for your application, including its image, labels, probes, resource requests and limits, and service configuration.

    Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  4. Check the chart for common issues with helm lint mychart, then render its templates locally with helm template mychart. These checks help catch chart and rendering problems before installation, but they do not verify that the resources will work in your cluster.

The Helm cheat sheet also lists helm show values for inspecting chart defaults and helm package for packaging a chart.

Install the chart as a release

For example, install the local chart as my-release in a new app namespace, using a separate production values file:

helm install my-release ./mychart --namespace app --create-namespace -f values-prod.yaml

The release name identifies this particular installation; it is distinct from the chart name. The namespace option scopes the release to Kubernetes namespace app, while --create-namespace creates that namespace if needed. The -f option (equivalent to --values) supplies configuration overrides. You can provide multiple values files or use --set key=value for individual overrides.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

To inspect what Helm proposes without installing it, add --dry-run --debug. If the chart declares dependencies that need to be fetched, add --dependency-update. Review the rendered manifests and configuration carefully before applying a production installation.

Upgrade a release and choose how values are handled

To update the existing release from the local chart and production values file, run:

helm upgrade my-release ./mychart -f values-prod.yaml

Helm upgrades a named release; it does not create one if it is absent. Add --install to use the same command for install-or-upgrade workflows:

helm upgrade --install my-release ./mychart --namespace app --create-namespace -f values-prod.yaml

Decide explicitly how the upgrade should combine new inputs with previously stored values:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Option Effect Useful when
--reuse-values Retains values from the existing release and merges in the new values or flags. You intend to keep prior custom settings while applying selected changes.
--reset-values Starts from the chart’s built-in defaults, then applies the values files or flags supplied for this upgrade. You want to discard previously stored overrides and define the desired inputs explicitly.
Explicit -f files or --set flags Supplies the overrides for the upgrade; confirm the treatment of existing values against the CLI reference for your Helm version. You want the deployment configuration visible in the command or version-controlled files.

For repeatable deployments, pin the chart version when installing or upgrading from a chart repository rather than allowing the selected chart version to vary. Where policy limits release history, set --history-max to control how many revisions are retained. Consult the Helm upgrade command reference for the flags and behavior available in your CLI version.

Choose what happens when an upgrade fails

An ordinary failed upgrade leaves you to inspect the failure and decide what recovery is appropriate. With --rollback-on-failure, Helm rolls the release back if the upgrade fails. Alternatively, you can review the failure and perform a manual rollback after checking release history. Choose the policy that suits your change and operational controls; do not assume every failure should trigger the same recovery action.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Inspect release history and roll back

First list the release’s revisions:

helm history my-release

Review the revision, chart, and status information to identify the configuration you intend to restore. Then specify that revision:

helm rollback my-release 1

Replace 1 with the revision you selected. Omitting the revision or using 0 targets the previous release. A rollback does not rewind the revision counter: if the release was installed at revision 1, upgraded to revisions 2 and 3, and then rolled back to revision 1, the restored configuration appears as revision 4. This keeps the release history chronological. See the Helm rollback command reference.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Rollback safeguards

  • Use --dry-run to simulate the rollback before applying it.

  • Use --cleanup-on-fail to remove resources newly created during a rollback if that rollback fails.

  • Use --no-hooks only when you deliberately want to suppress rollback hooks; hooks may perform application-specific actions.

After a rollback, run helm history my-release again to confirm the new revision and inspect its status.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.