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
<1> Optional: Modify the Containerfile, for example to add or remove packages.
59
50
<2> Optional: Update the secret needed to pull the base operating system image from the registry.
60
51
<3> Optional: Modify the image registry to push the newly built custom layered image to.
61
52
<4> Optional: Update the secret needed to push the newly built custom layered image to the registry.
62
-
<5> Optional: Update the secret needed to pull the newly built custom layered image from the registry.
63
53
+
64
54
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.
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
+
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
+
13
+
.Prerequisites
14
+
15
+
* You have opted-in to {image-mode-os-on-lower} by creating a `MachineOSConfig` object.
16
+
17
+
.Procedure
18
+
19
+
* Edit the `MachineOSConfig` object to add the `machineconfiguration.openshift.io/rebuild` annotation by using the following command:
<1> The value `True` in the `BUILDING` column indicates that the `MachineOSBuild` object is building.
58
+
59
+
* Edit the `MachineOSConfig` object to verify that the MCO removed the `machineconfiguration.openshift.io/rebuild` annotation by using the following command:
To prevent the custom layered images from taking up excessive space in your registry, you can automatically remove an on-cluster custom layered image from the repository by deleting the `MachineOSBuild` object that created the image.
10
+
11
+
The credentials provided by the registry push secret that you added to the `MachineOSBuild` object must grant the permission for deleting an image from the registry. If the delete permission is not provided, the image is not removed when you delete the `MachineOSBuild` object.
12
+
13
+
Note that the custom layered image is not deleted if the image is either currently in use on a node or is desired by the nodes, as indicated by the `machineconfiguration.openshift.io/currentConfig` or `machineconfiguration.openshift.io/desiredConfig` annotation on the node.
In the case of a build failure, for example due to network issues or an invalid secret, the MCO retries the build three additional times before the job fails. The MCO creates a different build pod for each build attempt. You can use the build pod logs to troubleshoot any build failures. However, the MCO automatically removes these build pods after a short period of time.
@@ -53,30 +51,31 @@ NAME PREPARED BUILDING SUCCEEDED INT
// You can manually rebuild your custom layered image by either modifying your `MachineOSConfig` object or applying an annotation to the `MachineOSConfig` object as discussed in the following section.
54
+
You can manually rebuild your custom layered image by either modifying your `MachineOSConfig` object or applying an annotation to the `MachineOSConfig` object as discussed in the following section. For more information, see "Rebuilding an on-cluster custom layered image".
55
+
56
+
If you used a custom machine config pool to apply an on-cluster layered image to a node, you can remove the custom layered image from the node and revert to the base image. For more information, see "Reverting an on-cluster layered node".
57
+
58
+
You can modify an on-custom layered image as needed, to install additional packages, remove existing packages, change repositories, update secrets, or other similar changes, by editing the MachineOSConfig object. For more information, see "Modifying a custom layered image".
== On-cluster layering Technology Preview known limitations
62
+
== On-cluster layering known limitations
62
63
63
64
Note the following limitations when working with the on-cluster layering feature:
64
65
65
66
* On-cluster layering is supported only for {product-title} clusters on the AMD64 architecture.
66
-
* On-cluster layering is not supported on multi-architecture compute machines, {sno}, or disconnected clusters.
67
+
* On-cluster layering is not supported on multi-architecture compute machines, or {sno} clusters.
67
68
* 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.
68
69
* Node disruption policies are not supported on nodes with a custom layered image. As a result the following configuration changes cause a node reboot:
69
70
** Modifying the configuration files in the `/var` or `/etc` directory
70
71
** Adding or modifying a systemd service
71
72
** Changing SSH keys
72
73
** Removing mirroring rules from `ICSP`, `ITMS`, and `IDMS` objects
73
74
** Changing the trusted CA, by updating the `user-ca-bundle` configmap in the `openshift-config` namespace
74
-
* The images used in creating custom layered images take up space in your push registry. Always be aware of the free space in your registry and prune the images as needed.
75
+
* The images used in creating custom layered images take up space in your push registry. Always be aware of the free space in your registry and prune the images as needed. You can automatically remove an on-cluster custom layered image from the repository by deleting the MachineOSBuild object that created the image. Note that the credentials provided by the registry push secret must also grant permission to delete an image from the registry. For more information, see "Removing an on-cluster custom layered image".
75
76
76
77
.Prerequisites
77
78
78
-
* You have enabled the `TechPreviewNoUpgrade` feature set by using the feature gates. For more information, see "Enabling features using feature gates".
79
-
80
79
* You have a copy of the pull secret in the `openshift-machine-config-operator` namespace that the MCO needs to pull the base operating system image.
81
80
+
82
81
For example, if you are using the global pull secret, you can run the following command:
* You are familiar with how to configure a Containerfile. Instructions on how to create a Containerfile are beyond the scope of this documentation.
100
99
101
-
* Optional: You have a separate machine config pool for the nodes where you want to apply the custom layered image.
100
+
* Optional: You have a separate machine config pool for the nodes where you want to apply the custom layered image. One benefit to having a custom machine config pool for the nodes it that you can easily revert to the base image, if needed. For more information, see "Reverting an on-cluster layered node".
<1> Specifies the `machineconfiguration.openshift.io/v1` API that is required for `MachineConfig` CRs.
137
-
<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`.
138
-
<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 `worker` machine config pool.
133
+
<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`.
134
+
<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.
139
135
<4> Specifies the Containerfile to configure the custom layered image.
140
-
<5> Specifies the name of the image builder to use. This must be `PodImageBuilder`.
141
-
<6> Specifies the name of the pull secret that the MCO needs in order to pull the base operating system image from the registry.
142
-
<7> Specifies the image registry to push the newly built custom layered image to. This can be any registry that your cluster has access to. This example uses the internal {product-title} registry.
143
-
<8> Specifies the name of the push secret that the MCO needs in order to push the newly built custom layered image to that registry.
144
-
<9> Specifies the secret required by the image registry that the nodes need in order to pull the newly built custom layered image. This should be a different secret than the one used to push the image to your repository.
145
-
// +
146
-
// https://github.com/openshift/openshift-docs/pull/87486/files has the v1 api versions
136
+
<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.
137
+
<6> Specifies the name of the image builder to use. This must be `Job`, which is a reference to the `job` object that is managing the image build.
138
+
<7> Optional: Specifies the name of the pull secret that the MCO needs to pull the base operating system image from the registry. By default, the global pull secret is used.
139
+
<8> Specifies the image registry to push the newly-built custom layered image to. This can be any registry that your cluster has access to in the `host[:port][/namespace]/name` or `svc_name.namespace.svc[:port]/repository/name:<tag>` format. This example uses the internal {product-title} registry. You can specify a mirror registry if you cluster is properly configured to use a mirror registry.
140
+
<9> Specifies the name of the push secret that the MCO needs to push the newly-built custom layered image to that registry.
0 commit comments