diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 1643f59c65..3a81361f9c 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2306,12 +2306,9 @@ Topics: File: mco-update-boot-images - Name: Managing unused rendered machine configs File: machine-configs-garbage-collection -- Name: Red Hat Enterprise Linux (RHEL) CoreOS image layering +- Name: Image mode for OpenShift File: mco-coreos-layering - Distros: openshift-enterprise -- Name: Fedora CoreOS image layering - File: mco-coreos-layering - Distros: openshift-origin + Distros: openshift-enterprise,openshift-origin - Name: Machine Config Daemon metrics File: machine-config-daemon-metrics --- diff --git a/machine_configuration/mco-coreos-layering.adoc b/machine_configuration/mco-coreos-layering.adoc index ab41cb0b97..072708ff4a 100644 --- a/machine_configuration/mco-coreos-layering.adoc +++ b/machine_configuration/mco-coreos-layering.adoc @@ -1,22 +1,25 @@ :_mod-docs-content-type: ASSEMBLY include::_attributes/common-attributes.adoc[] [id="mco-coreos-layering"] -= {op-system} image layering += Image mode for OpenShift :context: mco-coreos-layering toc::[] -{op-system-first} image layering allows you to easily 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. +{image-mode-os-caps} allows you to easily 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. + +// 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. [id="coreos-layering-about_{context}"] -== About {op-system} image layering +== About {image-mode-os-lower} -Image layering allows you to customize the underlying node operating system on any of your cluster nodes. This helps keep everything up-to-date, including the node operating system and any added customizations such as specialized software. +{image-mode-os-caps} allows you to customize the underlying node operating system on any of your cluster nodes. This helps keep everything up-to-date, including the node operating system and any added customizations such as specialized software. You create a custom layered image by using a Containerfile and applying it to nodes by using a custom object. At any time, you can remove the custom layered image by deleting that custom object. -With {op-system} image layering, you can install RPMs into your base image, and your custom content will be booted alongside {op-system}. The Machine Config Operator (MCO) can roll out these custom layered images and monitor these custom containers in the same way it does for the default {op-system} image. {op-system} image layering gives you greater flexibility in how you manage your {op-system} nodes. +With {image-mode-os-lower}, you can install RPMs into your base image, and your custom content will be booted alongside {op-system}. The Machine Config Operator (MCO) can roll out these custom layered images and monitor these custom containers in the same way it does for the default {op-system} image. {image-mode-os-caps} gives you greater flexibility in how you manage your {op-system} nodes. // NOTE from https://issues.redhat.com/browse/OCPBUGS-2214?focusedCommentId=21430101&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-21430101 @@ -29,9 +32,9 @@ As soon as you apply the custom layered image to your cluster, you effectively _ There are two methods for deploying a custom layered image onto your nodes: -On-cluster layering:: With xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on_mco-coreos-layering[on-cluster layering], 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 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. -Out-of-cluster layering:: With xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring_mco-coreos-layering[out-of-cluster layering], 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 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. [IMPORTANT] ==== @@ -41,9 +44,9 @@ For both methods, use the same base {op-system} image installed on the rest of y [id="coreos-layering-examples_{context}"] == Example Containerfiles -{op-system} image layering allows you to use the following types of images to create custom layered images: +{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. {op-system} image layering 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 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. + [IMPORTANT] ==== @@ -177,16 +180,16 @@ 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 on-cluster layering to apply a custom layered image] +* 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] -.Additional resources 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] diff --git a/modules/coreos-layering-configuring-on-extensions.adoc b/modules/coreos-layering-configuring-on-extensions.adoc index 41fab05636..b36b7a64b1 100644 --- a/modules/coreos-layering-configuring-on-extensions.adoc +++ b/modules/coreos-layering-configuring-on-extensions.adoc @@ -19,7 +19,7 @@ include::snippets/coreos-layering-configuring-on-pause.adoc[] .Prerequisites -* You have opted in to on-cluster layering by creating a `MachineOSConfig` object. +* You have opted in to {image-mode-os-on-caps} by creating a `MachineOSConfig` object. .Procedure diff --git a/modules/coreos-layering-configuring-on-modifying.adoc b/modules/coreos-layering-configuring-on-modifying.adoc index d940350351..7cae9583ed 100644 --- a/modules/coreos-layering-configuring-on-modifying.adoc +++ b/modules/coreos-layering-configuring-on-modifying.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="coreos-layering-configuring-on-modifying_{context}"] -= Modifying a custom layered image += 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. @@ -14,7 +14,7 @@ include::snippets//coreos-layering-configuring-on-pause.adoc[] .Prerequisites -* You have opted in to on-cluster layering by creating a `MachineOSConfig` object. +* You have opted in to {image-mode-os-on-lower} by creating a `MachineOSConfig` object. .Procedure diff --git a/modules/coreos-layering-configuring-on-proc.adoc b/modules/coreos-layering-configuring-on-proc.adoc index be00184371..3819e87058 100644 --- a/modules/coreos-layering-configuring-on-proc.adoc +++ b/modules/coreos-layering-configuring-on-proc.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="coreos-layering-configuring-on-proc_{context}"] -= Using on-cluster layering to apply a custom layered image += Using the {image-mode-os-on-lower} to apply a custom layered image To apply a custom layered image to your cluster by using the on-cluster build process, create a `MachineOSConfig` custom resource (CR) that specifies the following parameters: @@ -61,7 +61,7 @@ spec: name: builder-dockercfg-mtcl23 ---- <1> Specifies the `machineconfiguration.openshift.io/v1` API that is required for `MachineConfig` CRs. -<2> Specifies a name for the `MachineOSConfig` object. This name is used with other on-cluster layering resources. The examples in this documentation use the name `layered-image`. +<2> Specifies a name for the `MachineOSConfig` object. This name is used with other [image-mode-os-on-lower] resources. The examples in this documentation use the name `layered-image`. <3> Specifies the name of the machine config pool associated with the nodes where you want to deploy the custom layered image. The examples in this documentation use the `layered` machine config pool. <4> Specifies the Containerfile to configure the custom layered image. <5> Specifies the architecture this containerfile is to be built for: `ARM64`, `AMD64`, `PPC64LE`, `S390X`, or `NoArch`. The default is `NoArch`, which defines a Containerfile that can be applied to any architecture. diff --git a/modules/coreos-layering-configuring-on-rebuild.adoc b/modules/coreos-layering-configuring-on-rebuild.adoc index 379bba9664..d7c5e6943e 100644 --- a/modules/coreos-layering-configuring-on-rebuild.adoc +++ b/modules/coreos-layering-configuring-on-rebuild.adoc @@ -6,13 +6,13 @@ [id="coreos-layering-configuring-on-rebuild_{context}"] = Rebuilding an on-cluster custom layered image -In situations where you want to rebuild a custom layered image, you can either modify your `MachineOSConfig` object or add an annotation to the `MachineOSConfig` object. Both of these actions trigger an automatic rebuild of the object. For example, you could perform a rebuild if the you change the Containerfile or need to update the `osimageurl` location in a machine config. +In situations where you want to rebuild an on-cluster custom layered image, you can either modify your `MachineOSConfig` object or add an annotation to the `MachineOSConfig` object. Both of these actions trigger an automatic rebuild of the object. For example, you could perform a rebuild if the you change the Containerfile or need to update the `osimageurl` location in a machine config. After you add the annotation, the Machine Config Operator (MCO) deletes the current `MachineOSBuild` object and creates a new one in its place. When the build process is complete, the MCO automatically removes the annotation. .Prerequisites -* You have opted-in to on-cluster layering by creating a `MachineOSConfig` object. +* You have opted-in to {image-mode-os-on-lower} by creating a `MachineOSConfig` object. .Procedure diff --git a/modules/coreos-layering-configuring-on-revert.adoc b/modules/coreos-layering-configuring-on-revert.adoc index f2213115b2..b43e739fb6 100644 --- a/modules/coreos-layering-configuring-on-revert.adoc +++ b/modules/coreos-layering-configuring-on-revert.adoc @@ -17,7 +17,7 @@ Before you remove the label, make sure the node is associated with another MCP. .Prerequisites -* You have opted-in to on-cluster layering by creating a `MachineOSConfig` object. +* You have opted-in to {image-mode-os-on-caps} by creating a `MachineOSConfig` object. * You have applied a `MachineOSConfig` object to a node in a custom machine config pool. .Procedure diff --git a/modules/coreos-layering-configuring-on.adoc b/modules/coreos-layering-configuring-on.adoc index 86889eabbe..1f9c291d20 100644 --- a/modules/coreos-layering-configuring-on.adoc +++ b/modules/coreos-layering-configuring-on.adoc @@ -4,9 +4,9 @@ :_mod-docs-content-type: CONCEPT [id="coreos-layering-configuring-on_{context}"] -= About on-cluster layering += About {image-mode-os-on-lower} -You can use the on-cluster build process to apply a custom layered image to your nodes by creating a `MachineOSConfig` custom resource (CR), as described in "Using on-cluster layering to apply a custom layered image". +You can use the {image-mode-os-lower} on-cluster build process to apply a custom layered image to your nodes by creating a `MachineOSConfig` custom resource (CR), as described in "Using {image-mode-os-on-caps} to apply a custom layered image". When you create the object, the Machine Config Operator (MCO) creates a `MachineOSBuild` object and a builder pod. The process also creates transient objects, such as config maps, which are cleaned up after the build is complete. The `MachineOSBuild` object and the associated `builder-*` pod use the same naming scheme, `-`, for example: @@ -75,11 +75,11 @@ You can modify an on-custom layered image as needed, to install additional packa [discrete] [id="coreos-layering-configuring-on-limitations_{context}"] -== On-cluster layering known limitations +== {image-mode-os-on-caps} known limitations Note the following limitations when working with the on-cluster layering feature: -* On-cluster layering is not supported on multi-architecture compute machines. +* {image-mode-os-on-caps} is not supported on multi-architecture compute machines. * Using multiple `MachineOSConfig` objects on the same machine config pool is not supported. You need a separate `MachineOSConfig` CR for each machine config pool where you want to use a distinct custom layered image. * If you scale up a machine set that uses a custom layered image, the nodes reboot two times. The first, when the node is initially created with the base image and a second time when the custom layered image is applied. * Node disruption policies are not supported on nodes with a custom layered image. As a result the following configuration changes cause a node reboot: diff --git a/modules/coreos-layering-configuring.adoc b/modules/coreos-layering-configuring.adoc index 8e11a8f73c..727f3c3906 100644 --- a/modules/coreos-layering-configuring.adoc +++ b/modules/coreos-layering-configuring.adoc @@ -4,9 +4,11 @@ :_mod-docs-content-type: PROCEDURE [id="coreos-layering-configuring_{context}"] -= Using out-of-cluster layering to apply a custom layered image += Using {image-mode-os-out-caps} to apply a custom layered image -You can easily configure {op-system-first} image layering on the nodes in specific machine config pools. The Machine Config Operator (MCO) reboots those nodes with the new custom layered image, overriding the base {op-system-first} image. +You can use the {image-mode-os-lower} out-of-cluster build process to apply a custom layered image to your nodes by creating a `MachineOSConfig` custom resource (CR). + +When you create the object, the Machine Config Operator (MCO) reboots those nodes with the new custom layered image, overriding the base {op-system-first} image. To apply a custom layered image to your cluster, you must have the custom layered image in a repository that your cluster can access. Then, create a `MachineConfig` object that points to the custom layered image. You need a separate `MachineConfig` object for each machine config pool that you want to configure. diff --git a/modules/coreos-layering-updating.adoc b/modules/coreos-layering-updating.adoc index 739352ab58..949623a7a5 100644 --- a/modules/coreos-layering-updating.adoc +++ b/modules/coreos-layering-updating.adoc @@ -6,7 +6,7 @@ [id="coreos-layering-updating_{context}"] = Updating with a {op-system} custom layered image -When you configure {op-system-first} image layering, {product-title} no longer automatically updates the node pool that uses the custom layered image. You become responsible to manually update your nodes as appropriate. +When you configure {image-mode-os-lower}, {product-title} no longer automatically updates the node pool that uses the custom layered image. You become responsible to manually update your nodes as appropriate. To update a node that uses a custom layered image, follow these general steps: diff --git a/rosa_architecture/index.adoc b/rosa_architecture/index.adoc index c3dbeddefe..888d91aeae 100644 --- a/rosa_architecture/index.adoc +++ b/rosa_architecture/index.adoc @@ -155,7 +155,7 @@ xref:../installing/installing_ibm_cloud/preparing-to-install-on-ibm-cloud.adoc#p - **xref:../storage/persistent_storage/persistent-storage-ocs.adoc#red-hat-openshift-data-foundation[Install Red Hat OpenShift Data Foundation]**: You can install {rh-storage-first} as an Operator to provide highly integrated and simplified persistent storage management for containers. -- **xref:../machine_configuration/mco-coreos-layering.adoc#mco-coreos-layering[{op-system-first} image layering]**: As a post-installation task, you can add new images on top of the base {op-system} image. This layering does not modify the base {op-system} image. Instead, the layering creates a custom layered image that includes all {op-system} functions and adds additional functions to specific nodes in the cluster. +- **xref:../machine_configuration/mco-coreos-layering.adoc#mco-coreos-layering[{image-mode-os-lower}]**: As a post-installation task, you can add new images on top of the base {op-system} image. This layering does not modify the base {op-system} image. Instead, the layering creates a custom layered image that includes all {op-system} functions and adds additional functions to specific nodes in the cluster. endif::[] ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated,openshift-dpu,microshift[] diff --git a/welcome/learn_more_about_openshift.adoc b/welcome/learn_more_about_openshift.adoc index 7504c40243..7ec2bfc75a 100644 --- a/welcome/learn_more_about_openshift.adoc +++ b/welcome/learn_more_about_openshift.adoc @@ -77,7 +77,7 @@ Explore the following {product-title} installation tasks: | xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#validating-an-installation[Validating an installation] | xref:../storage/persistent_storage/persistent-storage-ocs.adoc#red-hat-openshift-data-foundation[Install {rh-storage-first}] -| xref:../machine_configuration/mco-coreos-layering.adoc#mco-coreos-layering[{op-system-first} image layering] +| xref:../machine_configuration/mco-coreos-layering.adoc#mco-coreos-layering[{image-mode-os-lower}] |===