MCO-1: MCO Core Configuration and Customization III

Author: Michael Burke

machine_configuration/mco-coreos-layering.adoc

@@ -7,7 +7,9 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-You can extend the functionality of your base {op-system} image by layering additional images onto the base image. This layering does not modify the base {op-system} image. Instead, it creates a _custom layered image_ that includes all {op-system} functionality and adds additional functionality to specific nodes in the cluster.
+You can extend the functionality of your base {op-system} image by layering additional images onto the base image without modifying the base {op-system} image. 
+
+This layering creates a _custom layered image_ that includes all {op-system} functionality and adds additional functionality to specific nodes in the cluster.
 
 // Paragraph taken from Mark Russell draft (6/2/25) blog: https://docs.google.com/document/d/1DMaBg--3ljVlv0jqLJ4KjjFvGRA6J9gmF67Yq37uKdQ/edit?tab=t.0
 Image mode is a cloud-native approach to operating system management that treats your OS like a container image. You define your operating system configuration as code, build it as a unified image, and deploy it consistently across your entire fleet.
@@ -32,9 +34,9 @@ When you apply the custom layered image to your cluster, you assume the responsi
 
 There are three methods for deploying a custom layered image onto your nodes:
 
-{image-mode-os-on-caps}:: With xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on_mco-coreos-layering[{image-mode-os-on-lower}], you create a `MachineOSConfig` object where you include the Containerfile and other parameters. The build is performed on your cluster and the resulting custom layered image is automatically pushed to your repository and applied to the machine config pool that you specified in the `MachineOSConfig` object. The entire process is performed completely within your cluster.
+{image-mode-os-on-caps}:: With {image-mode-os-on-lower}, you create a `MachineOSConfig` object where you include the Containerfile and other parameters. The build is performed on your cluster and the resulting custom layered image is automatically pushed to your repository and applied to the machine config pool that you specified in the `MachineOSConfig` object. The entire process is performed completely within your cluster.
 
-{image-mode-os-out-caps}:: With xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring_mco-coreos-layering[{image-mode-os-out-lower}], you create a Containerfile that references an {product-title} image and the RPM that you want to apply, build the layered image in your own environment, and push the image to your repository. Then, in your cluster, create a `MachineConfig` object for the targeted node pool that points to the new image. The Machine Config Operator overrides the base {op-system} image, as specified by the `osImageURL` value in the associated machine config, and boots the new image.
+{image-mode-os-out-caps}:: With {image-mode-os-out-lower}, you create a Containerfile that references an {product-title} image and the RPM that you want to apply, build the layered image in your own environment, and push the image to your repository. Then, in your cluster, create a `MachineConfig` object for the targeted node pool that points to the new image. The Machine Config Operator overrides the base {op-system} image, as specified by the `osImageURL` value in the associated machine config, and boots the new image.
 
 During {product-title} installation:: You can apply a pre-built custom layered image to specific nodes during {product-title} installation. 
 
@@ -48,14 +50,14 @@ For these methods, use the same base {op-system} image installed on the rest of
 
 {image-mode-os-caps} allows you to use the following types of images to create custom layered images:
 
-* *{product-title} Hotfixes*. You can work with Customer Experience and Engagement (CEE) to obtain and apply link:https://access.redhat.com/solutions/2996001[Hotfix packages] on top of your {op-system} image. In some instances, you might want a bug fix or enhancement before it is included in an official {product-title} release. {image-mode-os-caps} allows you to easily add the Hotfix before it is officially released and remove the Hotfix when the underlying {op-system} image incorporates the fix.
+* *{product-title} Hotfixes*. You can work with Customer Experience and Engagement (CEE) to obtain and apply Hotfix packages on top of your {op-system} image. In some instances, you might want a bug fix or enhancement before it is included in an official {product-title} release. {image-mode-os-caps} allows you to easily add the Hotfix before it is officially released and remove the Hotfix when the underlying {op-system} image incorporates the fix.
 +
 [IMPORTANT]
 ====
 Some Hotfixes require a Red Hat Support Exception and are outside of the normal scope of {product-title} support coverage or life cycle policies.
 ====
 +
-Hotfixes are provided to you based on link:https://access.redhat.com/solutions/2996001[Red Hat Hotfix policy]. Apply it on top of the base image and test that new custom layered image in a non-production environment. When you are satisfied that the custom layered image is safe to use in production, you can roll it out on your own schedule to specific node pools. For any reason, you can easily roll back the custom layered image and return to using the default {op-system}.
+Hotfixes are provided to you based on Red Hat Hotfix policy. Apply it on top of the base image and test that new custom layered image in a non-production environment. When you are satisfied that the custom layered image is safe to use in production, you can roll it out on your own schedule to specific node pools. For any reason, you can easily roll back the custom layered image and return to using the default {op-system}.
 +
 .Example on-cluster Containerfile to apply a Hotfix
 [source,yaml]
