diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index f3cadae08b7..76931a528ea 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 --- diff --git a/machine_configuration/mco-image-streams.adoc b/machine_configuration/mco-image-streams.adoc index 82a0b2fbd78..5c57dcbca87 100644 --- a/machine_configuration/mco-image-streams.adoc +++ b/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] //// diff --git a/modules/mco-image-streams-reverting.adoc b/modules/mco-image-streams-reverting.adoc new file mode 100644 index 00000000000..240a4f8b9f8 --- /dev/null +++ b/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 --type merge -p '{"spec":{"osImageStream":{"name":"rhel-9"}}}' +---- ++ +Replace `` 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/ +---- ++ +Replace `` 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) +---- diff --git a/modules/mco-image-streams-updating.adoc b/modules/mco-image-streams-updating.adoc index bfdfa6c733a..e2c6fc8fa52 100644 --- a/modules/mco-image-streams-updating.adoc +++ b/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 -o yaml +---- ++ +Replace `` 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/ +$ oc debug node/ -- chroot /host cat /etc/redhat-release ---- + Replace `` 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/ -- chroot /host cat /etc/os-release ---- + +Replace `` 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)" +# ... ----