Merge pull request #35530 from codyhoag/vmware-and-hardware-dep

codyhoag · web-flow · commit 1cd0f1fffef7 · 2021-10-14T09:10:59.000-04:00
OSDOCS-2620 Deprecation for vSphere &gt;= 6.7u3 and HW 13
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -490,6 +490,8 @@ Topics:
 - Name: Updating a restricted network cluster
   File: updating-restricted-network-cluster
   Distros: openshift-enterprise
+- Name: Updating hardware on nodes running on vSphere
+  File: updating-hardware-on-nodes-running-on-vsphere
 # - Name: Troubleshooting an update
 #  File: updating-troubleshooting
 ---
diff --git a/installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc b/installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc
@@ -37,6 +37,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-requirements-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-network-user-infra.adoc[leveloffset=+2]
diff --git a/installing/installing_vmc/installing-restricted-networks-vmc.adoc b/installing/installing_vmc/installing-restricted-networks-vmc.adoc
@@ -37,6 +37,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vmc/installing-vmc-customizations.adoc b/installing/installing_vmc/installing-vmc-customizations.adoc
@@ -30,6 +30,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc b/installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc
@@ -25,6 +25,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-requirements-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-network-user-infra.adoc[leveloffset=+2]
diff --git a/installing/installing_vmc/installing-vmc-network-customizations.adoc b/installing/installing_vmc/installing-vmc-network-customizations.adoc
@@ -30,6 +30,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vmc/installing-vmc-user-infra.adoc b/installing/installing_vmc/installing-vmc-user-infra.adoc
@@ -28,6 +28,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-requirements-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-network-user-infra.adoc[leveloffset=+2]
diff --git a/installing/installing_vmc/installing-vmc.adoc b/installing/installing_vmc/installing-vmc.adoc
@@ -28,6 +28,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc b/installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc
@@ -32,6 +32,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/installing-restricted-networks-vsphere.adoc b/installing/installing_vsphere/installing-restricted-networks-vsphere.adoc
@@ -38,6 +38,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-requirements-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-network-user-infra.adoc[leveloffset=+2]
diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc
@@ -24,6 +24,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc
@@ -27,6 +27,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc
@@ -25,6 +25,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/installing-vsphere-network-customizations.adoc b/installing/installing_vsphere/installing-vsphere-network-customizations.adoc
@@ -30,6 +30,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-requirements-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-network-user-infra.adoc[leveloffset=+2]
diff --git a/installing/installing_vsphere/installing-vsphere.adoc b/installing/installing_vsphere/installing-vsphere.adoc
@@ -29,6 +29,10 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1]
 
+.Additional resources
+
+* To update the hardware version for your vSphere nodes, see xref:../../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-hardware-on-nodes-running-on-vsphere[Updating hardware on nodes running in vSphere].
+
 include::modules/installation-requirements-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-network-user-infra.adoc[leveloffset=+2]
diff --git a/modules/installation-vsphere-infrastructure.adoc b/modules/installation-vsphere-infrastructure.adoc
@@ -20,6 +20,21 @@
 
 You must install the {product-title} cluster on a VMware vSphere version 6 or 7 instance that meets the requirements for the components that you use.
 
+
+.Version requirements for vSphere virtual environments
+[cols=2, options="header"]
+|===
+|Virtual environment product |Required version
+|VM hardware version | 13 or later
+|vSphere ESXi hosts | 6.5 or later
+|vCenter host   | 6.5 or later
+|===
+
+[IMPORTANT]
+====
+Installing a cluster on VMware vSphere version 6.7U2 or earlier and virtual hardware version 13 is now deprecated. These versions are still fully supported, but support will be removed in a future version of {product-title}. Hardware version 15 is now the default for vSphere virtual machines in {product-title}. To update the hardware version for your vSphere nodes, see the "Updating hardware on nodes running in vSphere" article.
+====
+
 .Minimum supported vSphere version for VMware components
 |===
 |Component | Minimum supported versions |Description
diff --git a/modules/installation-vsphere-machines.adoc b/modules/installation-vsphere-machines.adoc
@@ -85,6 +85,14 @@ In the following steps, you create a template and then clone the template for al
 Do not start the original VM template. The VM template must remain off and must be cloned for new {op-system} machines. Starting the VM template configures the VM template as a VM on the platform, which prevents it from being used as a template that machine sets can apply configurations to.
 //This admonition note also appears in `modules/installation-vsphere-machines.adoc` and `modules/windows-machineset-vsphere.adoc`.
 ====