@@ -90,7 +92,7 @@ RUN dnf update -y https://example.com/files/systemd-252-46.el9_4.x86_64.rpm \
 ----
 // https://issues.redhat.com/browse/OCPBUGS-42838
 
-* *{op-system-base} packages*. You can download {op-system-base-full} packages from the link:https://access.redhat.com/downloads/content/479/ver=/rhel---9/9.1/x86_64/packages[Red Hat Customer Portal], such as chrony, firewalld, and iputils.
+* *{op-system-base} packages*. You can download {op-system-base-full} packages from the Red Hat Customer Portal, such as chrony, firewalld, and iputils.
 +
 .Example out-of-cluster Containerfile to apply the rsyslog utility
 [source,yaml,subs="attributes+"]
@@ -181,27 +183,10 @@ It is strongly recommended that you test your images outside of your production
 
 include::modules/coreos-layering-configuring-on.adoc[leveloffset=+1]
 
-.Additional resources
-* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-proc_mco-coreos-layering[Using the {image-mode-os-on-lower} to apply a custom layered image]
-* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-remove_mco-coreos-layering[Removing an on-cluster custom layered image]
-* xref:../updating/updating_a_cluster/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools-pause_update-using-custom-machine-config-pools[Pausing the machine config pools]
-* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-rebuild_mco-coreos-layering[Rebuilding an on-cluster custom layered image]
-* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-revert_mco-coreos-layering[Reverting an on-cluster custom layered image]
-* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-modifying_mco-coreos-layering[Modifying a custom layered image]
-* xref:../machine_configuration/index.adoc#checking-mco-node-status_machine-config-overview[About checking machine config node status]
-
 include::modules/coreos-layering-configuring-on-proc.adoc[leveloffset=+2]
 
-.Additional resources
-* xref:../openshift_images/managing_images/using-image-pull-secrets.adoc#images-update-global-pull-secret_using-image-pull-secrets[Updating the global cluster pull secret]
-* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-revert_mco-coreos-layering[Reverting an on-cluster custom layered image]
-* xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features[Enabling features using feature gates]
-
 include::modules/coreos-layering-configuring-on-modifying.adoc[leveloffset=+2]
 
-.Additional resources
-* xref:../updating/updating_a_cluster/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools-pause_update-using-custom-machine-config-pools[Pausing the machine config pools]
-
 ////
 Hiding extensions, not in 4.18. Maybe 4.19?
 include::modules/coreos-layering-configuring-on-extensions.adoc[leveloffset=+2]
@@ -219,15 +204,29 @@ include::modules/coreos-layering-configuring-on-remove.adoc[leveloffset=+2]
 
 include::modules/coreos-layering-configuring.adoc[leveloffset=+1]
 
-.Additional resources
-xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-updating_mco-coreos-layering[Updating with a {op-system} custom layered image]
-
 include::modules/coreos-layering-removing.adoc[leveloffset=+2]
 
 include::modules/coreos-layering-install-time.adoc[leveloffset=+1]
 
 include::modules/coreos-layering-updating.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-proc_mco-coreos-layering[Using the {image-mode-os-on-lower} to apply a custom layered image]
+* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-remove_mco-coreos-layering[Removing an on-cluster custom layered image]
+* xref:../updating/updating_a_cluster/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools-pause_update-using-custom-machine-config-pools[Pausing the machine config pools]
+* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-rebuild_mco-coreos-layering[Rebuilding an on-cluster custom layered image]
+* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-revert_mco-coreos-layering[Reverting an on-cluster custom layered image]
+* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-modifying_mco-coreos-layering[Modifying a custom layered image]
+* xref:../machine_configuration/index.adoc#checking-mco-node-status_machine-config-overview[About checking machine config node status]
+* xref:../openshift_images/managing_images/using-image-pull-secrets.adoc#images-update-global-pull-secret_using-image-pull-secrets[Updating the global cluster pull secret]
+* xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features[Enabling features using feature gates]
+* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-updating_mco-coreos-layering[Updating with a {op-system} custom layered image]
+* link:https://access.redhat.com/solutions/2996001[What is a Hotfix package? (Red{nbsp}Hat Knowledgebase article)]
+* link:https://access.redhat.com/downloads/content/479/ver=/rhel---9/9.1/x86_64/packages[Download Red Hat Enterprise Linux Packages]
+
 ////
 Sources:
 https://docs.google.com/document/d/1Eow2IReNWqnIh5HvCfcKV2MWgHUmFKSnBkt2rH6_V_M/edit

modules/coreos-layering-configuring-on-modifying.adoc

