diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 5b5f6b46ae69..a41b367de953 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -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 --- diff --git a/machine_configuration/mco-image-streams.adoc b/machine_configuration/mco-image-streams.adoc new file mode 100644 index 000000000000..0ee47b73eacd --- /dev/null +++ b/machine_configuration/mco-image-streams.adoc @@ -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] diff --git a/modules/mco-image-streams-deploying.adoc b/modules/mco-image-streams-deploying.adoc new file mode 100644 index 000000000000..e8799fe2690f --- /dev/null +++ b/modules/mco-image-streams-deploying.adoc @@ -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 create manifests +---- ++ +Replace `` 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/ +---- + +.. 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) +---- diff --git a/modules/mco-image-streams-updating.adoc b/modules/mco-image-streams-updating.adoc new file mode 100644 index 000000000000..9775ae63c7b6 --- /dev/null +++ b/modules/mco-image-streams-updating.adoc @@ -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 --type merge -p '{"spec":{"osImageStream":{"name":"rhel-10"}}}' +---- ++ +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 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/ +---- ++ +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 10.2 (Coughlan) +----