How to deploy a RHCOS 10 OpenShift Container Platform cluster

Updated 21 Apr 2026

Red Hat Enterprise Linux CoreOS (RHCOS) is a purpose-designed operating system for use with containers that is deployed by default on all OpenShift Container Platform nodes. Each version of RHCOS is based on a specific version of Red Hat Enterprise Linux (RHEL). For OpenShift Container Platform 4.13 and greater, the RHCOS version is based on RHEL 9.x.

Starting with OpenShift Container Platform 4.21.2, you can run your cluster with RHCOS 10.x for testing purposes only. For example, by testing your cluster with RHCOS 10.x, you can ensure that any existing hardware operates as expected with the new operating system. You can either install a new OpenShift Container Platform 4.21.2 or greater test cluster that runs RHCOS 10.x. Or, you can upgrade an existing test cluster to RHCOS 10.x. Procedures to perform both of the tasks are described in this article.

These procedures apply to an OpenShift Container Platform 4.21.x cluster that is 4.21.2 or later. These procedures will not apply to 4.22+ clusters, when the release is available.

IMPORTANT: Using RHCOS 10.x in an OpenShift Container Platform cluster is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Enabling Technology Preview features cannot be undone and prevents minor version updates. You should not enable this feature set on production clusters. Red Hat does not recommend using it in production. This feature provides early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

By default, the manifests created and used in the installation process for OpenShift Container Platform 4.21.x and earlier do not contain references to the osImageStream parameter, which is currently required to install RHCOS 10.x. The following procedures contain a step to patch the control plane and worker machine config pools to add this parameter. Red Hat plans to address this limitation in a future OpenShift Container Platform version.

NOTE: The boot image on each node remains at RHCOS 9.x after installing or upgrading to RHCOS 10.x. After you configure RHCOS 10.x in your cluster, new nodes boot using RHCOS 9.x initially and automatically upgrade to RHEL 10.x.

Deploy a new RHCOS 10.x cluster

Perform the following steps to deploy a new OpenShift Container Platform that uses RHCOS 10.x.

Prerequisites

You should review the OpenShift Container Platform installation documentation for the platform of your choice. This documentation addresses specific requirements and steps for each platform.
You must obtain the proper credentials to install the cluster on a platform of your choice. For more information, see the OpenShift Container Platform 4.21 installation documentation.
You must download the OpenShift Container Platform installation program, openshift-install, from the This content is not included.OpenShift Cluster Manager. For more information, see Obtaining the installation program in the installation documentation for your platform, for example: Obtaining the installation program.

Procedure

Run the OpenShift Container Platform installation program to create the installation manifests by running the following command:
```
 ./openshift-install --dir <installation_directory> create manifests
```
Replace <installation_directory> with the path to the directory where you want to store the installation files.

Download the control plane and worker machine config pool custom resource manifests for the installation program to use, and patch each manifest to add the osImageStream parameter by running the following commands:

 curl -s https://raw.githubusercontent.com/openshift/machine-config-operator/refs/heads/release-4.21/manifests/master.machineconfigpool.yaml | yq '.spec.osImageStream.name = "rhel-10"' > <installation_directory>/openshift/master.machineconfigpool.yaml

 curl -s https://raw.githubusercontent.com/openshift/machine-config-operator/refs/heads/release-4.21/manifests/worker.machineconfigpool.yaml | yq '.spec.osImageStream.name = "rhel-10"' > <installation_directory>/openshift/worker.machineconfigpool.yaml

Replace <installation_directory> with the path to the directory that stores the installation files.

Edit the 99_feature-gate.yaml manifest file to enable the required Technology Preview features. For example, you can manually run the following command:
```
 yq -i '.spec.featureSet = "TechPreviewNoUpgrade"' <installation_directory>/openshift/99_feature-gate.yaml
```
Replace <installation_directory> with the path to the directory that stores the installation files.

