Chapter 6. Boot image management

6.1. About boot image management
링크 복사

With boot image management enabled, the Machine Config Operator (MCO) manages and updates the Red Hat Enterprise Linux CoreOS (RHCOS) version of the boot image in the machine sets for your control plane or worker nodes. This means that the MCO updates the boot image whenever you update your cluster. Without boot image management enabled, if your cluster was originally created with an older OpenShift Container Platform version, the boot image that the MCO would use to create new nodes is an older Red Hat Enterprise Linux CoreOS (RHCOS) version, even if your cluster is at a later OpenShift Container Platform version.

New nodes created after enabling the feature use the updated boot image. This feature has no effect on existing nodes.

Note

The following table lists the platforms on which boot image management is available:

Expand

Platform	Worker machine sets	Control plane machine sets
Google Cloud	Enabled by default	Disabled by default
Amazon Web Services (AWS)	Enabled by default	Disabled by default
Microsoft Azure	Enabled by default	Disabled by default
VMware vSphere	Enabled by default	Not supported

For all other platforms, the MCO does not update the boot image with each cluster update.

For example, with the feature disabled, if your cluster was originally created with OpenShift Container Platform 4.16, the boot image that the MCO would use to create new nodes is the same RHCOS version that was installed for the cluster, even if your cluster is currently at a later OpenShift Container Platform version.

Using an older boot image could cause the following issues:

Extra time to start nodes
Certificate expiration issues
Version skew issues

You can disable the boot image management feature, if needed. When the feature is disabled, the boot image version no longer updates with the cluster. For example, you could disable the boot image management feature in order to use a custom boot image that you do not want changed. For information on how to disable this feature, see "Disabling boot image management". If you disable this feature, you can re-enable the feature at any time. For information, see "Enabling boot image management".

How the cluster behaves after disabling or re-enabling the feature, depends upon when you made the change, including the following scenarios:

If you disable the feature before updating to a new OpenShift Container Platform version:
- The boot image version used by the machine sets remains the same OpenShift Container Platform version as when the feature was disabled.
- When you scale up nodes, the new nodes use that same OpenShift Container Platform version.
If you disable the feature after updating to a new OpenShift Container Platform version:
- The boot image version used by the machine sets is updated to match the updated OpenShift Container Platform version.
- When you scale up nodes, the new nodes use the updated OpenShift Container Platform version.
- If you update to a later OpenShift Container Platform version, the boot image version in the machine sets remains at the current version and is not updated with the cluster.
If you enable the feature after disabling:
- The boot image version used by the machine sets is updated to the current OpenShift Container Platform version, if different.
- When you scale up nodes, the new nodes use the current OpenShift Container Platform version in the cluster.

Note

Because a boot image is used only when a node is scaled up, this feature has no effect on existing nodes.

To view the current Red Hat Enterprise Linux CoreOS (RHCOS) boot image version used in your cluster, you can view the /sysroot/.coreos-aleph-version.json file on that node.

Example coreos-aleph-version.json file with an older boot image

{
# ...
    "ref": "docker://ostree-image-signed:oci-archive:/rhcos-418.94.202511191518-0-ostree.x86_64.ociarchive",
    "version": "418.94.202511191518-0"
}

{
# ...
    "ref": "docker://ostree-image-signed:oci-archive:/rhcos-418.94.202511191518-0-ostree.x86_64.ociarchive",
    "version": "418.94.202511191518-0"
}

Copy to Clipboard

Toggle word wrap

where:

<version>: Specifies the Red Hat Enterprise Linux CoreOS (RHCOS) boot image version. In this example, the boot image is from the originally-installed OpenShift Container Platform 4.18 version, regardless of the current version of the cluster.

Important

If any of the machine sets for which you want to enable boot image management use a *-user-data secret that is based on Ignition version 2.2.0, the Machine Config Operator converts the Ignition version to 3.4.0 when you enable the feature. OpenShift Container Platform versions 4.5 and lower use Ignition version 2.2.0. If this conversion fails, the MCO or your cluster could degrade. An error message that includes err: converting ignition stub failed: failed to parse Ignition config is added to the output of the oc get ClusterOperator machine-config command. You can use the following general steps to correct the problem:

Disable the boot image management feature. For information, see "Disabling boot image management".
Manually update the *-user-data secret to use Ignition version to 3.2.0.
Enable the boot image management feature. For information, see "Enabling boot image management".

6.2. Enabling boot image management
링크 복사

For supported platforms, the Machine Config Operator (MCO) can manage and update the boot image on each node to ensure the Red Hat Enterprise Linux CoreOS (RHCOS) version of the boot image matches the Red Hat Enterprise Linux CoreOS (RHCOS) version appropriate for your cluster.