+
+. Optional: Update the configured virtual hardware version in the VM template, if necessary. Follow link:https://kb.vmware.com/s/article/1010675[Upgrading a virtual machine to the latest hardware version] in the VMware documentation for more information.
++
+[IMPORTANT]
+====
+It is recommended that you update the hardware version of the VM template to version 15 before creating VMs from it, if necessary. Using hardware version 13 for your cluster nodes running on vSphere is now deprecated. If your imported template defaults to hardware version 13, you must ensure that your ESXi host is on 6.7U3 or later before upgrading the VM template to hardware version 15. If your vSphere version is less than 6.7U3, you can skip this upgrade step; however, a future version of {product-title} is scheduled to remove support for hardware version 13 and vSphere versions less than 6.7U3.
+====
+
 . After the template deploys, deploy a VM for a machine in the cluster.
 .. Right-click the template name and click *Clone* -> *Clone to Virtual Machine*.
 .. On the *Select a name and folder* tab, specify a name for the VM. You might include the machine type in the name, such as `control-plane-0` or `compute-1`.
diff --git a/modules/scheduling-virtual-hardware-update-on-vsphere.adoc b/modules/scheduling-virtual-hardware-update-on-vsphere.adoc
@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// updating/updating-hardware-on-nodes-running-in-vsphere.adoc
+
+[id="scheduling-virtual-hardware-update-on-vsphere_{context}"]
+= Scheduling an update for virtual hardware on vSphere
+
+Virtual hardware updates can be scheduled to occur when a virtual machine is powered on or rebooted. You can schedule your virtual hardware updates exclusively in vCenter by following link:https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-96C06236-C271-4CFE-857E-22D1FDEECC95.html[Schedule a Compatibility Upgrade for a Virtual Machine] in the VMware documentation.
+
+When scheduling an upgrade prior to performing an upgrade of {product-title}, the virtual hardware update occurs when the nodes are rebooted during the course of the {product-title} upgrade.
diff --git a/modules/update-vsphere-virtual-hardware-on-compute-nodes.adoc b/modules/update-vsphere-virtual-hardware-on-compute-nodes.adoc
@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+//
+// updating/updating-hardware-on-nodes-running-in-vsphere.adoc
+
+[id="update-vsphere-virtual-hardware-on-compute-nodes_{context}"]
+= Updating the virtual hardware for compute nodes on vSphere
+
+To reduce the risk of downtime, it is recommended that compute nodes be upgraded serially.
+
+[NOTE]
+====
+Multiple compute nodes can be upgraded in parallel given workloads are tolerant of having multiple nodes in a `NotReady` state. It is the responsibility of the administrator to ensure that the required compute nodes are available.
+====
+
+.Prerequisites
+
+* You have cluster administrator permissions to execute the required permissions in the vCenter instance hosting your {product-title} cluster.
+* Your vSphere ESXi hosts are version 6.7U3 or later.
+
+.Procedure
+
+. List the compute nodes in your cluster.
++
+[source,terminal]
+----
+$ oc get nodes -l node-role.kubernetes.io/worker
+----
++
+.Example output
+[source,terminal]
+----
+NAME              STATUS   ROLES    AGE   VERSION
+compute-node-0    Ready    worker   30m   v1.22.1
+compute-node-1    Ready    worker   30m   v1.22.1
+compute-node-2    Ready    worker   30m   v1.22.1
+----
++
+Note the names of your compute nodes.
+
+. Mark the compute node as unschedulable:
++
+[source,terminal]
+----
+$ oc adm cordon <compute_node>
+----
+
+. Evacuate the pods from the compute node. There are several ways to do this. For example, you can evacuate all or selected pods on a node:
++
+[source,terminal]
+----
+$ oc adm drain <compute_node> [--pod-selector=<pod_selector>]
+----
++
+See the "Understanding how to evacuate pods on nodes" section for other options to evacuate pods from a node.
+
+. Shut down the virtual machine (VM) associated with the compute node. Do this in the vSphere client by right-clicking the VM and selecting *Power* -> *Shut Down Guest OS*. Do not shut down the VM using *Power Off* because it might not shut down safely.
+
+. Upgrade the VM in the vSphere client. Follow link:https://kb.vmware.com/s/article/1010675[Upgrading a virtual machine to the latest hardware version] in the VMware documentation for more information.
+
+. Power on the VM associated with the compute node. Do this in the vSphere client by right-clicking the VM and selecting *Power On*.
+
+. Wait for the node to report as `Ready`:
++
+[source,terminal]
+----
+$ oc wait --for=condition=Ready node/<compute_node>
+----
+
+. Mark the compute node as schedulable again:
++
+[source,terminal]
+----
+$ oc adm uncordon <compute_node>
+----
+
+. Repeat this procedure for each compute node in your cluster.
diff --git a/modules/update-vsphere-virtual-hardware-on-control-plane-nodes.adoc b/modules/update-vsphere-virtual-hardware-on-control-plane-nodes.adoc
@@ -0,0 +1,62 @@
+// Module included in the following assemblies:
+//
+// updating/updating-hardware-on-nodes-running-in-vsphere.adoc
+
+[id="update-vsphere-virtual-hardware-on-control-plane-nodes_{context}"]
+= Updating the virtual hardware for control plane nodes on vSphere
+
+To reduce the risk of downtime, it is recommended that control plane nodes be upgraded serially. This ensures that the Kubernetes API remains available and etcd retains quorum.
+
+.Prerequisites
+
+* You have cluster administrator permissions to execute the required permissions in the vCenter instance hosting your {product-title} cluster.
+* Your vSphere ESXi hosts are version 6.7U3 or later.
+
+.Procedure
+
+. List the control plane nodes in your cluster.
++
+[source,terminal]
+----
+$ oc get nodes -l node-role.kubernetes.io/master
+----
++
+.Example output
+[source,terminal]
+----
+NAME                    STATUS   ROLES    AGE   VERSION
+control-plane-node-0    Ready    master   75m   v1.22.1
+control-plane-node-1    Ready    master   75m   v1.22.1
+control-plane-node-2    Ready    master   75m   v1.22.1
+----
++
+Note the names of your control plane nodes.
+
+. Mark the control plane node as unschedulable.
++
+[source,terminal]
+----
+$ oc adm cordon <control_plane_node>
+----
+
+. Shut down the virtual machine (VM) associated with the control plane node. Do this in the vSphere client by right-clicking the VM and selecting *Power* -> *Shut Down Guest OS*. Do not shut down the VM using *Power Off* because it might not shut down safely.
+
+. Upgrade the VM in the vSphere client. Follow link:https://kb.vmware.com/s/article/1010675[Upgrading a virtual machine to the latest hardware version] in the VMware documentation for more information.
+
+. Power on the VM associated with the control plane node. Do this in the vSphere client by right-clicking the VM and selecting *Power On*.
+
+. Wait for the node to report as `Ready`:
++
+[source,terminal]
+----
+$ oc wait --for=condition=Ready node/<control_plane_node>
+----
+
+. Mark the control plane node as schedulable again:
++
+[source,terminal]
+----
+$ oc adm uncordon <control_plane_node>
+----
+
+. Repeat this procedure for each control plane node in your cluster.
diff --git a/updating/updating-hardware-on-nodes-running-on-vsphere.adoc b/updating/updating-hardware-on-nodes-running-on-vsphere.adoc
@@ -0,0 +1,29 @@
+[id="updating-hardware-on-nodes-running-on-vsphere"]
+= Updating hardware on nodes running on vSphere
+include::modules/common-attributes.adoc[]
+:context: updating-hardware-on-nodes-running-in-vsphere
+
+toc::[]
+
+You must ensure that your nodes running in vSphere are running on the hardware version supported by {product-title}. Currently, hardware version 13 or later is supported for vSphere virtual machines in a cluster.
+
+You can update your virtual hardware immediately or schedule an update in vCenter.
+
+[IMPORTANT]
+====
+Using hardware version 13 for your cluster nodes running on vSphere is now deprecated. This version is still fully supported, but support will be removed in a future version of {product-title}. Hardware version 15 is now the default for vSphere virtual machines in {product-title}.
+====
+
+[id="updating-virtual-hardware-on-vsphere_{context}"]
+== Updating virtual hardware on vSphere
+
+To update the hardware of your virtual machines (VMs) on VMware vSphere, update your virtual machines separately to reduce the risk of downtime for your cluster.
+
+include::modules/update-vsphere-virtual-hardware-on-control-plane-nodes.adoc[leveloffset=+2]
+include::modules/update-vsphere-virtual-hardware-on-compute-nodes.adoc[leveloffset=+2]
+
+.Additional resources
+
+* xref:../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working-evacuating_nodes-nodes-working[Understanding how to evacuate pods on nodes]
+
+include::modules/scheduling-virtual-hardware-update-on-vsphere.adoc[leveloffset=+1]
