OSDOCS MCO Dual stream RHEL9/10 Update

_topic_maps/_topic_map.yml

@@ -2568,7 +2568,7 @@ Topics:
   Distros: openshift-enterprise,openshift-origin
 - Name: Setting the RHCOS version in a cluster
   File: mco-image-streams
-  Distros: openshift-enterprise,openshift-origin
+  Distros: openshift-enterprise
 - Name: Machine Config Daemon metrics
   File: machine-config-daemon-metrics
 ---

machine_configuration/mco-image-streams.adoc

@@ -7,32 +7,19 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-You can create an {product-title} cluster that uses {op-system-first} 10.x or update an existing cluster to {op-system} 10.x, which is available as a Technology Preview feature in {product-title} 4.21.2 and greater. By running {op-system-first} 10.x as a Technology Preview feature, you can test how the operating system works with your cluster and your hardware, anticipate changes, and report bugs to Red{nbsp}Hat. 
+If you installed {product-title} with {op-system-first} version 9.x or you updated your cluster from {product-title} 4.22, which uses {op-system} 9.x by default, you can update the cluster to {op-system} 10.x.
 
-By default, {op-system} 9.x is installed on {product-title} clusters starting with 4.13.
+For new installations of {product-title} 5.0, {op-system} 10.x is installed by default.
 
-At any time, you can revert the cluster back to {op-system} 9.x, if needed.
-
-:FeatureName: Using {op-system} 10.x in an {product-title} cluster
-include::snippets/technology-preview.adoc[]
-
-{op-system} is a purpose-designed operating system for use with containers that is deployed by default on all {product-title} nodes. Each version of {op-system} is based on a specific version of {op-system-base-full}. For {product-title} 4.13 and greater, the {op-system} version is based on RHEL 9.x. 
-
-Running a cluster with {op-system} 10.x is for *testing purposes only* on test clusters, and should not be used on production clusters. For example, by testing your cluster with {op-system} 10.x, you can ensure that any existing hardware operates as expected with the new operating system. 
-
-You can use one of the following methods to run the nodes in a cluster on {op-system} 10.x:
-
-* Upgrading an existing 4.21.2 or later cluster to {op-system} 10.x. For more information, see "Updating the nodes in an existing cluster from {op-system} 9 to {op-system} 10".
-* Deploying {op-system} 10.x on a new {product-title} cluster. For more information, see "Installation configuration parameters".
+{op-system} is a purpose-designed operating system for use with containers that is deployed by default on all {product-title} nodes. Each version of {op-system} is based on a specific version of {op-system-base-full}. {op-system} 10.x is based on {op-system-base} 10.x.
 
 include::modules/mco-image-streams-updating.adoc[leveloffset=+1]
+// include::modules/mco-image-streams-reverting.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 [id="additional-resources_{context}"]
 == Additional resources
 
-* xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features[Enabling features using feature gates]
-
 * xref:../machine_configuration/mco-update-boot-images-manual.adoc#mco-update-boot-images-manual[Manually updating the boot image]
 
 ////

modules/mco-image-streams-reverting.adoc

