diff --git a/machine_configuration/mco-coreos-layering.adoc b/machine_configuration/mco-coreos-layering.adoc index f22c4d6c1504..7cdc004524da 100644 --- a/machine_configuration/mco-coreos-layering.adoc +++ b/machine_configuration/mco-coreos-layering.adoc @@ -182,8 +182,11 @@ 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:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates] * 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-remove_mco-coreos-layering[Removing 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/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] include::modules/coreos-layering-configuring-on-modifying.adoc[leveloffset=+2] @@ -199,11 +202,12 @@ include::modules/coreos-layering-configuring-on-extensions.adoc[leveloffset=+2] * 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] //// -// Not in 4.18; maybe 4.19 -// include::modules/coreos-layering-configuring-on-rebuild.adoc[leveloffset=+2] +include::modules/coreos-layering-configuring-on-rebuild.adoc[leveloffset=+2] include::modules/coreos-layering-configuring-on-revert.adoc[leveloffset=+2] +include::modules/coreos-layering-configuring-on-remove.adoc[leveloffset=+2] + include::modules/coreos-layering-configuring.adoc[leveloffset=+1] .Additional resources diff --git a/modules/coreos-layering-configuring-on-modifying.adoc b/modules/coreos-layering-configuring-on-modifying.adoc index ea83275db317..3bf94598c7a9 100644 --- a/modules/coreos-layering-configuring-on-modifying.adoc +++ b/modules/coreos-layering-configuring-on-modifying.adoc @@ -24,42 +24,32 @@ include::snippets//coreos-layering-configuring-on-pause.adoc[] + [source,yaml] ---- -apiVersion: machineconfiguration.openshift.io/v1alpha1 +apiVersion: machineconfiguration.openshift.io/v1 kind: MachineOSConfig metadata: name: layered spec: machineConfigPool: - name: worker - buildInputs: - containerFile: - - containerfileArch: noarch - content: |- <1> - FROM configs AS final - - RUN rpm-ostree install rng-tools && \ - systemctl enable rngd && \ - rpm-ostree cleanup -m && \ - ostree container commit - - RUN rpm-ostree install tree && \ - ostree container commit - 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: new-secret-name - buildOutputs: - currentImagePullSecret: - name: new-secret-name <5> + name: layered + containerFile: + - containerfileArch: NoArch + content: |- <1> + FROM configs AS final + RUN dnf install -y cowsay && \ + dnf clean all && \ + ostree container commit + imageBuilder: + imageBuilderType: Job + baseImagePullSecret: + name: global-pull-secret-copy <2> + renderedImagePushSpec: image-registry.openshift-image-registry.svc:5000/openshift/os-image:latest <3> + renderedImagePushSecret: <4> + name: builder-dockercfg-mtcl23 ---- <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. -<5> Optional: Update the secret needed to pull the newly built custom layered image from the registry. + 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. diff --git a/modules/coreos-layering-configuring-on-rebuild.adoc b/modules/coreos-layering-configuring-on-rebuild.adoc new file mode 100644 index 000000000000..c7f3d229202e --- /dev/null +++ b/modules/coreos-layering-configuring-on-rebuild.adoc @@ -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 +---- ++ +.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 +---- ++ +.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 +# ... +---- diff --git a/modules/coreos-layering-configuring-on-remove.adoc b/modules/coreos-layering-configuring-on-remove.adoc new file mode 100644 index 000000000000..665721074d26 --- /dev/null +++ b/modules/coreos-layering-configuring-on-remove.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * 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. diff --git a/modules/coreos-layering-configuring-on.adoc b/modules/coreos-layering-configuring-on.adoc index 47053d6bcd86..b397f712070c 100644 --- a/modules/coreos-layering-configuring-on.adoc +++ b/modules/coreos-layering-configuring-on.adoc @@ -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. -:FeatureName: On-cluster image layering -include::snippets/technology-preview.adoc[] 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,17 +51,20 @@ NAME PREPARED BUILDING SUCCEEDED INT layered-c8765e26ebc87e1e17a7d6e0a78e8bae False False False False True ---- -// Not in 4.18; maybe 4.19 -// 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. +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 Technology Preview known limitations +== 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, {sno}, or disconnected clusters. +* 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 @@ -71,12 +72,10 @@ Note the following limitations when working with the on-cluster layering feature ** 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. +* 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 enabled the `TechPreviewNoUpgrade` feature set by using the feature gates. For more information, see "Enabling features using feature gates". - * 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. +* 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". .Procedure @@ -108,42 +107,37 @@ $oc create secret docker-registry global-pull-secret-copy \ + [source,yaml] ---- -apiVersion: machineconfiguration.openshift.io/v1alpha1 <1> +apiVersion: machineconfiguration.openshift.io/v1 <1> kind: MachineOSConfig metadata: name: layered <2> spec: machineConfigPool: - name: worker <3> - buildInputs: - containerFile: <4> - - containerfileArch: noarch - content: |- - FROM configs AS final - RUN rpm-ostree install tree && \ - ostree container commit - imageBuilder: <5> - imageBuilderType: PodImageBuilder - baseImagePullSecret: <6> - name: global-pull-secret-copy - renderedImagePushspec: image-registry.openshift-image-registry.svc:5000/openshift/os-image:latest <7> - renderedImagePushSecret: <8> - name: builder-dockercfg-7lzwl - buildOutputs: <9> - currentImagePullSecret: - name: builder-dockercfg-mtcl23 + 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 `worker` machine config pool. +<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 name of the image builder to use. This must be `PodImageBuilder`. -<6> Specifies the name of the pull secret that the MCO needs in order to pull the base operating system image from the registry. -<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. -<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. -<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. -// + -// https://github.com/openshift/openshift-docs/pull/87486/files has the v1 api versions +<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:` 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 ---- Name: layered-ad5a3cad36303c363cf458ab0524e7c0 # ... -API Version: machineconfiguration.openshift.io/v1alpha1 +API Version: machineconfiguration.openshift.io/v1 Kind: MachineOSBuild # ... Spec: