add docs for the imported-cluster-version-management feature

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

@@ -31,13 +31,13 @@ kubectl create clusterrolebinding cluster-admin-binding \
 
 Since, by default, Google Kubernetes Engine (GKE) doesn't grant the `cluster-admin` role, you must run these commands on GKE clusters before you can register them. To learn more about role-based access control for GKE, please see [the official Google documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control).
 
-### Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE)  
+### Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE)
 
-To successfully import or provision EKS, AKS, and GKE clusters from Rancher, the cluster must have at least one managed node group. 
+To successfully import or provision EKS, AKS, and GKE clusters from Rancher, the cluster must have at least one managed node group.
 
 AKS clusters can only be imported if local accounts are enabled. If a cluster is configured to use Microsoft Entra ID for authentication, Rancher will not be able to import the cluster and report an error.
 
-EKS Anywhere clusters can be imported/registered into Rancher with an API address and credentials, as with any downstream cluster. EKS Anywhere clusters are treated as imported clusters and do not have full lifecycle support from Rancher. 
+EKS Anywhere clusters can be imported/registered into Rancher with an API address and credentials, as with any downstream cluster. EKS Anywhere clusters are treated as imported clusters and do not have full lifecycle support from Rancher.
 
 GKE Autopilot clusters aren't supported. See [Compare GKE Autopilot and Standard](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison) for more information about the differences between GKE modes.
 
@@ -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/>
-  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/>
-  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.
+5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup:
+   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.
+   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-the-version-management-feature-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:
 
-- The ability to [upgrade the Kubernetes version](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)
-  :::danger
+[RKE2](https://docs.rke2.io) is Rancher's next-generation Kubernetes distribution for datacenter and cloud installations.
 
-  After a cluster has been imported into Rancher, upgrades should be performed using Rancher. Upgrading an imported cluster outside of Rancher is **not** supported.
+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 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
+- Enable or disable [version management](#configuring-the-version-management-feature-for-rke2-and-k3s-clusters)
+- [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
+- View a read-only version of the cluster’s configuration arguments and environment variables used to launch each node
 
 ### 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 the Version Management Feature for RKE2 and K3s clusters
+
+The version management feature for imported RKE2 and K3s cluster can be configured using one of the following options:
+
+- **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.
+- **System-default** (default): Inherits behavior from the global **imported-cluster-version-management** setting.
+
+You can define the default behavior for newly created clusters or existing ones set to system-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.
+
+:::danger
+
+When version management is enabled for a cluster, upgrading it outside of Rancher may lead to unexpected consequences.
+
+:::
+
 ## 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
@@ -304,4 +325,4 @@ This section lists some of the most common errors that may occur when importing
 
     ```sh
     az aks update --resource-group <resource-group> --name <cluster-name> --enable-local-accounts
-    ```
+    ```

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

@@ -31,13 +31,13 @@ kubectl create clusterrolebinding cluster-admin-binding \
 
 Since, by default, Google Kubernetes Engine (GKE) doesn't grant the `cluster-admin` role, you must run these commands on GKE clusters before you can register them. To learn more about role-based access control for GKE, please see [the official Google documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control).
 
-### Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE)  
+### Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE)
 
-To successfully import or provision EKS, AKS, and GKE clusters from Rancher, the cluster must have at least one managed node group. 
+To successfully import or provision EKS, AKS, and GKE clusters from Rancher, the cluster must have at least one managed node group.
 
 AKS clusters can only be imported if local accounts are enabled. If a cluster is configured to use Microsoft Entra ID for authentication, Rancher will not be able to import the cluster and report an error.
 
-EKS Anywhere clusters can be imported/registered into Rancher with an API address and credentials, as with any downstream cluster. EKS Anywhere clusters are treated as imported clusters and do not have full lifecycle support from Rancher. 
+EKS Anywhere clusters can be imported/registered into Rancher with an API address and credentials, as with any downstream cluster. EKS Anywhere clusters are treated as imported clusters and do not have full lifecycle support from Rancher.
 
 GKE Autopilot clusters aren't supported. See [Compare GKE Autopilot and Standard](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison) for more information about the differences between GKE modes.
 
@@ -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/>
-  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/>
-  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.
+5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup:
+   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.
+   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-the-version-management-feature-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:
 
-- The ability to [upgrade the Kubernetes version](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)
-  :::danger
+[RKE2](https://docs.rke2.io) is Rancher's next-generation Kubernetes distribution for datacenter and cloud installations.
 
-  After a cluster has been imported into Rancher, upgrades should be performed using Rancher. Upgrading an imported cluster outside of Rancher is **not** supported.
+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 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
+- Enable or disable [version management](#configuring-the-version-management-feature-for-rke2-and-k3s-clusters)
+- [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
+- View a read-only version of the cluster’s configuration arguments and environment variables used to launch each node
 
 ### 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 the Version Management Feature for RKE2 and K3s clusters
+
+The version management feature for imported RKE2 and K3s cluster can be configured using one of the following options:
+
+- **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.
+- **System-default** (default): Inherits behavior from the global **imported-cluster-version-management** setting.
+
+You can define the default behavior for newly created clusters or existing ones set to system-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.
+
+:::danger
+
+When version management is enabled for a cluster, upgrading it outside of Rancher may lead to unexpected consequences.
+
+:::
+
 ## 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
@@ -304,4 +325,4 @@ This section lists some of the most common errors that may occur when importing
 
     ```sh
     az aks update --resource-group <resource-group> --name <cluster-name> --enable-local-accounts
-    ```
+    ```