Skip to content

[Dual stream/Image Stream] Support two major versions of RHEL CoreOS in a single OCP release & cluster #109617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mburke5678 wants to merge 7 commits into
base: main
Choose a base branch
from
Open

[Dual stream/Image Stream] Support two major versions of RHEL CoreOS in a single OCP release & cluster #109617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
aa70594
[Dual stream] Support two major versions of RHEL CoreOS in a single O…
Apr 6, 2026
0cb023e
edits
Apr 10, 2026
93e0ac7
Fix vale errors
Apr 10, 2026
b3dc5d1
Fix build error
Apr 10, 2026
40d2e9e
proofread
Apr 10, 2026
53f78ca
added defaultStream: rhel-10 step
Apr 13, 2026
f062f8f
edits
Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2470,6 +2470,9 @@ Topics:
- Name: Image mode for OpenShift
File: mco-coreos-layering
Distros: openshift-enterprise,openshift-origin
- Name: OpenShift Container Platform image streams
File: mco-image-streams
Distros: openshift-enterprise,openshift-origin
- Name: Machine Config Daemon metrics
File: machine-config-daemon-metrics
---
Expand Down
42 changes: 42 additions & 0 deletions machine_configuration/mco-image-streams.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
:_mod-docs-content-type: ASSEMBLY
:context: mco-image-streams
include::_attributes/common-attributes.adoc[]
[id="mco-image-streams"]
= Setting the {op-system} version in a cluster

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 Hat.

By default, {op-system} 9.x is installed on {product-title} clusters starting with 4.14.

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 will operate 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:

* Deploying {op-system} 10.x on a new {product-title} cluster.
* Upgrading an existing 4.21.2 or later cluster to {op-system} 10.x.

By default, the manifests created and used in installation process do not contain references to the `osImageStream` parameter, which is required to install {op-system} 10.x. The following procedures contain a step to add this parameter where needed. It is planned that this limitation will be addressed in a future {product-title} version.

include::modules/mco-image-streams-updating.adoc[leveloffset=+1]

include::modules/mco-image-streams-deploying.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:../installing/overview/index.adoc#ocp-installation-overview[{product-title} installation documentation]

* xref:../machine_configuration/mco-update-boot-images-manual.adoc#mco-update-boot-images-manual[Manually updating the boot image]
119 changes: 119 additions & 0 deletions modules/mco-image-streams-deploying.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
// Module included in the following assemblies:
//
// * machine configuration/mco-image-streams.adoc

:_mod-docs-content-type: PROCEDURE
[id="mco-image-streams-deploying_{context}"]
= Deploying a new {op-system} 10.x cluster

