openshift-docs/modules/mco-update-boot-images-configuring.adoc

// Module included in the following assemblies:
//
// * machine-configuration/mco-update-boot-images.adoc
// * nodes/nodes/nodes-update-boot-images.adoc

:_mod-docs-content-type: PROCEDURE
[id="mco-update-boot-images-configuring_{context}"]
= Enabling boot image management

include::snippets/mco-update-boot-images-abstract.adoc[]

[NOTE]
====
include::snippets/mco-update-boot-images-intro.adoc[]
====

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 {gcp-short} and {aws-short} 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 {op-system-first} boot image version appropriate for your cluster. If the cluster is again updated to a new {product-title} 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`:
+
[source,terminal]
----
$ oc edit featuregate cluster
----
+
.Example `FeatureGate` CR
[source,yaml]
----
apiVersion: config.openshift.io/v1
kind: FeatureGate
metadata:
  name: cluster
spec:
  featureSet: TechPreviewNoUpgrade <1>
----
<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:
+
[source,terminal]
----
$ oc edit MachineConfiguration cluster
----

. Enable the boot image management feature for some or all of your machine sets:

* Enable the boot image management feature for all machine sets:
+
[source,yaml]
----
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
----
+
--
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:
+
[source,yaml]
----
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"
----
+
--
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:
+
[source,terminal]
----
$ oc get machineconfiguration cluster -o yaml
----
+
.Example machine set with the boot image reference
+
[source,yaml]
----
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
----
+
--
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.
+
[source,terminal]
----
$ oc scale --replicas=2 machinesets.machine.openshift.io <machineset> -n openshift-machine-api
----

. 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 {op-system-first} version on a nodes:

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

.. Set `/host` as the root directory within the debug shell by using the following command:
+
[source,terminal]
----
sh-5.1# chroot /host
----

.. View the `/sysroot/.coreos-aleph-version.json` file by using a command similar to the following:
+
[source,terminal]
----
sh-5.1# cat /sysroot/.coreos-aleph-version.json
----
+
.Example output
[source,yaml]
----
{
# ...
    "ref": "docker://ostree-image-signed:oci-archive:/rhcos-9.6.20251015-1-ostree.x86_64.ociarchive",
    "version": "9.6.20251015-1"
}
----
where:

`<version>`:: Specifies the boot image version.