Skip to content

Preserve custom add-on config during Kubernetes upgrade of Rancher-provisioned RKE2 or K3s cluster

Article Number: 000022134

Environment

  • Rancher v2.6 - v2.12
  • A Rancher-provisioned RKE2 or K3s cluster with customizations to add-on configurations

Procedure

In Rancher-provisioned RKE2 and K3s clusters the cluster components, such as the CNI or Cloud Provider, are managed via add-ons. The version of an add-on, and the available configuration, in addition to as default values, are tied to the particular RKE2 or K3s Kubernetes version.

In the UI form for add-on configuration (e.g. Cluster Management -> Edit Config -> Add-on: Calico) a warning is displayed: "Add-On Configuration can vary between Kubernetes versions. Changing the Kubernetes version may reset the values below." Upgrading the Kubernetes version (Cluster Management -> Edit Config -> Basics -> Kubernetes Version) and clicking 'Save' will display a warning: "Changing the Kubernetes Version can reset Add-On values. You should check that the values are as expected before continuing." If a user clicks 'Continue' and the upgrade is performed, without first re-applying any add-on configuration customizations, add-on configuration may revert to the default values, resulting in unexpected behaviour or cluster errors.

In order to mitigate this and ensure that any custom add-on configuration is persisted across the upgrade, the following procedure should be used:

  • Take a copy of the add-on custom configurations
  • Change the Kubernetes Version
  • Navigate back to the add-on configurations and re-apply any custom values that have been erased as a result of the change in Kubernetes Version
  • Click on Save to apply the changes, and click Continue when the Add-On Reset warning is displayed

In Rancher v2.13 improvements have been made to the UI handling of custom add-on configuration values, as detailed in https://github.com/rancher/dashboard/issues/5837