How to reinstall the managed-system-upgrade-controller in a Rancher-provisioned RKE2 or K3s cluster

Article Number: 000022404

Environment

• Rancher v2.12+
• A Rancher-provisioned RKE2 or K3s cluster

Procedure

The managed-system-upgrade-controller is an instance of the System Upgrade Controller (SUC). Rancher automatically deploys this as a Helm chart into Rancher-provisioned RKE2 and K3s clusters to manage rancher-system-agent upgrades during cluster lifecycle operations and Rancher upgrades.

During troubleshooting, if for example a user has accidentally deleted or altered  managed-system-upgrade-controller resources, a clean installation of the controller may be required. This article details the procedure to force a reinstallation of the chart.

1. Delete the App from the cluster

1. Explore the affected cluster within the Rancher UI.
2. In the left navigation menu, go to Apps -> Installed Apps.

3. Use the filter box to search for managed-system-upgrade-controller.

4. Note: The App name follows the format mcc-<cluster-name>-managed-system-upgrade-controller.

5. Click the vertical ellipsis (⋮) at the end of the row and select Delete.
6. Confirm the App name in the modal and click Delete.

2. Restart the cattle-cluster-agent

Once the App has been successfully deleted, and is no longer present in the Installed Apps list, restart the cattle-cluster-agent to trigger a reconciliation loop that detects the missing managed chart and initiates a fresh installation:

kubectl rollout restart deployment cattle-cluster-agent -n cattle-system

3. Verify reinstallation

1. Navigate back to Apps -> Installed Apps in the Rancher UI.
2. Wait a few moments for the managed-system-upgrade-controller to reappear.
3. Ensure the status transitions to Deployed.