OSDOCS Document how to perform boot image updates on vSphere clusters

machine_configuration/mco-update-boot-images-manual.adoc

@@ -14,6 +14,8 @@ For {product-title} platforms that do not support automatic boot image updating
 Red{nbsp}Hat does not support manually updating the boot image in control plane nodes.
 ====
 
+include::modules/mco-update-boot-images-vsphere.adoc[leveloffset=+1]
+
 include::modules/mco-update-boot-images-ibm-cloud.adoc[leveloffset=+1]
 
 include::modules/mco-update-boot-images-nutanix.adoc[leveloffset=+1]

modules/mco-update-boot-images-vsphere.adoc

@@ -0,0 +1,160 @@
+// Module included in the following assemblies:
+//
+// * machine_configuration/mco-update-boot-images.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="mco-update-boot-images-vsphere_{context}"]
+= Manually updating the boot image on an {vmw-short} cluster
+
+[role="_abstract"]
+You can manually update the boot image for your {vmw-first} cluster by configuring your machine sets to use the latest {product-title} image as the boot image to ensure that new nodes can scale up properly.
+
+vSphere boot images use a template that you create by uploading a {op-system-first} OVA image to the VMware vCenter. The template image is used by all machine sets as the boot image. The following procedure shows how to identify the correct boot image to use as the new boot image, how to create the template from the image in vCenter, and how to modify your compute machine sets to use that template image.
+
+[NOTE]
+====
+For clusters that use a default {op-system} image, you can configure the cluster to automatically update the boot image each time the cluster is updated. If you are using the following procedure, ensure that automatic boot image updates are disabled and skew enforcement is in manual mode. For more information, see "Boot image management" and "Boot image skew enforcement".
+====
+
+.Prerequisites
+
+* You have completed the general boot image prerequisites as described in the "Prerequisites" section of the link:https://access.redhat.com/articles/7053165#prerequisites-2[{product-title} Boot Image Updates knowledgebase article].
+
+* You have installed the {oc-first}.
+
+* You have set boot image skew enforcement to the manual or none mode. For more information, see "Configuring boot image skew enforcement".
+
+* You have disabled boot image management for the cluster. For more information, see "Disabling boot image management".
+
+* You have downloaded the latest version of the {product-title} installation program, openshift-install, from the {cluster-manager-url}. For more information, see "Obtaining the installation program."
+
+// The vSphere steps are copied from installation-vsphere-machines.adoc and tweaked based on the KB; last two steps from KB
+
+.Procedure
+
+. Obtain the latest boot image to use as the new boot image:
+
+.. Obtain the name of the new boot image by running the following command:
++
+[source,terminal]
+----
+$ openshift-install coreos print-stream-json | jq '.architectures.x86_64.artifacts.vmware'
+----
++
+.Example output
+[source,terminal]
+----
+{
+  "release": "9.6.20251023-0",
+  "formats": {
+    "ova": {
+      "disk": {
+        "location": "https://rhcos.mirror.openshift.com/art/storage/prod/streams/rhel-9.6/builds/9.6.20251023-0/x86_64/rhcos-9.6.20251023-0-vmware.x86_64.ova",
+        "sha256": "14fa549bb83b2e730de22312419b503bc1ce85adf72269582f0af60e366d87ff"
+      }
+    }
+  }
+}
+----
+
+.. Use the URL in the `location` field to download the image.
+
+. In the vSphere Client, create a template for the OVA image:
+.. From the *Hosts and Clusters* tab, right-click your cluster name and select *Deploy OVF Template*.
+.. On the *Select an OVF* tab, specify the name of the {op-system} OVA file that you downloaded.
+.. On the *Select a name and folder* tab, set a *Virtual machine name* for your template, such as using the {op-system-first} version number in the image name. Click the name of your vSphere cluster and select the folder.
+.. On the *Select a compute resource* tab, click the name of your vSphere cluster.
+.. On the *Select storage* tab, configure the storage options for your VM.
+*** Select *Thin Provision* or *Thick Provision*, based on your storage preferences.
+*** Select the datastore that you specified in your `install-config.yaml` file.
+*** If you want to encrypt your virtual machines, select *Encrypt this virtual machine*. See the section titled "Requirements for encrypting virtual machines" for more information.
+.. On the *Select network* tab, specify the network that you configured for the cluster, if available.
+.. When creating the OVF template, do not specify values on the *Customize template* tab or configure the template any further.
+.. On the *Ready to complete* tab, verify your settings and click *Finish*.
++
+The vSphere Client uploads the boot image to create the OVF template. This can take a few minutes depending on network speeds. You can keep track of this process in the task tab under _Deploy OVF template_.
+.. After the upload is complete, click the new virtual machine and click *Template* -> *Convert to template* -> *Yes*.
++
+You now have a VM template based on the new boot image, which you can use to update the machine set objects.
+
+. Update each of your compute machine sets to include the new boot image:
+
+.. Obtain the name of your machine sets for use in the following step by running the following command:
++
+[source,terminal]
+----
+$ oc get machineset -n openshift-machine-api
+----
++
+.Example output
+[source,terminal]
+----
+NAME                                 DESIRED   CURRENT   READY   AVAILABLE   AGE
+ci-ln-xw7zmyt-72292-x7nqv-worker-a   1         1         1       1           53m
+----
+
+.. Edit a machine set to update the `image` field in the `providerSpec` stanza to add your boot image by running the following command:
++
+[source,terminal]
+----
+$ oc patch machineset <machineset-name> -n openshift-machine-api --type json \
+  -p '[{"op": "replace", "path": "/spec/template/spec/providerSpec/value/template", "value": "ci-ln-6vjqx8t-c1627-bwxkr-rhcos-generated-region-generated-zone"}]'
+----
++
+Replace `<machineset_name>` with the name of your machine set.
+
+. If boot image skew enforcement in your cluster is set to the manual mode, update the version of the new boot image in the `MachineConfiguration` object as described in "Updating the boot image skew enforcement version".
+
+.Verification
+
+. Scale up a machine set to check that the new node is using the new boot image:
+
+.. Increase the machine set replicas by one to trigger a new machine by running the following command:
++
+[source,terminal]
+----
+$ oc scale --replicas=<count> machineset <machineset_name> -n openshift-machine-api
+----
+where:
+
+`<count>`:: Specifies the total number of replicas, including any existing replicas, that you want for this machine set.
+`<machineset_name>`:: Specifies the name of the machine set to scale.
+
+.. Optional: View the status of the machine set as it provisions by running the following command:
++
+[source,terminal]
+----
+$ oc get machines.machine.openshift.io -n openshift-machine-api -w
+----
++
+It can take several minutes for the machine set to achieve the `Running` state.
+
+.. Verify that the new node has been created and is in the `Ready` state by running the following command:
++
+[source,terminal]
+----
+$ oc get nodes
+----
+
+. Verify that the new node is using the new boot image by running the following command:
++
+[source,terminal]
+----
+$ oc debug node/<new_node> -- chroot /host cat /sysroot/.coreos-aleph-version.json
+----
++
+Replace `<new_node>` with the name of your new node.
++
+.Example output
+[source,terminal]
+----
+{
+# ...
+    "ref": "docker://ostree-image-signed:oci-archive:/rhcos-9.6.20251212-1-ostree.x86_64.ociarchive",
+    "version": "9.6.20251212-1"
+}
+----
+where:
+
+`version`:: Specifies the boot image version.
+