[role="_abstract"]
You can deploy a new {product-title} 4.22 cluster that uses {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 to install an {product-title} 4.22.x cluster. To install an {product-title} 4.21.x cluster, see link:https://access.redhat.com/articles/7138399[How to deploy a RHCOS 10 {product-title} cluster]. The following procedure describes steps you must perform before launching the installation program. For details on how to run the installation program, see the installation documentation for your platform.

.Prerequisites

* You reviewed the {product-title} installation documentation for the platform of your choice. The installation documentation addresses specific requirements and steps for each platform.

* You obtained the proper credentials to install the cluster on a platform of your choice. For more information, see the installation documentation.

* You downloaded the {product-title} installation program, openshift-install, from the {cluster-manager-url}. For more information, see "Obtaining the installation program" for your platform.

.Procedure

. Run the {product-title} installation program to create the installation manifests by running the following command:
+
[source,terminal]
----
$ ./openshift-install --dir <installation_directory> create manifests
----
+
Replace `<installation_directory>` with the path to the directory where you want to store the installation files.

. Edit the `install-config.yaml` manifest file to enable the required Technology Preview features and configure the installation program to use {op-system} 10.x by running the following command:
+
[source,terminal]
----
$ yq -i '.featureSet = "TechPreviewNoUpgrade" | .osImageStream = "rhel-10"' installer-dir/install-config.yaml
----
+
[WARNING]
====
Enabling the `TechPreviewNoUpgrade` feature set on your cluster cannot be undone and prevents minor version updates. You should not enable this feature set on production clusters.
====

. Deploy the cluster by running the following command:
+
[source,terminal]
----
$ ./openshift-install --dir installer-dir create cluster
----
+
After the installation finishes, the cluster is running with both machine config pools pointing to RHEL 10.x.

.Verification

* View the `OSImageStream` custom resource by running the following command:
+
[source,terminal]
----
$ oc get OSImageStream cluster -o yaml
----
+
The output appears similar to the following example:
+
.Example output
[source,terminal]
----
apiVersion: machineconfiguration.openshift.io/v1alpha1
kind: OSImageStream
metadata:
annotations:
machineconfiguration.openshift.io/release-image-version: c26a561cf361f0c5ba7afbd7e69eeebcd6a5175c
name: cluster
spec: {}
#...
status:
availableStreams:
- name: rhel-10
osExtensionsImage: registry.ci.openshift.org/ocp/4.22-2026-04-09-065530@sha256:34baf90f333d89690a2f99b3ab746f8a43fee99b1218a8a058f75231f7c7ab53
osImage: registry.ci.openshift.org/ocp/4.22-2026-04-09-065530@sha256:b208f0f861d009008b43a103e64d087f6da59e480bb0292d401895e041095da7
- name: rhel-9
osExtensionsImage: registry.ci.openshift.org/ocp/4.22-2026-04-09-065530@sha256:4aa864da633b1ce0a3612992a75849ff2b7d289699fa9b9b400522371a77d3ea
osImage: registry.ci.openshift.org/ocp/4.22-2026-04-09-065530@sha256:cb34964bd5d957a1226e9fb082a591b650eca339ebd4aad15343d02fc21130dd
defaultStream: rhel-10
# ...
----
+
The `status.availableStreams.osImage` value under `name: rhel-10` is the pull spec for the {op-system} 10.x image. The nodes use this image because of the `osImageStream: rhel-10` parameter that you added to the `install-config.yaml` file in a previous step.

* Examine the `/etc/redhat-release file` to see the current {op-system} version on the cluster:

.. Log in to a node by using the following command:
+
[source,terminal]
----
$ oc debug node/<node_name>
----

.. 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 10.2 (Coughlan)
----
152 changes: 152 additions & 0 deletions modules/mco-image-streams-updating.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
// Module included in the following assemblies:
//
// * machine configuration/mco-image-streams.adoc

:_mod-docs-content-type: PROCEDURE
[id="mco-image-streams-updating_{context}"]
= 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 link:https://access.redhat.com/articles/7138399[How to deploy a RHCOS 10 {product-title} cluster].

You must update the boot image in your cluster to at least RHCOS 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.

[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 10.x.
====

.Prerequisites

* You have updated the boot image in your cluster to at least {op-system} 9.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".

.Procedure

. Confirm that your cluster has the {op-system} 10.x stream available by running the following command:
+
[source,terminal]
----
$ oc get osImageStreams/cluster -o yaml | grep rhel-10
----
+
.Example output
[source,terminal]
----
- 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:

* Update all of the nodes in your cluster to RHCOS 10:
+
.. 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/v1alpha1
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-10
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-10` parameter directs the Machine Config Operator (MCO) to update the nodes to the image referenced in `status.availableStreams.osImage` value under `name: rhel-10`.

* Update all machine config pools to RHCOS 10:
+
--
.. Update the worker machine config pool to RHCOS 10 by using the following command:
+
[source,terminal]
----
$ oc patch mcp worker --type merge -p '{"spec":{"osImageStream":{"name":"rhel-10"}}}'
----

.. Update the control plane machine config pool to RHCOS 10 by using the following command:
+
[source,terminal]
----
$ oc patch mcp master --type merge -p '{"spec":{"osImageStream":{"name":"rhel-10"}}}'
----

.. Update all custom machine config pools to RHCOS 10 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-10"}}}'
----
+
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 10.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 10.2 (Coughlan)
----