Note

The following table lists the platforms on which boot image management is available:

Expand

Platform	Worker machine sets	Control plane machine sets
Google Cloud	Enabled by default	Disabled by default
Amazon Web Services (AWS)	Enabled by default	Disabled by default
Microsoft Azure	Enabled by default	Disabled by default
VMware vSphere	Enabled by default	Not supported

For all other platforms, the MCO does not update the boot image with each cluster update.

To enable the boot image management feature for control plane machine sets or to re-enable the boot image management feature for worker machine sets where it was disabled, edit the MachineConfiguration object. You can enable the feature for all of the machine sets in the cluster or specific machine sets.

Note

Because the boot image management feature for worker nodes is default for the Google Cloud and AWS platforms, the managedBootImages configuration does not appear in the machine configuration object. To enable the feature for control plane machine sets without disabling the feature for worker machine sets, you must expressly add the configuration for both the control plane and worker machine sets, as shown in the following procedure. If you add only the configuration for control plane machine sets, due to default behavior, the Machine Config Operator (MCO) overwrites the configuration for the worker machine sets.

Enabling the feature updates the boot image to the Red Hat Enterprise Linux CoreOS (RHCOS) boot image version appropriate for your cluster. If the cluster is again updated to a new OpenShift Container Platform version in the future, the boot image is updated again. New nodes created after enabling the feature use the updated boot image. This feature has no effect on existing nodes.

Prerequisites

If you are enabling boot image management for control plane machine sets, you enabled the required Technology Preview features for your cluster by editing the FeatureGate CR named cluster:
```
oc edit featuregate cluster
```
```
$ oc edit featuregate cluster
```
Copy to Clipboard Toggle word wrap
Example FeatureGate CR
```
apiVersion: config.openshift.io/v1
kind: FeatureGate
metadata:
  name: cluster
spec:
  featureSet: TechPreviewNoUpgrade 
```
```
apiVersion: config.openshift.io/v1
kind: FeatureGate
metadata:
  name: cluster
spec:
  featureSet: TechPreviewNoUpgrade 
```
1
Copy to Clipboard Toggle word wrap
1
Enables the required ManagedBootImagesCPMS feature gate.
Warning
Do not enable this feature set on production clusters. Enabling the TechPreviewNoUpgrade feature set on your cluster cannot be undone and prevents minor version updates. This feature set allows you to enable these Technology Preview features on test clusters, where you can fully test them. Do not enable this feature set on production clusters.

Procedure

Edit the MachineConfiguration object, named cluster, by using the following command:
```
oc edit MachineConfiguration cluster
```
```
$ oc edit MachineConfiguration cluster
```
Copy to Clipboard Toggle word wrap
Enable the boot image management feature for some or all of your machine sets:
- Enable the boot image management feature for all machine sets:
  apiVersion: operator.openshift.io/v1 kind: MachineConfiguration metadata: name: cluster spec: # ... managedBootImages: machineManagers: - apiGroup: machine.openshift.io resource: controlplanemachinesets selection: mode: All - apiGroup: machine.openshift.io resource: machinesets selection: mode: All
  Copy to Clipboard Toggle word wrap
  where:
  spec.managedBootImages
  Configures the boot image management feature.
  spec.managedBootImages.machineManagers.apiGroup
  Specifies the API group. This must be machine.openshift.io.
  spec.managedBootImages.machineManagers.resource
  Specifies the resource within the specified API group to apply the change. Use one or both of the following parameters. You must add the full stanza, as shown, if you want to enable the feature for control plane and worker machine sets.
  controlplanemachinesets: Enables boot image management for control plane machine sets.
  machinesets: Enables boot image management for worker machine sets.
  spec.managedBootImages.machineManagers.selection.mode
  Specifies that the feature is enabled for all machine sets in the cluster.
- Enable the boot image management feature for specific worker machine sets:
  apiVersion: operator.openshift.io/v1 kind: MachineConfiguration metadata: name: cluster spec: # ... managedBootImages: machineManagers: - apiGroup: machine.openshift.io resource: machinesets selection: mode: Partial partial: machineResourceSelector: matchLabels: region: "east"
  Copy to Clipboard Toggle word wrap
  where:
  spec.managedBootImages
  Configures the boot image management feature.
  spec.managedBootImages.machineManagers.apiGroup
  Specifies the API group. This must be machine.openshift.io.
  spec.managedBootImages.machineManagers.resource
  Specifies the resource within the specified API group to apply the change. This must be machinesets. Partial boot image management for control plane machine sets is not supported.
  spec.managedBootImages.machineManagers.selection.mode
  Specifies that the feature is enabled for specific machine sets in the cluster. This must be Partial.
  spec.managedBootImages.machineManagers.selection.partial
  Specifies that the feature is enabled for machine sets with the specified label in their MachineSet object.

