Skip to content

How to migrate from using helm template to helm upgrade to manage Rancher upgrades in an air-gapped environment

Article Number: 000022006

Environment

  • Rancher Server installed in an air-gapped environment.
  • The initial installation was performed using the `helm template` command.

Procedure

When upgrading Rancher in an air-gapped environment, users who previously installed Rancher with helm template will encounter an "Error: UPGRADE FAILED: "rancher" has no deployed releases". This happens because helm template doesn't create a Helm release record in the cluster, which is essential for helm upgrade to function.

The standard solution provided in the Rancher documentation is to continue using the helm template method for subsequent upgrades. However, you may wish to migrate to the helm upgrade workflow, removing the additional step of templating the helm chart, before applying it with kubectl, during upgrades.

helm upgrade --install can be used to upgrade the Rancher chart, whilst creating the necessary Helm release record in the cluster. However, attempting to use helm upgrade --installwithout taking ownership of existing resources will result in an error like the following, because the Kubernetes resources (such as PriorityClass) lack the necessary Helm labels (app.kubernetes.io/managed-by: Helm) and annotations (meta.helm.sh/release-name: rancher and meta.helm.sh/release-namespace: cattle-system).

helm upgrade --install rancher ./rancher-<VERSION>.tgz --namespace cattle-system --set hostname=<RANCHER.YOURDOMAIN.COM>
Release "rancher" does not exist. Installing it now.
Error: Unable to continue with install: PriorityClass "rancher-critical" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "rancher"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "cattle-system"

To migrate from the helm template workflow to the helm upgrade workflow, you must run the helm upgrade --install command with the --take-ownership flag. This flag instructs Helm to take control of existing resources in the cluster that were created by a previous installation of the same chart, even if they lack Helm-specific annotations and labels.

This process essentially "adopts" the existing resources into a new Helm release, allowing future upgrades to be performed using the standard helm upgrade command.

Steps

  1. Navigate to the directory containing the Rancher Helm chart tarball.
  2. Run the helm upgrade --installcommand with the --take-ownership flag, along with your original installation values (e.g., --set hostname):

helm upgrade --install rancher ./rancher-<VERSION>.tgz --namespace cattle-system --set hostname=<RANCHER.YOURDOMAIN.COM> --take-ownership
3. Confirm that the command output shows a successful deployment, with "Rancher Server has been installed":

Release "rancher" does not exist. Installing it now.
NAME: rancher
LAST DEPLOYED: Fri Aug 22 15:18:09 2025
NAMESPACE: cattle-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Rancher Server has been installed.