Backport OCL to 4.18 #96116
+146
−67
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * machine_configuration/coreos-layering.adoc | ||
|
|
||
| :_mod-docs-content-type: PROCEDURE | ||
| [id="coreos-layering-configuring-on-rebuild_{context}"] | ||
| = Rebuilding an on-cluster custom layered image | ||
|
|
||
| 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 {image-mode-os-on-lower} by creating a `MachineOSConfig` object. | ||
| .Procedure | ||
|
|
||
| * Edit the `MachineOSConfig` object to add the `machineconfiguration.openshift.io/rebuild` annotation by using the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc edit MachineOSConfig <object_name> | ||
| ---- | ||
| + | ||
| .Example `MachineOSConfig` object | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: machineconfiguration.openshift.io/v1 | ||
| kind: MachineOSConfig | ||
| metadata: | ||
| annotations: | ||
| machineconfiguration.openshift.io/current-machine-os-build: layering-c26d4a003432df70ee66c83981144cfa | ||
| machineconfiguration.openshift.io/rebuild: "" <1> | ||
| # ... | ||
| name: layered | ||
| # ... | ||
| ---- | ||
| <1> Add this annotation to trigger a rebuild of the custom layered image. | ||
| .Verification | ||
|
|
||
| * Check that the `MachineOSBuild` object is building by using the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc get machineosbuild | ||
| ---- | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| NAME PREPARED BUILDING SUCCEEDED INTERRUPTED FAILED AGE | ||
| layered-d6b929a29c6dbfa8e4007c8069a2fd08 False True False False False 2m41s <1> | ||
| ---- | ||
| <1> The value `True` in the `BUILDING` column indicates that the `MachineOSBuild` object is building. | ||
| * Edit the `MachineOSConfig` object to verify that the MCO removed the `machineconfiguration.openshift.io/rebuild` annotation by using the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc edit MachineOSConfig <object_name> | ||
| ---- | ||
| + | ||
| .Example `MachineOSConfig` object | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: machineconfiguration.openshift.io/v1 | ||
| kind: MachineOSConfig | ||
| metadata: | ||
| annotations: | ||
| machineconfiguration.openshift.io/current-machine-os-build: layering-c26d4a003432df70ee66c83981144cfa | ||
| # ... | ||
| name: layered | ||
| # ... | ||
| ---- | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| // Module included in the following assemblies: | ||
|
There was a problem hiding this comment. PEER REVIEW This file I copied directly from main (and 4.19). No need for review here. |
||
| // | ||
| // * machine_configuration/coreos-layering.adoc | ||
|
|
||
| :_mod-docs-content-type: PROCEDURE | ||
| [id="coreos-layering-configuring-on-remove_{context}"] | ||
| = Removing an on-cluster custom layered image | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| 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/currentImage` or `machineconfiguration.openshift.io/desiredImage` annotation on the node. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -40,8 +40,6 @@ You should not need to interact with these new objects or the `machine-os-builde | |
|
|
||
| You need a separate `MachineOSConfig` CR for each machine config pool where you want to use a custom layered image. | ||
|
|
||
| include::snippets//coreos-layering-configuring-on-pause.adoc[] | ||
|
|
||
| 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 | |
| layered-c8765e26ebc87e1e17a7d6e0a78e8bae False False False False True | ||
| ---- | ||
|
|
||
| You can manually rebuild your custom layered image by either modifying your `MachineOSConfig` object or applying an annotation to the `MachineOSConfig` object. For more information, see "Rebuilding an on-cluster custom layered image". | ||
|
|
||
| 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". | ||
|
|
||
| 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". | ||
|
|
||
| [discrete] | ||
| [id="coreos-layering-configuring-on-limitations_{context}"] | ||
| == On-cluster layering known limitations | ||
|
|
||
| Note the following limitations when working with the on-cluster layering feature: | ||
|
|
||
| * On-cluster layering is supported only for {product-title} clusters on the AMD64 architecture. | ||
| * On-cluster layering is not supported on multi-architecture compute machines, or {sno} clusters. | ||
| * 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: | ||
| ** Modifying the configuration files in the `/var` or `/etc` directory | ||
| ** Adding or modifying a systemd service | ||
| ** Changing SSH keys | ||
| ** Removing mirroring rules from `ICSP`, `ITMS`, and `IDMS` objects | ||
| ** Changing the trusted CA, by updating the `user-ca-bundle` configmap in the `openshift-config` namespace | ||
| * 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". | ||
|
|
||
| .Prerequisites | ||
|
|
||
| * 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. | ||
| + | ||
| For example, if you are using the global pull secret, you can run the following command: | ||
|
|
@@ -98,7 +97,7 @@ $oc create secret docker-registry global-pull-secret-copy \ | |
|
|
||
| * You are familiar with how to configure a Containerfile. Instructions on how to create a Containerfile are beyond the scope of this documentation. | ||
|
|
||
| * 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". | ||
|
There was a problem hiding this comment. PEER REVIEW This line I copied directly from main (and 4.19+). No need for review here. |
||
|
|
||
| .Procedure | ||
|
|
||
|
|
@@ -108,42 +107,37 @@ $oc create secret docker-registry global-pull-secret-copy \ | |
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: machineconfiguration.openshift.io/v1 <1> | ||
| kind: MachineOSConfig | ||
| metadata: | ||
| name: layered <2> | ||
| spec: | ||
| machineConfigPool: | ||
| name: layered <3> | ||
| containerFile: # <4> | ||
| - containerfileArch: NoArch <5> | ||
| content: |- | ||
| FROM configs AS final | ||
| RUN dnf install -y cowsay && \ | ||
| dnf clean all && \ | ||
| ostree container commit | ||
| imageBuilder: # <6> | ||
| imageBuilderType: Job | ||
| baseImagePullSecret: # <7> | ||
| name: global-pull-secret-copy | ||
| renderedImagePushSpec: image-registry.openshift-image-registry.svc:5000/openshift/os-image:latest # <8> | ||
| renderedImagePushSecret: # <9> | ||
| 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`. | ||
| <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. | ||
| <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. | ||
| <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. | ||
| <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. | ||
| <9> Specifies the name of the push secret that the MCO needs to push the newly-built custom layered image to that registry. | ||
|
|
||
| .. Create the `MachineOSConfig` object: | ||
| + | ||
|
|
@@ -230,7 +224,7 @@ $ oc describe machineosbuild <object_name> | |
| ---- | ||
| Name: layered-ad5a3cad36303c363cf458ab0524e7c0 | ||
| # ... | ||
| API Version: machineconfiguration.openshift.io/v1 | ||
| Kind: MachineOSBuild | ||
| # ... | ||
| Spec: | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PEER REVIEW This file I copied directly from main (and 4.19). No need for review here.