Merge pull request #1699 from jiaqiluo/211-imported-cluster-version-mgmt

New feature in 2.11: imported cluster version management

docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md

@@ -47,9 +47,10 @@ GKE Autopilot clusters aren't supported. See [Compare GKE Autopilot and Standard
 2. On the **Clusters** page, **Import Existing**.
 3. Choose the type of cluster.
 4. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
-5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup:<br/>
+5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup:
-  a. Click **Agent Environment Variables** under **Cluster Options** to set environment variables for [rancher cluster agent](../launch-kubernetes-with-rancher/about-rancher-agents.md). The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables can be set using agent environment variables.<br/>
+   1. Click **Agent Environment Variables** under **Cluster Options** to set environment variables for [rancher cluster agent](../launch-kubernetes-with-rancher/about-rancher-agents.md). The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables can be set using agent environment variables.
-  b. Enable Project Network Isolation to ensure the cluster supports Kubernetes `NetworkPolicy` resources. Users can select the **Project Network Isolation** option under the **Advanced Options** dropdown to do so.
+   1. Enable Project Network Isolation to ensure the cluster supports Kubernetes `NetworkPolicy` resources. Users can select the **Project Network Isolation** option under the **Advanced Options** dropdown to do so.
+   1. [Configure the version management feature for imported RKE2 and K3s clusters](#configuring-version-management-for-rke2-and-k3s-clusters).
 6. Click **Create**.
 7. The prerequisite for `cluster-admin` privileges is shown (see **Prerequisites** above), including an example command to fulfil the prerequisite.
 8. Copy the `kubectl` command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run `kubectl get nodes` to verify before running the command shown in Rancher.
@@ -124,18 +125,16 @@ After registering a cluster, the cluster owner can:
 ### Additional Features for Registered RKE2 and K3s Clusters
 
 [K3s](https://rancher.com/docs/k3s/latest/en/) is a lightweight, fully compliant Kubernetes distribution for edge installations.
+
 [RKE2](https://docs.rke2.io) is Rancher's next-generation Kubernetes distribution for datacenter and cloud installations.
 
-When an RKE2 or K3s cluster is registered in Rancher, Rancher will recognize it. The Rancher UI will expose the features for [all registered clusters,](#features-for-all-registered-clusters) in addition to the following features for editing and upgrading the cluster:
+When an RKE2 or K3s cluster is registered in Rancher, Rancher will recognize it.
+The Rancher UI will expose features available to [all registered clusters](#features-for-all-registered-clusters), along with the following options for editing and upgrading the cluster:
 
-- The ability to [upgrade the Kubernetes version](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)
+- Enable or disable [version management](#configuring-version-management-for-rke2-and-k3s-clusters)
-  :::danger
+- [Upgrade the Kubernetes version](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) when version management is enabled
-
+- Configure the [upgrade strategy](#configuring-rke2-and-k3s-cluster-upgrades) when version management is enabled
-  After a cluster has been imported into Rancher, upgrades should be performed using Rancher. Upgrading an imported cluster outside of Rancher is **not** supported.
+- View a read-only version of the cluster’s configuration arguments and environment variables used to launch each node
-
-  :::
-- The ability to configure the maximum number of nodes that will be upgraded concurrently
-- The ability to see a read-only version of the cluster's configuration arguments and environment variables used to launch each node in the cluster
 
 ### Additional Features for Registered EKS, AKS, and GKE Clusters
 
@@ -145,6 +144,24 @@ When you create an EKS, AKS, or GKE cluster in Rancher, then delete it, Rancher
 
 See [Cluster Management Capabilities by Cluster Type](kubernetes-clusters-in-rancher-setup.md) for more information about what features are available for managing registered clusters.
 
+## Configuring Version Management for RKE2 and K3s Clusters
+
+:::danger
+
+When version management is enabled for an imported cluster, upgrading it outside of Rancher may lead to unexpected consequences.
+
+:::
+
+The version management feature for imported RKE2 and K3s clusters can be configured using one of the following options:
+
+- **Global default** (default): Inherits behavior from the global **imported-cluster-version-management** setting.
+- **True**: Enables version management, allowing users to control the Kubernetes version and upgrade strategy of the cluster through Rancher.
+- **False**: Disables version management, enabling users to manage the cluster’s Kubernetes version independently, outside of Rancher.
+
+You can define the default behavior for newly created clusters or existing ones set to "Global default" by modifying the **imported-cluster-version-management** setting.
+
+Changes to the global **imported-cluster-version-management** setting take effect during the cluster’s next reconciliation cycle.
+
 ## Configuring RKE2 and K3s Cluster Upgrades
 
 :::tip
@@ -180,8 +197,12 @@ The current status of the plans can be viewed with this command:
 kubectl get plans -A -o yaml
 ```
 
+:::tip
+
 If the cluster becomes stuck in upgrading, restart the `system-upgrade-controller`.
 
+:::
+
 To prevent issues when upgrading, the [Kubernetes upgrade best practices](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) should be followed.
 
 ## Authorized Cluster Endpoint Support for RKE2 and K3s Clusters

versioned_docs/version-2.11/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md

@@ -47,9 +47,10 @@ GKE Autopilot clusters aren't supported. See [Compare GKE Autopilot and Standard
 2. On the **Clusters** page, **Import Existing**.
 3. Choose the type of cluster.
 4. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
-5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup:<br/>
+5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup:
-  a. Click **Agent Environment Variables** under **Cluster Options** to set environment variables for [rancher cluster agent](../launch-kubernetes-with-rancher/about-rancher-agents.md). The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables can be set using agent environment variables.<br/>
+   1. Click **Agent Environment Variables** under **Cluster Options** to set environment variables for [rancher cluster agent](../launch-kubernetes-with-rancher/about-rancher-agents.md). The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables can be set using agent environment variables.
-  b. Enable Project Network Isolation to ensure the cluster supports Kubernetes `NetworkPolicy` resources. Users can select the **Project Network Isolation** option under the **Advanced Options** dropdown to do so.
+   1. Enable Project Network Isolation to ensure the cluster supports Kubernetes `NetworkPolicy` resources. Users can select the **Project Network Isolation** option under the **Advanced Options** dropdown to do so.
+   1. [Configure the version management feature for imported RKE2 and K3s clusters](#configuring-version-management-for-rke2-and-k3s-clusters).
 6. Click **Create**.
 7. The prerequisite for `cluster-admin` privileges is shown (see **Prerequisites** above), including an example command to fulfil the prerequisite.
 8. Copy the `kubectl` command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run `kubectl get nodes` to verify before running the command shown in Rancher.
@@ -124,18 +125,16 @@ After registering a cluster, the cluster owner can:
 ### Additional Features for Registered RKE2 and K3s Clusters
 
 [K3s](https://rancher.com/docs/k3s/latest/en/) is a lightweight, fully compliant Kubernetes distribution for edge installations.
+
 [RKE2](https://docs.rke2.io) is Rancher's next-generation Kubernetes distribution for datacenter and cloud installations.
 
-When an RKE2 or K3s cluster is registered in Rancher, Rancher will recognize it. The Rancher UI will expose the features for [all registered clusters,](#features-for-all-registered-clusters) in addition to the following features for editing and upgrading the cluster:
+When an RKE2 or K3s cluster is registered in Rancher, Rancher will recognize it.
+The Rancher UI will expose features available to [all registered clusters](#features-for-all-registered-clusters), along with the following options for editing and upgrading the cluster:
 
-- The ability to [upgrade the Kubernetes version](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)
+- Enable or disable [version management](#configuring-version-management-for-rke2-and-k3s-clusters)
-  :::danger
+- [Upgrade the Kubernetes version](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) when version management is enabled
-
+- Configure the [upgrade strategy](#configuring-rke2-and-k3s-cluster-upgrades) when version management is enabled
-  After a cluster has been imported into Rancher, upgrades should be performed using Rancher. Upgrading an imported cluster outside of Rancher is **not** supported.
+- View a read-only version of the cluster’s configuration arguments and environment variables used to launch each node
-
-  :::
-- The ability to configure the maximum number of nodes that will be upgraded concurrently
-- The ability to see a read-only version of the cluster's configuration arguments and environment variables used to launch each node in the cluster
 
 ### Additional Features for Registered EKS, AKS, and GKE Clusters
 
@@ -145,6 +144,24 @@ When you create an EKS, AKS, or GKE cluster in Rancher, then delete it, Rancher
 
 See [Cluster Management Capabilities by Cluster Type](kubernetes-clusters-in-rancher-setup.md) for more information about what features are available for managing registered clusters.
 
+## Configuring Version Management for RKE2 and K3s Clusters
+
+:::danger
+
+When version management is enabled for an imported cluster, upgrading it outside of Rancher may lead to unexpected consequences.
+
+:::
+
+The version management feature for imported RKE2 and K3s clusters can be configured using one of the following options:
+
+- **Global default** (default): Inherits behavior from the global **imported-cluster-version-management** setting.
+- **True**: Enables version management, allowing users to control the Kubernetes version and upgrade strategy of the cluster through Rancher.
+- **False**: Disables version management, enabling users to manage the cluster’s Kubernetes version independently, outside of Rancher.
+
+You can define the default behavior for newly created clusters or existing ones set to "Global default" by modifying the **imported-cluster-version-management** setting.
+
+Changes to the global **imported-cluster-version-management** setting take effect during the cluster’s next reconciliation cycle.
+
 ## Configuring RKE2 and K3s Cluster Upgrades
 
 :::tip
@@ -180,8 +197,12 @@ The current status of the plans can be viewed with this command:
 kubectl get plans -A -o yaml
 ```
 
+:::tip
+
 If the cluster becomes stuck in upgrading, restart the `system-upgrade-controller`.
 
+:::
+
 To prevent issues when upgrading, the [Kubernetes upgrade best practices](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) should be followed.
 
 ## Authorized Cluster Endpoint Support for RKE2 and K3s Clusters