Verification

View the current state of the boot image management feature by using the following command to view the machine configuration object:

oc get machineconfiguration cluster -o yaml

$ oc get machineconfiguration cluster -o yaml

Copy to Clipboard

Toggle word wrap

Example machine set with the boot image reference

kind: MachineConfiguration
metadata:
  name: cluster
# ...
status:
  conditions:
  - lastTransitionTime: "2025-05-01T20:11:49Z"
    message: Reconciled 2 of 4 MAPI MachineSets | Reconciled 0 of 0 CAPI MachineSets
      | Reconciled 0 of 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "True"
    type: BootImageUpdateProgressing
  - lastTransitionTime: "2025-05-01T19:30:13Z"
    message: 0 Degraded MAPI MachineSets | 0 Degraded CAPI MachineSets | 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "False"
    type: BootImageUpdateDegraded
  managedBootImagesStatus:
    machineManagers:
    - apiGroup: machine.openshift.io
      resource: controlplanemachinesets
      selection:
        mode: All
    - apiGroup: machine.openshift.io
      resource: machinesets
      selection:
        mode: All

kind: MachineConfiguration
metadata:
  name: cluster
# ...
status:
  conditions:
  - lastTransitionTime: "2025-05-01T20:11:49Z"
    message: Reconciled 2 of 4 MAPI MachineSets | Reconciled 0 of 0 CAPI MachineSets
      | Reconciled 0 of 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "True"
    type: BootImageUpdateProgressing
  - lastTransitionTime: "2025-05-01T19:30:13Z"
    message: 0 Degraded MAPI MachineSets | 0 Degraded CAPI MachineSets | 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "False"
    type: BootImageUpdateDegraded
  managedBootImagesStatus:
    machineManagers:
    - apiGroup: machine.openshift.io
      resource: controlplanemachinesets
      selection:
        mode: All
    - apiGroup: machine.openshift.io
      resource: machinesets
      selection:
        mode: All

Copy to Clipboard

Toggle word wrap

where:

status.managedBootImagesStatus.machineManagers.selection.mode: Specifies that the boot image management feature is enabled when set to All.

Scale a machine set to create a new node by using a command similar to the following. The boot image is updated only for new nodes.

oc scale --replicas=2 machinesets.machine.openshift.io <machineset> -n openshift-machine-api

$ oc scale --replicas=2 machinesets.machine.openshift.io <machineset> -n openshift-machine-api

Copy to Clipboard

Toggle word wrap

If your cluster was using an older boot image version, you can see the new boot image version when the new node reaches the READY state. View the Red Hat Enterprise Linux CoreOS (RHCOS) version on a nodes:
1. Log in to the node by using a command similar to the following:
  $ oc debug node/<node_name>
  Copy to Clipboard Toggle word wrap
2. Set /host as the root directory within the debug shell by using the following command:
  sh-5.1# chroot /host
  Copy to Clipboard Toggle word wrap
3. View the /sysroot/.coreos-aleph-version.json file by using a command similar to the following:
  sh-5.1# cat /sysroot/.coreos-aleph-version.json
  Copy to Clipboard Toggle word wrap
  Example output
  { # ... "ref": "docker://ostree-image-signed:oci-archive:/rhcos-9.6.20251015-1-ostree.x86_64.ociarchive", "version": "9.6.20251015-1" }
  
  Copy to Clipboard Toggle word wrap
  where:
  <version>
  Specifies the boot image version.

6.3. Disabling boot image management
링크 복사

You can disable the boot image management feature so that the Machine Config Operator (MCO) no longer manages or updates the boot image in the affected machine sets. For example, you could disable this feature for the worker nodes in order to use a custom boot image that you do not want changed.

You disable the boot image management feature for the control plane or worker machine sets in your cluster by editing the MachineConfiguration object.

Note

The following table lists the platforms on which boot image management is available:

Expand

Platform	Worker machine sets	Control plane machine sets
Google Cloud	Enabled by default	Disabled by default
Amazon Web Services (AWS)	Enabled by default	Disabled by default
Microsoft Azure	Enabled by default	Disabled by default
VMware vSphere	Enabled by default	Not supported

For all other platforms, the MCO does not update the boot image with each cluster update.

Disabling this feature does not rollback the nodes or machine sets to the originally-installed boot image. The machine sets retain the boot image version that was present when the feature was disabled and is not updated if the cluster is upgraded to a new OpenShift Container Platform version in the future. This feature has no effect on existing nodes.

After disabling the feature, you can re-enable the feature at any time. For more information, see "Enabling updated boot images".

Procedure

Edit the MachineConfiguration object, named cluster, by using the following command::
```
oc edit MachineConfiguration cluster
```
```
$ oc edit MachineConfiguration cluster
```
Copy to Clipboard Toggle word wrap

Disable the feature for some or all of your machine sets:

apiVersion: operator.openshift.io/v1
kind: MachineConfiguration
metadata:
  name: cluster
spec:
# ...
  managedBootImages:
    machineManagers:
    - apiGroup: machine.openshift.io
      resource: machinesets
      selection:
        mode: None
    - apiGroup: machine.openshift.io
      resource: controlplanemachinesets
      selection:
        mode: None

apiVersion: operator.openshift.io/v1
kind: MachineConfiguration
metadata:
  name: cluster
spec:
# ...
  managedBootImages:
    machineManagers:
    - apiGroup: machine.openshift.io
      resource: machinesets
      selection:
        mode: None
    - apiGroup: machine.openshift.io
      resource: controlplanemachinesets
      selection:
        mode: None

Copy to Clipboard

Toggle word wrap

where:

spec.managedBootImages

Configures the boot image management feature.

spec.managedBootImages.machineManagers.selection.mode.None

Specifies that the feature is disabled for all machine sets in the cluster. Set the selection mode to None for one or both of the following resources to disable the feature for that resource.

controlplanemachinesets: Disable boot image management for control plane machine sets.
machinesets: Disables boot image management for worker machine sets.

Verification

View the current state of the boot image management feature by using the following command to view the machine configuration object:

oc get machineconfiguration cluster -o yaml

$ oc get machineconfiguration cluster -o yaml

Copy to Clipboard

Toggle word wrap

Example machine set with the boot image reference

kind: MachineConfiguration
metadata:
  name: cluster
# ...
status:
  conditions:
  - lastTransitionTime: "2025-05-01T20:11:49Z"
    message: Reconciled 2 of 4 MAPI MachineSets | Reconciled 0 of 0 CAPI MachineSets
      | Reconciled 0 of 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "True"
    type: BootImageUpdateProgressing
  - lastTransitionTime: "2025-05-01T19:30:13Z"
    message: 0 Degraded MAPI MachineSets | 0 Degraded CAPI MachineSets | 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "False"
    type: BootImageUpdateDegraded
  managedBootImagesStatus:
    machineManagers:
    - apiGroup: machine.openshift.io
      resource: controlplanemachinesets
      selection:
        mode: None
    - apiGroup: machine.openshift.io
      resource: machinesets
      selection:
        mode: All

kind: MachineConfiguration
metadata:
  name: cluster
# ...
status:
  conditions:
  - lastTransitionTime: "2025-05-01T20:11:49Z"
    message: Reconciled 2 of 4 MAPI MachineSets | Reconciled 0 of 0 CAPI MachineSets
      | Reconciled 0 of 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "True"
    type: BootImageUpdateProgressing
  - lastTransitionTime: "2025-05-01T19:30:13Z"
    message: 0 Degraded MAPI MachineSets | 0 Degraded CAPI MachineSets | 0 CAPI MachineDeployments
    reason: BootImageUpdateConfigurationUpdated
    status: "False"
    type: BootImageUpdateDegraded
  managedBootImagesStatus:
    machineManagers:
    - apiGroup: machine.openshift.io
      resource: controlplanemachinesets
      selection:
        mode: None
    - apiGroup: machine.openshift.io
      resource: machinesets
      selection:
        mode: All

Copy to Clipboard

Toggle word wrap

where:

status.managedBootImagesStatus.machineManagers.selection.mode: Specifies that the boot image management feature is disabled when set to None. In this example, the boot image management feature is disabled for control plane machine sets and enabled for worker machine sets.

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

6.1. About boot image management
링크 복사

6.2. Enabling boot image management
링크 복사

6.3. Disabling boot image management
링크 복사

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat 소개

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

Chapter 6. Boot image management

6.1. About boot image management링크 복사링크가 클립보드에 복사되었습니다!

6.2. Enabling boot image management링크 복사링크가 클립보드에 복사되었습니다!

6.3. Disabling boot image management링크 복사링크가 클립보드에 복사되었습니다!

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat 소개

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

6.1. About boot image management
링크 복사

6.2. Enabling boot image management
링크 복사

6.3. Disabling boot image management
링크 복사