@@ -0,0 +1,141 @@
+// Module included in the following assemblies:
+//
+// * machine configuration/mco-image-streams.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="mco-image-streams-reverting_{context}"]
+= Reverting the nodes in an existing cluster from {op-system} 10 to {op-system} 9
+
+[role="_abstract"]
+For an existing {product-title} 5.0 cluster that is using {op-system-first} 10.x, you can move the nodes in your machine config pools to {op-system} 9.x.
+
+For example, if you updated your cluster to use {op-system-first} 10.x rather than {op-system-first} 9.x, you can revert your cluster to 9.x, if needed.
+
+[IMPORTANT]
+====
+Running a cluster with a mixture of RHCOS 9.x and 10.x nodes is not supported. You must move all of your nodes to RHCOS 9.x.
+====
+
+.Procedure
+
+. Confirm that your cluster has the {op-system} 9.x stream available by running the following command:
++
+[source,terminal]
+----
+$ oc get osImageStreams/cluster -o yaml | grep rhel-9
+----
++
+.Example output
+[source,terminal]
+----
+  - name: rhel-9
+----
+
+. Update the nodes by using one of the following procedures:
+
+* Revert all of the nodes in your cluster to RHCOS 9:
++
+.. Edit the `OSImageStream` custom resource by running the following command:
++
+[source,terminal]
+----
+$ oc edit osimagestream cluster
+----
++
+.. Add or edit the `defaultStream` parameter to specify `rhel-10`:
++
+[source,terminal]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: OSImageStream
+metadata:
+  annotations:
+    machineconfiguration.openshift.io/release-image-version: c4a08067821f304642e731fdcca0c8c6a6b19484
+  creationTimestamp: "2026-04-13T17:27:41Z"
+  generation: 1
+  name: cluster
+  resourceVersion: "36503"
+  uid: f2ef4c15-4c1b-4117-850e-ae6adf408c4f
+spec:
+  defaultStream: rhel-9
+status:
+  availableStreams:
+  - name: rhel-10
+    osExtensionsImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:34baf90f333d89690a2f99b3ab746f8a43fee99b1218a8a058f75231f7c7ab53
+    osImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:b208f0f861d009008b43a103e64d087f6da59e480bb0292d401895e041095da7
+  - name: rhel-9
+    osExtensionsImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:4aa864da633b1ce0a3612992a75849ff2b7d289699fa9b9b400522371a77d3ea
+    osImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:cb34964bd5d957a1226e9fb082a591b650eca339ebd4aad15343d02fc21130dd
+  defaultStream: rhel-9
+----
++
+The `spec.defaultStream: rhel-9` parameter directs the Machine Config Operator (MCO) to revert the nodes to the image referenced in `status.availableStreams.osImage` value under `name: rhel-9`.
+
+* Revert all machine config pools to RHCOS 9:
++
+--
+.. Revert the worker machine config pool to RHCOS 9 by using the following command:
++
+[source,terminal]
+----
+$ oc patch mcp worker --type merge -p '{"spec":{"osImageStream":{"name":"rhel-9"}}}'
+----
+
+.. Revert the control plane machine config pool to RHCOS 9 by using the following command:
++
+[source,terminal]
+----
+$ oc patch mcp master --type merge -p '{"spec":{"osImageStream":{"name":"rhel-9"}}}'
+----
+
+.. Revert all custom machine config pools to RHCOS 9 by using the following command with the name of the machine config pool to update:
++
+[source,terminal]
+----
+$ oc patch mcp <mcp_name> --type merge -p '{"spec":{"osImageStream":{"name":"rhel-9"}}}'
+----
++
+Replace `<mcp_name>` with the names of the custom machine config pools to update.
+--
++
+[IMPORTANT]
+====
+Running a cluster with a mixture of RHCOS 9.x and 10.x nodes is not supported. You must move all of your nodes to RHCOS 9.x.
+====
++
+Wait for the pools to finish rolling out the update.
+
+.Verification
+
+. After the nodes have returned to the READY state, examine the `/etc/redhat-release` file to see the current {op-system} version on the nodes:
+
+.. Log in to a node by using the following command:
++
+[source,terminal]
+----
+$ oc debug node/<node_name>
+----
++
+Replace `<node_name>` with the name of the node. 
+
+.. Set `/host` as the root directory within the debug shell by using the following command:
++
+[source,terminal]
+----
+$ chroot /host
+----
+
+.. Look at the contents of the `/etc/redhat-release` file by using the following command:
++
+[source,terminal]
+----
+$ cat /etc/redhat-release
+----
++
+The output should appear similar to  the following example:
++
+.Example output
+[source,terminal]
+----
+Red Hat Enterprise Linux release 9.8 (Plow)
+----

modules/mco-image-streams-updating.adoc

@@ -7,9 +7,7 @@
 = Updating the nodes in an existing cluster from {op-system} 9 to {op-system} 10
 
 [role="_abstract"]
-For an existing {product-title} 4.21.2 or later cluster, you can move the nodes in your machine config pool to {op-system-first} 10.x. By running {op-system-first} 10.x as a Technology Preview feature, you can test how the operating system works with your cluster and your hardware, anticipate changes, and report bugs to Red Hat.
-
-Use the following procedure for an {product-title} 4.22.x cluster. For an {product-title} 4.21.x cluster that is 4.21.2 or later, see the link:https://access.redhat.com/articles/7138399[How to deploy a RHCOS 10 {product-title} cluster knowledgebase article].
+For an existing {product-title} 5.0 cluster that is using {op-system-first} 9.x, you can move the nodes to {op-system} 10.x. For 4.22.x clusters, you must first update to {product-title} 5.0, then update to {op-system} 10.x.
 
 [IMPORTANT]
 ====
