Skip to content

How to disable Rancher System Upgrade Controller for Imported K3s and RKE2 Clusters

This document (000021913) is provided subject to the disclaimer at the end of this document.

Environment

Rancher v2.10.6 and later.

This KB should NOT implemented in Rancher environment if you have a mix of Custom, Node Provisioned as Imported clusters and disabling the Rancher System Upgrade Controller via the feature flag would cause unexpected consequences on Rancher Provisioned clusters.

Situation

The System Upgrade Controller can be installed on standalone K3S/RKE2 clusters to manage the cluster upgrades. However, when the standalone cluster is imported and managed by Rancher, an additional system upgrade controller is installed on these clusters by Rancher when Rancher is upgraded to v2.10.6.

Resolution

The procedure to disable/manage the Rancher System Upgrade Controller for imported clusters is a bit different for Rancher v2.10.x and 2.11.x.

Rancher v2.10.x:

DISCLAIMER: This method should only be followed for a Rancher setup if all the clusters are imported. If there is a mix of Custom, Node Provisioned and imported clusters, then its recommended to first upgrade Rancher to v2.11.x and follow the steps outlined in the below Rancher v2.11 section.

Users can disable the System Upgrade Controller deployed by Rancher for new and existing imported clusters (this includes the local cluster aka Rancher cluster since its considered as an imported cluster) by updating the Rancher helm chart values. Doing this would disable the Rancher System Upgrade Controller for all the imported clusters. To proceed:

  • Open the values.yaml file using your preferred editor. If you do not have this file, you can generate it for an existing Rancher installation using the below command:
helm get values rancher -n cattle-system -o yaml > values.yaml
  • Now you can update "features: managed-system-upgrade-controller=false" in the file. Below is a reference of the file after adding the flag:
bootstrapPassword: P@ssw2rd
features: managed-system-upgrade-controller=false
hostname: rancher.foo.bar
replicas: 1
  • Now you can perform the Rancher upgrade using the below command by passing the values.yaml file.

NOTE: Ensure that you add other parameters to the below command which was used to install Rancher initially.

 helm upgrade rancher rancher-prime/rancher \
  --namespace cattle-system \
  -f values.yaml \
  --version <DEPLOYED_RANCHER_VERSION>
  • Once upgraded, Rancher will not install any system-upgrade-controller for new clusters that you import.
  • An additional step needs to be performed for already existing imported clusters. Even after updating the Rancher helm release with the above helm values, the Rancher system-upgrade-controller would not be automatically removed. For existing clusters, you would have to remove the rancher system-upgrade-controller manually and to do that, you can run the below command on the existing cluster.
kubectl delete apps -n cattle-system system-upgrade-controller

NOTE: Going forward, any Kubernetes upgrades for the imported clusters where Rancher system-upgrade-controller is disabled should not be performed from Rancher UI. If performed, this would not upgrade the cluster and it would keep the cluster in "Upgrading" state with a message "Cluster is being upgraded" and you would notice the following error message in the Rancher pod logs:

2025/07/23 09:33:59 [ERROR] error syncing 'c-m-zz2sgb6k': handler k3s-upgrade-controller: the server could not find the requested resource (get plans.upgrade.cattle.io), requeuing
  • Hence, its recommended that you either perform manual or automated K3S/RKE2 upgrades outside of Rancher.

Rancher v2.11:

In Rancher v2.11 onwards, users can control the per-cluster behaviour of the Rancher System Upgrade Controller that should be deployed while importing the cluster. You can choose one of the values while importing the K3S/RKE2 cluster from the Rancher UI in the K8s version management section. This feature is called Version Management and more details about this can be found here.

  • Global default: This is the default value. Inherits behaviour from the global imported-cluster-version-management setting in Rancher UI > Global Settings > Settings.
  • True: Enables version management, allowing users to control the Kubernetes version and upgrade strategy of the cluster through Rancher. This would install Rancher system-upgrade-controller on the imported clusters.
  • False: Disables version management, enabling users to manage the cluster’s Kubernetes version independently, outside of Rancher. This option would NOT install Rancher system-upgrade-controller on the imported clusters.

Status

Top Issue

Disclaimer

This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.