Alternatively, you can manually edit this file to add the spec.featureSet parameter with the TechPreviewNoUpgrade value as described in Enabling feature sets using the CLI.

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:
```
 ./openshift-install --dir <installation_directory> create cluster
```
Replace <installation_directory> with the path to the directory that stores the installation files.

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:

  oc get OSIMAGESTREAM cluster -o yaml

The output should appear similar to the following example:

  apiVersion: machineconfiguration.openshift.io/v1alpha1
  kind: OSImageStream
  metadata:
    annotations:
      machineconfiguration.openshift.io/release-image-version: c26a561cf361f0c5ba7afbd7e69eeebcd6a5175c
    name: cluster
  spec: {}
  status:
    availableStreams:
    - name: rhel-9
      osExtensionsImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:b2fae727bddb8c50a465ae302f58859b8c4af3348a94114650f3f8ea980836d4
      osImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:eb1d1f17470cfadaec7dc4f717951d349b7e8e75f84ff22956941d69ce7246c2
    - name: rhel-10
      osExtensionsImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:12438c7e8586c4527be16633f48902ead60aa2a2d9305a2efbd09595165f3647
      osImage: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:bc0976717e1f525d4a2ee6320512bfa7d0d8420d3317ee7d65a7956c7792587f
    defaultStream: rhel-9

The status.rhel-10.osImage value is the pull spec for the RHCOS 10.x image. The nodes use this image because of the osImageStream.name.rhel-10 parameter that you added to the machine config pools in a previous step.

Examine the /etc/redhat-release file to see the current RHCOS version on the cluster.
1. Log in to a node by using the following command:
```
 oc debug node/<node_name>
```
2. Set /host as the root directory within the debug shell by using the following command:
```
 chroot /host
```
3. Look at the contents of the /etc/redhat-release file by using the following command:
```
 cat /etc/redhat-release
```
  The output should appear similar to the following example:
```
 Red Hat Enterprise Linux release 10.1 (Coughlan)
```

Update an existing cluster from RHCOS 9 to RHCOS 10

For an existing OpenShift Container Platform cluster 4.21.2 and greater, you can move the nodes in any machine config pool to RHCOS 10 by editing the machine config pool custom resource.

Prerequisites

Enable the TechPreviewNoUpgrade feature set on your cluster by to enable the required Technology Preview features by running the following command:
```
  oc patch featuregate cluster --type merge -p '{"spec":{"featureSet":"TechPreviewNoUpgrade"}}'
```
Replace <installation_directory> with the path to the directory that stores the installation files.

Alternatively, manually edit this file to add the spec.featureSet parameter with the TechPreviewNoUpgrade value as described in Enabling feature sets using the CLI.

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.

Procedure

Update all machine config pools to RHCOS 10 by using the following commands with the name of the machine config pool 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.
1. Update the worker machine config pool to RHCOS 10 by using the following command:
```
 oc patch mcp <mcp-name> --type merge -p '{"spec":{"osImageStream":{"name":"rhel-10"}}}'
```
2. Update the control plane machine config pool to RHCOS 10 by using the following command with the name of the machine config pool to update:
```
 oc patch mcp <mcp-name> --type merge -p '{"spec":{"osImageStream":{"name":"rhel-10"}}}'
```
3. Update any custom machine config pools to RHCOS 10 by using the following command with the name of the machine config pool to update:
```
 oc patch mcp <mcp-name> --type merge -p '{"spec":{"osImageStream":{"name":"rhel-10"}}}'
```
Wait for the pool 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 RHCOS version on the cluster.

Log in to a node by using the following command:
```
     oc debug node/<node_name>
```
Set /host as the root directory within the debug shell by using the following command:
```
     chroot /host
```
Look at the contents of the /etc/redhat-release file by using the following command:
```
     cat /etc/redhat-release
```
The output should appear similar to the following example:
```
     Red Hat Enterprise Linux release 10.1 (Coughlan)
```

Product(s)

Red Hat OpenShift Container Platform

Category

Troubleshoot

Article Type

General