@@ -20,8 +18,7 @@ Running a cluster with a mixture of RHCOS 9.x and 10.x nodes is not supported. Y
 
 * You have updated the boot image in your cluster to at least {op-system} 9.x. Note that the boot image on each node remains at {op-system} 9.x after installing or upgrading to {op-system} 10.x. After you configure {op-system} 10.x in your cluster, new nodes boot using {op-system} 9.x initially and automatically upgrade to {op-system} 10.x. For more information, see "Manually updating the boot image".
 
-* You have enabled the `TechPreviewNoUpgrade` feature set in your cluster's `FeatureGate` custom resource (CR).
-For more information, see "Enabling features using feature gates".
+* Your cluster is updated to {product-title} 5.0.
 
 .Procedure
 
@@ -37,8 +34,6 @@ $ oc get osImageStreams/cluster -o yaml | grep rhel-10
 ----
   - name: rhel-10
 ----
-+
-It can take several minutes for the `osImageStream` object to become available after you enable the `TechPreviewNoUpgrade` feature set.
 
 . Update the nodes by using one of the following procedures:
 
@@ -55,7 +50,7 @@ $ oc edit osimagestream cluster
 +
 [source,terminal]
 ----
-apiVersion: machineconfiguration.openshift.io/v1alpha1
+apiVersion: machineconfiguration.openshift.io/v1
 kind: OSImageStream
 metadata:
   annotations:
@@ -116,35 +111,69 @@ Wait for the pools to finish rolling out the update.
 
 .Verification
 
-. After the nodes have returned to the READY state, examine the `/etc/redhat-release` file to see the current {op-system} version on the nodes:
+* After the nodes have returned to the READY state, check the machine config pool status for the nodes in a machine config pool to view the current {op-system} version by running the following command:
++
+[source,terminal]
+----
+$ oc get machineconfigpool -n openshift-machine-config-operator <machine_config_pool_name> -o yaml
+----
++
+Replace `<machine_config_pool_name>` with the name of a machine config pool.
++
+The output should appear similar to  the following example:
++
+.Example output
+[source,terminal]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineConfigPool
+metadata:
+  name: worker
+# ...
+status
+# ...
+  osImageStream:
+    name: rhel-10
+----
 
-.. Log in to a node by using the following command:
+* Examine the `/etc/redhat-release` file on a node to see the current {op-system} version on the nodes by running the following command:
 +
 [source,terminal]
 ----
-$ oc debug node/<node_name>
+$ oc debug node/<node_name> -- chroot /host cat /etc/redhat-release
 ----
 +
 Replace `<node_name>` with the name of the node. 
-
-.. Set `/host` as the root directory within the debug shell by using the following command:
 +
+The output should appear similar to  the following example:
++
+.Example output
 [source,terminal]
 ----
-$ chroot /host
+Red Hat Enterprise Linux release 10.2 (Coughlan)
 ----
 
-.. Look at the contents of the `/etc/redhat-release` file by using the following command:
+* Examine the `/etc/os-release` file on a node to see the current {op-system} version on the nodes by running the following command:
 +
 [source,terminal]
 ----
-$ cat /etc/redhat-release
+$ oc debug node/<node_name> -- chroot /host cat /etc/os-release
 ----
 +
+Replace `<node_name>` with the name of the node. 
++
 The output should appear similar to  the following example:
 +
 .Example output
 [source,terminal]
 ----
-Red Hat Enterprise Linux release 10.2 (Coughlan)
+NAME="Red Hat Enterprise Linux CoreOS"
+VERSION="10.2.20260824-0 (Coughlan)"
+RELEASE_TYPE=stable
+ID="rhel"
+ID_LIKE="centos fedora"
+VERSION_ID="10.2"
+PLATFORM_ID="platform:el10"
+PRETTY_NAME="Red Hat Enterprise Linux CoreOS 10.2.20260824-0 (Coughlan)"
+# ...
 ----