Merge branch 'rancher:main' into rke2-restore

2026-09-25 04:28:15 +00:00 · 2024-05-08 12:31:21 -07:00
parent 3c608b6756 7d3d40ae83
commit 1f6e54cf82
332 changed files with 30315 additions and 1281 deletions
@@ -7,12 +7,16 @@ title: Security FAQ
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/security"/>
 </head>

-**Is there a Hardening Guide?**
+### Is there a Hardening Guide?

-The Hardening Guide is now located in the main [Security](../reference-guides/rancher-security/rancher-security.md) section.
+The Hardening Guide is located in the main [Security](../reference-guides/rancher-security/rancher-security.md) section.

-<br/>
-
-**What are the results of Rancher's Kubernetes cluster when it is CIS benchmarked?**
+### Have hardened Rancher Kubernetes clusters been evaluated by the CIS Kubernetes Benchmark? Where can I find the results?

 We have run the CIS Kubernetes benchmark against a hardened Rancher Kubernetes cluster.  The results of that assessment can be found in the main [Security](../reference-guides/rancher-security/rancher-security.md) section.
+
+### How does Rancher verify communication with downstream clusters, and what are some associated security concerns?
+
+Communication between the Rancher server and downstream clusters is performed through agents. Rancher uses either a registered certificate authority (CA) bundle or the local trust store to verify communication between Rancher agents and the Rancher server. Using a CA bundle for verification is more strict, as only the certificates based on that bundle are trusted. If TLS verification for a explicit CA bundle fails, Rancher may fall back to using the local trust store for verifying future communication. Any CA within the local trust store can then be used to generate a valid certificate.
+
+As described in [Rancher Security Update CVE-2024-22030](https://www.suse.com/c/rancher-security-update/), under a narrow set of circumstances, malicious actors can take over Rancher nodes by exploiting the behavior of Rancher CAs. For the attack to succeed, the malicious actor must generate a valid certificate from either a valid CA in the targeted Rancher server, or from a valid registered CA. The attacker also needs to either hijack or spoof the Rancher server-url as a preliminary step. Rancher is currently evaluating Rancher CA behavior to mitigate against this and any similar avenues of attack. 
@@ -6,11 +6,11 @@ title: Node Drivers
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers"/>
 </head>

-Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a [Docker Machine driver](https://docs.docker.com/machine/drivers/). The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only `active` node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.
+A node driver is the same as a [Docker Machine driver](https://docs.docker.com/machine/drivers/). Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. By default, Rancher is packaged with many node drivers, but you can also create and add custom node drivers to Rancher.

-If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.
+Only `Active` node drivers are displayed in the Rancher UI when you create node templates. If there are specific node drivers that you don't want to show your users, you must deactivate these node drivers.

-#### Managing Node Drivers
+## Managing Node Drivers

 :::note Prerequisites:

@@ -21,17 +21,31 @@ To create, edit, or delete drivers, you need _one_ of the following permissions:

 :::

-## Activating/Deactivating Node Drivers
+### Activating/Deactivating Node Drivers

-By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, DigitalOcean, Linode and vSphere. If you want to show or hide any node driver, you can change its status.
+By default, Rancher only activates drivers for the most popular cloud providers, such as Amazon EC2, Azure, DigitalOcean, Linode and vSphere. If you want to show or hide any node driver, you can change its status.

 1. In the upper left corner, click **☰ > Cluster Management**.
+1.  In the left navigation menu, click **Drivers**.
+1.	On the **Node Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**.

-2.  In the left navigation menu, click **Drivers**.
+:::danger 

-2.	On the **Node Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**.
+You can lose access to clusters after deactivating a node driver.

-## Adding Custom Node Drivers
+Deactivating a node driver doesn't just affect its visibility in the Rancher UI. When you deactivate or delete a node driver, any nodes deployed with that driver become inaccessible. 
+
+For example, if you deactivate a vSphere node driver to hide it in the UI, and you have a vSphere cluster that was deployed with that driver, the initial node in the cluster will fail, and the entire cluster will become inaccessible. Attempts to delete the vSphere nodes will fail, with nodes stuck in an extended `Removing` state.
+
+Before you deactivate a node driver, make sure that it has no associated clusters. One way to check is to see if the respective platform for a driver is listed among your clusters:
+
+1. In the upper left corner, click **☰ > Cluster Management**.
+1. Select **Clusters**.
+1. Check the **Provider** column of the table for instances of the node driver you are deactivating.
+
+:::
+
+### Adding Custom Node Drivers

 If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster.

@@ -40,6 +54,6 @@ If you want to use a node driver that Rancher doesn't support out-of-the-box, yo
 1. On **Node Drivers** tab, click **Add Node Driver**.
 1.	Complete the **Add Node Driver** form. Then click **Create**.

-### Developing your own node driver
+### Developing Your Own Node Drivers

 Node drivers are implemented with [Docker Machine](https://docs.docker.com/machine/).
@@ -1,12 +1,12 @@
 ---
-title: Migrating vSphere In-tree to Out-of-tree
+title: Migrating VMware vSphere In-tree to Out-of-tree
 ---

 <head>
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-vsphere"/>
 </head>

-Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.
+Kubernetes is moving away from maintaining cloud providers in-tree. VMware vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

 This page covers how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration.

@@ -1,12 +1,12 @@
 ---
-title: Setting Up an In-tree vSphere Cloud Provider
+title: Setting Up an In-tree VMware vSphere Cloud Provider
 ---

 <head>
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere"/>
 </head>

-To set up the in-tree vSphere cloud provider, follow these steps while creating the vSphere cluster in Rancher:
+To set up the in-tree VMware vSphere cloud provider, follow these steps while creating the vSphere cluster in Rancher:

 1. Set **Cloud Provider** option to `Custom` or `Custom (In-Tree)`.
 1. Click on **Edit as YAML**
@@ -1,12 +1,12 @@
 ---
-title: Setting Up an Out-of-tree vSphere Cloud Provider
+title: Setting Up an Out-of-tree VMware vSphere Cloud Provider
 ---

 <head>
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere"/>
 </head>

-Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.
+Kubernetes is moving away from maintaining cloud providers in-tree. VMware vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

 This page covers how to install the Cloud Provider Interface (CPI) and Cloud Storage Interface (CSI) plugins after setting up a cluster.

@@ -25,7 +25,7 @@ Using the vSphere out-of-tree cloud provider requires Linux nodes and is not sup

 The Cloud Provider Interface (CPI) should be installed first before installing the Cloud Storage Interface (CSI).

-### 1. Create a vSphere cluster
+### 1. Create a VMware vSphere cluster

 1. Click **☰ > Cluster Management**.
 1. On the **Clusters** page, click **Create**.
@@ -33,7 +33,7 @@ For details on enabling the Azure cloud provider, refer to [this page.](azure.md

 For details on enabling the Google Compute Engine cloud provider, refer to [this page.](google-compute-engine.md)

-### Setting up the vSphere Cloud Provider
+### Setting up the VMware vSphere Cloud Provider

 For details on enabling the vSphere cloud provider, refer to [in-tree vSphere config](configure-in-tree-vsphere.md) and [out-of-tree vSphere config](configure-out-of-tree-vsphere.md).

@@ -86,7 +86,7 @@ Some Linux operating systems accept multiple domain names separated by spaces. H

 :::

-### Rancher on vSphere with ESXi 6.7u2 and above
+### Rancher on VMware vSphere with ESXi 6.7u2 and above

 If you are using Rancher on VMware vSphere with ESXi 6.7u2 or later with Red Hat Enterprise Linux 8.3, CentOS 8.3, or SUSE Enterprise Linux 15 SP2 or later, it is necessary to disable the `vmxnet3` virtual network adapter hardware offloading feature. Failure to do so will result in all network connections between pods on different cluster nodes to fail with timeout errors. All connections from Windows pods to critical services running on Linux nodes, such as CoreDNS, will fail as well. It is also possible that external connections may fail. This issue is the result of Linux distributions enabling the hardware offloading feature in `vmxnet3` and a bug in the `vmxnet3` hardware offloading feature that results in the discarding of packets for guest overlay traffic. To address this issue, it is necessary disable the `vmxnet3` hardware offloading feature. This setting does not survive reboot, so it is necessary to disable on every boot. The recommended course of action is to create a systemd unit file at `/etc/systemd/system/disable_hw_offloading.service`, which disables the `vmxnet3` hardware offloading feature on boot. A sample systemd unit file which disables the `vmxnet3` hardware offloading feature is as follows. Note that `<VM network interface>` must be customized to the host `vmxnet3` network interface, e.g., `ens192`:

@@ -21,11 +21,62 @@ The `cattle-cluster-agent` is used to connect to the Kubernetes API of [Rancher

 The `cattle-node-agent` is used to interact with nodes in a [Rancher Launched Kubernetes](launch-kubernetes-with-rancher.md) cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The `cattle-node-agent` is deployed using a DaemonSet resource to make sure it runs on every node. The `cattle-node-agent` is used as fallback option to connect to the Kubernetes API of [Rancher Launched Kubernetes](launch-kubernetes-with-rancher.md) clusters when `cattle-cluster-agent` is unavailable.

+### Requests
+
+The `cattle-cluster-agent` pod does not define the default CPU and memory request values. As a baseline, we recommend setting the CPU request at `50m` and memory request at `100Mi`. However, it is important that you assess your use case appropriately and that you allocate the correct resources to your cluster for your needs.
+
+To configure request values through the UI:
+
+<Tabs groupId="k8s-distro">
+<TabItem value="RKE">
+
+1. When you [create](./launch-kubernetes-with-rancher.md) or edit an existing cluster, go to the **Cluster Options** section.
+1. Expand the **Cluster Configuration** subsection.
+1. Configure your request values using the **CPU Requests** and **Memory Requests** fields as needed.
+
+</TabItem>
+<TabItem value="RKE2/K3s">
+
+1. When you [create](./launch-kubernetes-with-rancher.md) or edit an existing cluster, go to the **Cluster Configuration**.
+1. Select the **Cluster Agent** subsection.
+1. Configure your request values using the **CPU Reservation** and **Memory Reservation** fields as needed.
+
+</TabItem>
+</Tabs>
+
+If you prefer to configure via YAML, add the following snippet to your configuration file:
+
+<Tabs groupId="k8s-distro">
+<TabItem value="RKE">
+
+```yaml
+cluster_agent_deployment_customization:
+  override_resource_requirements:
+    requests:
+      cpu: 50m
+      memory: 100Mi
+```
+
+</TabItem>
+<TabItem value="RKE2/K3s">
+
+```yaml
+spec:
+  clusterAgentDeploymentCustomization:
+    overrideResourceRequirements:
+      requests:
+        cpu: 50m
+        memory: 100Mi 
+```
+
+</TabItem>
+</Tabs>
+
 ### Scheduling rules

-The `cattle-cluster-agent` uses either a fixed set of tolerations, or dynamically-added tolerations based on taints applied to the control plane nodes. This structure allows [Taint based Evictions](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#taint-based-evictions) to work properly for `cattle-cluster-agent`. 
+The `cattle-cluster-agent` uses either a fixed set of tolerations, or dynamically-added tolerations based on taints applied to the control plane nodes. This structure allows [Taint based Evictions](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#taint-based-evictions) to work properly for `cattle-cluster-agent`.

-If control plane nodes are present in the cluster, the default tolerations will be replaced with tolerations matching the taints on the control plane nodes. The default set of tolerations are described below. 
+If control plane nodes are present in the cluster, the default tolerations will be replaced with tolerations matching the taints on the control plane nodes. The default set of tolerations are described below.

 | Component              | nodeAffinity nodeSelectorTerms             | nodeSelector | Tolerations                                                                    |
 | ---------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ |
@@ -1,5 +1,5 @@
 ---
-title: Creating a vSphere Virtual Machine Template
+title: Creating a VMware vSphere Virtual Machine Template
 ---

 <head>
@@ -1,12 +1,12 @@
 ---
-title: Creating Credentials in the vSphere Console
+title: Creating Credentials in the VMware vSphere Console
 ---

 <head>
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials"/>
 </head>

-This section describes how to create a vSphere username and password. You will need to provide these vSphere credentials to Rancher, which allows Rancher to provision resources in vSphere.
+This section describes how to create a VMware vSphere username and password. You must provide these vSphere credentials to Rancher, which allows Rancher to provision resources in vSphere.

 The following table lists the permissions required for the vSphere user account:

@@ -1,12 +1,12 @@
 ---
-title: Provisioning Kubernetes Clusters in vSphere
+title: Provisioning Kubernetes Clusters in VMware vSphere
 ---

 <head>
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere"/>
 </head>

-In this section, you'll learn how to use Rancher to install an [RKE](https://rancher.com/docs/rke/latest/en/)  Kubernetes cluster in vSphere.
+In this section, you'll learn how to use Rancher to install an [RKE](https://rancher.com/docs/rke/latest/en/)  Kubernetes cluster in VMware vSphere.

 First, you will set up your vSphere cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision nodes in vSphere.

@@ -17,16 +17,16 @@ For details on configuring the vSphere node template, refer to the [vSphere node
 For details on configuring RKE Kubernetes clusters in Rancher, refer to the [cluster configuration reference.](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#rke-cluster-config-file-reference)


- [Preparation in vSphere](#preparation-in-vsphere)
- [Creating a vSphere Cluster](#creating-a-vsphere-cluster)
+- [Preparation in vSphere](#preparation-in-vmware-vsphere)
+- [Creating a vSphere Cluster](#creating-a-vmware-vsphere-cluster)

-## Preparation in vSphere
+## Preparation in VMware vSphere

 This section describes the requirements for setting up vSphere so that Rancher can provision VMs and clusters.

 The node templates are documented and tested with the vSphere Web Services API version 6.5.

-### Create Credentials in vSphere
+### Create Credentials in VMware vSphere

 Before proceeding to create a cluster, you must ensure that you have a vSphere user with sufficient permissions. When you set up a node template, the template will need to use these vSphere credentials.

@@ -42,7 +42,7 @@ It must be ensured that the hosts running the Rancher server are able to establi

 See [Node Networking Requirements](../../../kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for a detailed list of port requirements applicable for creating nodes on an infrastructure provider.

-### Valid ESXi License for vSphere API Access
+### Valid ESXi License for VMware vSphere API Access

 The free ESXi license does not support API access. The vSphere servers must have a valid or evaluation ESXi license.

@@ -50,7 +50,7 @@ The free ESXi license does not support API access. The vSphere servers must have

 If you have a cluster with DRS enabled, setting up [VM-VM Affinity Rules](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.resmgmt.doc/GUID-7297C302-378F-4AF2-9BD6-6EDB1E0A850A.html) is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate ESXi hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes.

-## Creating a vSphere Cluster
+## Creating a VMware vSphere Cluster

 1. [Create your cloud credentials](#1-create-your-cloud-credentials)
 2. [Create a node template with your cloud credentials](#2-create-a-node-template-with-your-cloud-credentials)
@@ -1,6 +1,6 @@
 ---
-title: Creating a vSphere Cluster
-description: Use Rancher to create a vSphere cluster. It may consist of groups of VMs with distinct properties which allow for fine-grained control over the sizing of nodes.
+title: Creating a VMware vSphere Cluster
+description: Use Rancher to create a VMware vSphere cluster. It may consist of groups of VMs with distinct properties which allow for fine-grained control over the sizing of nodes.
 ---

 <head>
@@ -9,13 +9,13 @@ description: Use Rancher to create a vSphere cluster. It may consist of groups o

 import YouTube from '@site/src/components/YouTube'

-By using Rancher with vSphere, you can bring cloud operations on-premises.
+By using Rancher with VMware vSphere, you can bring cloud operations on-premises.

 Rancher can provision nodes in vSphere and install Kubernetes on them. When creating a Kubernetes cluster in vSphere, Rancher first provisions the specified number of virtual machines by communicating with the vCenter API. Then it installs Kubernetes on top of them.

 A vSphere cluster may consist of multiple groups of VMs with distinct properties, such as the amount of memory or the number of vCPUs. This grouping allows for fine-grained control over the sizing of nodes for each Kubernetes role.

-## vSphere Enhancements in Rancher v2.3
+## VMware vSphere Enhancements in Rancher v2.3

 The vSphere node templates have been updated, allowing you to bring cloud operations on-premises with the following enhancements:

@@ -33,7 +33,7 @@ It is not recommended to enable node auto-replace on a node pool of master nodes

 Node templates for vSphere have been updated so that when you create a node template with your vSphere credentials, the template is automatically populated with the same options for provisioning VMs that you have access to in the vSphere console.

-For the fields to be populated, your setup needs to fulfill the [prerequisites.](provision-kubernetes-clusters-in-vsphere.md#preparation-in-vsphere)
+For the fields to be populated, your setup needs to fulfill the [prerequisites.](provision-kubernetes-clusters-in-vsphere.md#preparation-in-vmware-vsphere)

 ### More Supported Operating Systems

@@ -45,7 +45,7 @@ In this YouTube video, we demonstrate how to set up a node template with the new

 <YouTube id="dPIwg6x1AlU"/>

-## Creating a vSphere Cluster
+## Creating a VMware vSphere Cluster

 In [this section,](provision-kubernetes-clusters-in-vsphere.md) you'll learn how to use Rancher to install an [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes cluster in vSphere.

@@ -53,7 +53,7 @@ In [this section,](provision-kubernetes-clusters-in-vsphere.md) you'll learn how

 For an example of how to provision storage in vSphere using Rancher, refer to [this section.](../../../manage-clusters/provisioning-storage-examples/vsphere-storage.md) In order to dynamically provision storage in vSphere, the vSphere provider must be enabled. Refer to [in-tree vSphere config](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md) and [out-of-tree vSphere config](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md).

-## Enabling the vSphere Cloud Provider
+## Enabling the VMware vSphere Cloud Provider

 When a cloud provider is set up in Rancher, the Rancher server can automatically provision new infrastructure for the cluster, including new nodes or persistent storage devices.

@@ -67,7 +67,7 @@ In [Rancher Launched Kubernetes clusters](../../launch-kubernetes-with-rancher/l
 ### hostPath Volumes
 Before you create a hostPath volume, you need to set up an [extra_bind](https://rancher.com/docs/rke/latest/en/config-options/services/services-extras/#extra-binds/) in your cluster configuration. This will mount the path as a volume in your kubelets, which can then be used for hostPath volumes in your workloads.

-### Migrating vSphere Cloud Provider from In-tree to Out-of-tree
+### Migrating VMware vSphere Cloud Provider from In-tree to Out-of-tree

 Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

@@ -1,12 +1,12 @@
 ---
-title: vSphere Storage
+title: VMware vSphere Storage
 ---

 <head>
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/vsphere-storage"/>
 </head>

-To provide stateful workloads with vSphere storage, we recommend creating a vSphereVolume StorageClass. This practice dynamically provisions vSphere storage when workloads request volumes through a PersistentVolumeClaim.
+To provide stateful workloads with VMware vSphere storage, we recommend creating a vSphereVolume StorageClass. This practice dynamically provisions vSphere storage when workloads request volumes through a PersistentVolumeClaim.

 In order to dynamically provision storage in vSphere, the vSphere provider must be enabled. See the following pages for more: [Out-of-tree vSphere](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md) and [in-tree vSphere](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md).

@@ -35,7 +35,7 @@ The following steps can also be performed using the `kubectl` command line tool.
 5. Optionally, specify additional properties for this storage class under **Parameters**. Refer to the [vSphere storage documentation](https://github.com/vmware-archive/vsphere-storage-for-kubernetes/blob/master/documentation/storageclass.md) for details.
 5. Click **Create**.

-### Creating a Workload with a vSphere Volume
+### Creating a Workload with a VMware vSphere Volume

 1. In the left navigation bar, click **Workload**.
 1. Click **Create**.
@@ -1,5 +1,5 @@
 ---
-title: Best Practices for Rancher Managed vSphere Clusters
+title: Best Practices for Rancher Managed VMware vSphere Clusters
 ---

 <head>
@@ -18,6 +18,6 @@ Configuring sensible monitoring and alerting rules is vital for running any prod

 Running well-built containers can greatly impact the overall performance and security of your environment. Refer to this [guide](tips-to-set-up-containers.md) for tips.

-### Best Practices for Rancher Managed vSphere Clusters
+### Best Practices for Rancher Managed VMware vSphere Clusters

 This [guide](rancher-managed-clusters-in-vsphere.md) outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.
@@ -1,12 +1,12 @@
 ---
-title: Installing Rancher in a vSphere Environment
+title: Installing Rancher in a VMware vSphere Environment
 ---

 <head>
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere"/>
 </head>

-This guide outlines a reference architecture for installing Rancher on an RKE Kubernetes cluster in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.
+This guide outlines a reference architecture for installing Rancher on an RKE Kubernetes cluster in a VMware vSphere environment. It also desctibes standard vSphere best practices as documented by VMware.


 <figcaption>Solution Overview</figcaption>
@@ -16,6 +16,6 @@ Refer to this [guide](tips-for-running-rancher.md) for our general advice for se

 This [guide](rancher-deployment-strategy.md) is designed to help you choose whether a regional deployment strategy or a hub-and-spoke deployment strategy is better for a Rancher server that manages downstream Kubernetes clusters.

-### Installing Rancher in a vSphere Environment
+### Installing Rancher in a VMware vSphere Environment

 This [guide](on-premises-rancher-in-vsphere.md) outlines a reference architecture for installing Rancher in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.
@@ -1,5 +1,5 @@
 ---
-title: VSphere Node Template Configuration
+title: VMware vSphere Node Template Configuration
 ---

 <head>
@@ -40,6 +40,10 @@ The AKSConfig, EKSConfig or GKEConfig represents the desired state. Nil values a

 UpstreamSpec represents the cluster as it is in the hosted Kubernetes provider. It's refreshed every 5 minutes. After the UpstreamSpec is refreshed, Rancher checks if the cluster has an update in progress. If it's currently updating, nothing further is done. If it is not currently updating, any managed fields on AKSConfig, EKSConfig or GKEConfig are overwritten with their corresponding value from the recently updated UpstreamSpec.

+:::warning
+When you import a cluster from a cloud provider into Rancher, UpstreamSpec represents the cluster state and Config is empty. If you then update the imported cluster through the Rancher UI, both UpstreamSpec and Config become non-null. Any further updates to the cluster should be applied through Rancher. This is because there is no safe way to determine if changes originating from UpstreamSpec represent the desired state or just a mismatch with Config. If you update the imported cluster through the cloud provider console after you apply any updates through the Rancher UI, the controller will deploy a rollback and the content of Config will be considered the desired state.
+:::
+
 The effective desired state can be thought of as the UpstreamSpec, plus all non-nil fields in the AKSConfig, EKSConfig or GKEConfig. This is what is displayed in the UI.

 If Rancher and another source attempt to update a cluster at the same time, or within 5 minutes of an update finishing, any managed fields are likely to get caught in a race condition. To use EKS as an example, a cluster may have PrivateAccess as a managed field. If PrivateAccess is false and then enabled in EKS console at 11:01, and tags are updated from Rancher before 11:05, then the value is likely to be overwritten. This can also occur if tags are updated while the cluster is still processing the update. The issue described in this example shouldn't occur if the cluster is registered and the PrivateAccess fields are nil.
@@ -13,15 +13,16 @@ Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG
 ### Double check if all the required ports are opened in your (host) firewall

 Double check if all the [required ports](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) are opened in your (host) firewall. The overlay network uses UDP in comparison to all other required ports which are TCP.
+
 ### Check if overlay network is functioning correctly

 The pod can be scheduled to any of the hosts you used for your cluster, but that means that the NGINX ingress controller needs to be able to route the request from `NODE_1` to `NODE_2`. This happens over the overlay network. If the overlay network is not functioning, you will experience intermittent TCP/HTTP connection failures due to the NGINX ingress controller not being able to route to the pod.

 To test the overlay network, you can launch the following `DaemonSet` definition. This will run a `swiss-army-knife` container on every host (image was developed by Rancher engineers and can be found here: https://github.com/rancherlabs/swiss-army-knife), which we will use to run a `ping` test between containers on all hosts.

-:::note
+:::caution

-This container [does not support ARM nodes](https://github.com/leodotcloud/swiss-army-knife/issues/18), such as a Raspberry Pi. This will be seen in the pod logs as `exec user process caused: exec format error`.
+The `swiss-army-knife` container does not support Windows nodes. It also [does not support ARM nodes](https://github.com/leodotcloud/swiss-army-knife/issues/18), such as a Raspberry Pi. When the test encounters incompatible nodes, this is recorded in the pod logs as an error message, such as `exec user process caused: exec format error` for ARM nodes, or `ImagePullBackOff (Back-off pulling image "rancherlabs/swiss-army-knife)` for Windows nodes.

 :::