You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: machine_configuration/mco-coreos-layering.adoc
+14-11Lines changed: 14 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,25 @@
1
1
:_mod-docs-content-type: ASSEMBLY
2
2
include::_attributes/common-attributes.adoc[]
3
3
[id="mco-coreos-layering"]
4
-
= {op-system} image layering
4
+
= Image mode for OpenShift
5
5
:context: mco-coreos-layering
6
6
7
7
toc::[]
8
8
9
9
10
-
{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.
10
+
{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.
11
+
12
+
// Paragraph taken from Mark Russell draft (6/2/25) blog: https://docs.google.com/document/d/1DMaBg--3ljVlv0jqLJ4KjjFvGRA6J9gmF67Yq37uKdQ/edit?tab=t.0
13
+
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.
11
14
12
15
[id="coreos-layering-about_{context}"]
13
-
== About {op-system} image layering
16
+
== About {image-mode-os-lower}
14
17
15
-
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.
18
+
{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.
16
19
17
20
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.
18
21
19
-
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.
22
+
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.
20
23
21
24
// NOTE from https://issues.redhat.com/browse/OCPBUGS-2214?focusedCommentId=21430101&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-21430101
22
25
@@ -29,9 +32,9 @@ As soon as you apply the custom layered image to your cluster, you effectively _
29
32
30
33
There are two methods for deploying a custom layered image onto your nodes:
31
34
32
-
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.
35
+
{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.
33
36
34
-
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.
37
+
{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.
35
38
36
39
[IMPORTANT]
37
40
====
@@ -41,9 +44,9 @@ For both methods, use the same base {op-system} image installed on the rest of y
41
44
[id="coreos-layering-examples_{context}"]
42
45
== Example Containerfiles
43
46
44
-
{op-system} image layering allows you to use the following types of images to create custom layered images:
47
+
{image-mode-os-caps} allows you to use the following types of images to create custom layered images:
45
48
46
-
* *{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.
49
+
* *{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.
47
50
+
48
51
[IMPORTANT]
49
52
====
@@ -177,16 +180,16 @@ It is strongly recommended that you test your images outside of your production
* 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]
183
+
* 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]
181
184
* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-remove_mco-coreos-layering[Removing an on-cluster custom layered image]
182
185
* 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]
183
186
* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-rebuild_mco-coreos-layering[Rebuilding an on-cluster custom layered image]
184
187
* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-revert_mco-coreos-layering[Reverting an on-cluster custom layered image]
185
188
* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-modifying_mco-coreos-layering[Modifying a custom layered image]
* 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]
191
194
* xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-configuring-on-revert_mco-coreos-layering[Reverting 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.
= Using on-cluster layering to apply a custom layered image
7
+
= Using the {image-mode-os-on-lower} to apply a custom layered image
8
8
9
9
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:
10
10
@@ -61,7 +61,7 @@ spec:
61
61
name: builder-dockercfg-mtcl23
62
62
----
63
63
<1> Specifies the `machineconfiguration.openshift.io/v1` API that is required for `MachineConfig` CRs.
64
-
<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`.
64
+
<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`.
65
65
<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.
66
66
<4> Specifies the Containerfile to configure the custom layered image.
67
67
<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.
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.
9
+
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.
10
10
11
11
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.
12
12
13
13
.Prerequisites
14
14
15
-
* You have opted-in to on-cluster layering by creating a `MachineOSConfig` object.
15
+
* You have opted-in to {image-mode-os-on-lower} by creating a `MachineOSConfig` object.
Copy file name to clipboardExpand all lines: modules/coreos-layering-configuring-on.adoc
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,9 @@
4
4
5
5
:_mod-docs-content-type: CONCEPT
6
6
[id="coreos-layering-configuring-on_{context}"]
7
-
= About on-cluster layering
7
+
= About {image-mode-os-on-lower}
8
8
9
-
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".
9
+
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".
10
10
11
11
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, `<MachineOSConfig_CR_name>-<hash>`, for example:
12
12
@@ -75,11 +75,11 @@ You can modify an on-custom layered image as needed, to install additional packa
Note the following limitations when working with the on-cluster layering feature:
81
81
82
-
* On-cluster layering is not supported on multi-architecture compute machines.
82
+
* {image-mode-os-on-caps} is not supported on multi-architecture compute machines.
83
83
* 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.
84
84
* 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.
85
85
* Node disruption policies are not supported on nodes with a custom layered image. As a result the following configuration changes cause a node reboot:
Copy file name to clipboardExpand all lines: modules/coreos-layering-configuring.adoc
+4-2Lines changed: 4 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,11 @@
4
4
5
5
:_mod-docs-content-type: PROCEDURE
6
6
[id="coreos-layering-configuring_{context}"]
7
-
= Using out-of-cluster layering to apply a custom layered image
7
+
= Using {image-mode-os-out-caps} to apply a custom layered image
8
8
9
-
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.
9
+
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).
10
+
11
+
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.
10
12
11
13
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.
0 commit comments