OCDOCS 15797 OCPSTRAT-2182 Updated boot images: Phase 5 (vsphere, Azure TP)

Author: Michael Burke

machine_configuration/mco-update-boot-images.adoc

@@ -6,22 +6,20 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+include::snippets/mco-update-boot-images-abstract.adoc[]
+
 include::snippets/mco-update-boot-images-intro.adoc[]
 
-:FeatureName: Boot image management on {vmw-short}
+:FeatureName: Boot image management for control plane nodes
 include::snippets/technology-preview.adoc[]
 
-[role="_additional-resources"]
-.Additional resources
-* xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features[Enabling features using feature gates]
-
 include::modules/mco-update-boot-images-about.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 * xref:../machine_configuration/mco-update-boot-images.adoc#mco-update-boot-images-disable_machine-configs-configure[Disabling boot image management]
 * xref:../machine_configuration/mco-update-boot-images.adoc#mco-update-boot-images-configuring_machine-configs-configure[Enabling boot image management]
 
-include::modules/mco-update-boot-images-disable.adoc[leveloffset=+1]
-
 include::modules/mco-update-boot-images-configuring.adoc[leveloffset=+1]
+
+include::modules/mco-update-boot-images-disable.adoc[leveloffset=+1]

modules/mco-update-boot-images-about.adoc

@@ -3,31 +3,29 @@
 // * nodes/nodes/nodes-update-boot-images.adoc
 // * machine_configuration/mco-update-boot-images.adoc
 
-:_mod-docs-content-type: PROCEDURE
+:_mod-docs-content-type: CONCEPT
 [id="mco-update-boot-images_{context}"]
 = About boot image management
 
-By default, for {gcp-first} and {aws-first} clusters, the Machine Config Operator (MCO) updates the boot image in the machine sets in your cluster whenever you update your cluster.
+[role="_abstract"]
+With boot image management enabled, the Machine Config Operator (MCO) manages and updates the {op-system-first} 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 {product-title} version, the boot image that the MCO would use to create new nodes is an older {op-system-first} version, even if your cluster is at a later {product-title} version. 
 
-For {vmw-first}, you can enable boot image management as a Technology Preview feature. For information on how to enable this feature, see "Enabling boot image management".
+New nodes created after enabling the feature use the updated boot image. This feature has no effect on existing nodes.
 
-:FeatureName: Boot image management on {vmw-short}
-include::snippets/technology-preview.adoc[]
+[NOTE]
+====
+include::snippets/mco-update-boot-images-intro.adoc[]
+====
 
-You can disable the boot image management feature, if needed. When the feature is disabled, the boot image no longer updates with the cluster. For example, with the feature disabled, if your cluster was originally created with {product-title} 4.16, the boot image that the MCO would use to create nodes is the same 4.16 version, even if your cluster is at a later version.
+For example, with the feature disabled, if your cluster was originally created with {product-title} 4.16, the boot image that the MCO would use to create new nodes is the same {op-system} version that was installed for the cluster, even if your cluster is currently at a later {product-title} version.
 
-However, using an older boot image could cause the following issues:
+Using an older boot image could cause the following issues:
 
 * Extra time to start nodes
 * Certificate expiration issues
 * Version skew issues
 
-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".
-
-[NOTE]
-====
-The ability to configure boot image management is available for only {gcp-short} and {aws-short} clusters. It is not supported for clusters managed by the {cluster-capi-operator}.
-====
+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:
 
@@ -49,78 +47,20 @@ How the cluster behaves after disabling or re-enabling the feature, depends upon
 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 boot image used in your cluster, use one of the following methods, based on your platform:
-
-* For {gcp-short} and {aws-short}, you can examine a machine set.
-+
-[NOTE]
-====
-The location and format of the boot image within the machine set differs, based on the platform. However, the boot image is always listed in the `spec.template.spec.providerSpec.` parameter. 
-====
-+
-.Example {gcp-short} machine set with the boot image reference
+To view the current {op-system-first} 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
 [source,yaml]
 ----
-apiVersion: machine.openshift.io/v1beta1
-kind: MachineSet
-metadata:
-  name: ci-ln-hmy310k-72292-5f87z-worker-a
-  namespace: openshift-machine-api
-spec:
-# ...
-  template:
-# ...
-    spec:
-# ...
-      providerSpec:
-# ...
-        value:
-          disks:
-          - autoDelete: true
-            boot: true
-            image: projects/rhcos-cloud/global/images/rhcos-412-85-202203181601-0-gcp-x86-64 <1>
+{
 # ...
+    "ref": "docker://ostree-image-signed:oci-archive:/rhcos-418.94.202511191518-0-ostree.x86_64.ociarchive",
+    "version": "418.94.202511191518-0"
+}
 ----
-<1> This boot image is the same as the originally-installed {product-title} version, in this example {product-title} 4.12, regardless of the current version of the cluster. The way that the boot image is represented in the machine set depends on the platform, as the structure of the `providerSpec` field differs from platform to platform.
-+
-.Example {aws-short} machine set with the boot image reference
+where:
 
-[source,yaml]
-----
-apiVersion: machine.openshift.io/v1beta1
-kind: MachineSet
-metadata:
-  name: ci-ln-hmy310k-72292-5f87z-worker-a
-  namespace: openshift-machine-api
-spec:
-# ...
-  template:
-# ...
-    spec:
-# ...
-      providerSpec:
-         value:
-          ami:
-            id: ami-0e8fd9094e487d1ff
-# ...
-----
-
-* For {vmw-first}, examine an affected node by opening an `oc debug` session to the node and using the `rpm-ostree status` command.
-+
-[source,terminal]
-----
-sh-5.1# rpm-ostree status
-----
-+
-.Example {aws-short} node with the boot image reference
-+
-----
-State: idle
-Deployments:
-* ostree-unverified-registry:quay.io/my-registry/...
-                   Digest: sha256:...
-----
+`<version>`:: Specifies the {op-system-first} boot image version. In this example, the boot image is from the originally-installed {product-title} 4.18 version, regardless of the current version of the cluster.
 
 // The following admonition is intended to address https://issues.redhat.com/browse//OSDOCS-14592
 [IMPORTANT]