@@ -6,7 +6,10 @@
 [id="coreos-layering-configuring-on-modifying_{context}"]
 = Modifying an on-cluster custom layered image
 
-You can modify an on-cluster custom layered image, as needed. This allows you to install additional packages, remove existing packages, change the pull or push repositories, update secrets, or other similar changes. You can edit the `MachineOSConfig` object, apply changes to the YAML file that created the `MachineOSConfig` object, or create a new YAML file for that purpose.
+[role="_abstract"]
+You can modify an on-cluster custom layered image, as needed, to install additional packages, remove existing packages, change the pull or push repositories, update secrets, or other similar changes. 
+
+You can edit the `MachineOSConfig` object, apply changes to the YAML file that created the `MachineOSConfig` object, or create a new YAML file for that purpose.
 
 If you modify and apply the `MachineOSConfig` object YAML or create a new YAML file, the YAML overwrites any changes you made directly to the `MachineOSConfig` object itself.
 
@@ -33,7 +36,7 @@ spec:
     name: layered-image
   containerFile:
   - containerfileArch: noarch
-    content: |- <1>
+    content: |-
       FROM configs AS final
 
       RUN rpm-ostree install rng-tools && \
@@ -46,15 +49,20 @@ spec:
   imageBuilder:
     imageBuilderType: PodImageBuilder
   baseImagePullSecret:
-    name: global-pull-secret-copy <2>
-  renderedImagePushspec: image-registry.openshift-image-registry.svc:5000/openshift-machine-config-operator/os-images:latest <3>
-  renderedImagePushSecret:  <4>
+    name: global-pull-secret-copy
+  renderedImagePushspec: image-registry.openshift-image-registry.svc:5000/openshift-machine-config-operator/os-images:latest
+  renderedImagePushSecret:
     name: new-secret-name
 ----
-<1> Optional: Modify the Containerfile, for example to add or remove packages.
-<2> Optional: Update the secret needed to pull the base operating system image from the registry.
-<3> Optional: Modify the image registry to push the newly built custom layered image to.
-<4> Optional: Update the secret needed to push the newly built custom layered image to the registry.
++
+where:
++
+--
+`spec:containerFile.content`::  Modify the Containerfile, for example to add or remove packages. This parameter is optional.
+`spec.baseImagePullSecret`:: Update the secret needed to pull the base operating system image from the registry. This parameter is optional.
+`spec.renderedImagePushspec`:: Modify the image registry to push the newly built custom layered image to. This parameter is optional.
+`spec.renderedImagePushSecret`:: Update the secret needed to push the newly built custom layered image to the registry. This parameter is optional.
+--
 +
 When you save the changes, the MCO drains, cordons, and reboots the nodes. After the reboot, the node uses the cluster base {op-system-first} image. If your changes modify a secret only, no new build is triggered and no reboot is performed.
 
@@ -72,9 +80,10 @@ $ oc get machineosbuild
 ----
 NAME                                             PREPARED   BUILDING   SUCCEEDED   INTERRUPTED   FAILED   AGE
 layered-image-a5457b883f5239cdcb71b57e1a30b6ef   False      False      True        False         False    4d17h
-layered-image-f91f0f5593dd337d89bf4d38c877590b   False      True       False       False         False    2m41s <1>
+layered-image-f91f0f5593dd337d89bf4d38c877590b   False      True       False       False         False    2m41s
 ----
-<1> The value `True` in the `BUILDING` column indicates that the `MachineOSBuild` object is building. When the `SUCCEEDED` column reports `True`, the build is complete.
++
+The value `True` in the `BUILDING` column indicates that the `MachineOSBuild` object is building. When the `SUCCEEDED` column reports `True`, the build is complete.
 
 . You can watch as the new machine config is rolled out to the nodes by using the following command:
 +
@@ -88,9 +97,10 @@ $ oc get machineconfigpools
 ----
 NAME      CONFIG                                              UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
 master    rendered-master-a0b404d061a6183cc36d302363422aba    True      False      False      3              3                   3                     0                      3h38m
-worker    rendered-worker-221507009cbcdec0eec8ab3ccd789d18    False     True       False      2              2                   2                     0                      3h38m <1>
+worker    rendered-worker-221507009cbcdec0eec8ab3ccd789d18    False     True       False      2              2                   2                     0                      3h38m
 ----
-<1> The value `FALSE` in the `UPDATED` column indicates that the `MachineOSBuild` object is building. When the `UPDATED` column reports `FALSE`, the new custom layered image has rolled out to the nodes.
++
+The value `FALSE` in the `UPDATED` column indicates that the `MachineOSBuild` object is building. When the `UPDATED` column reports `FALSE`, the new custom layered image has rolled out to the nodes.
 
 . When the node is back in the `Ready` state, check that the changes were applied: