mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
OSDOCS On Cluster Layering: Install Time Support
This commit is contained in:
Michael Burke
committed by
openshift-cherrypick-robot
openshift-cherrypick-robot
parent
f5c87df66d
commit
61136550aa
@@ -6,8 +6,8 @@ include::_attributes/common-attributes.adoc[]
|
||||
|
||||
toc::[]
|
||||
|
||||
|
||||
{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.
|
||||
[role="_abstract"]
|
||||
You can 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.
|
||||
@@ -30,15 +30,17 @@ Installing realtime kernel and extensions RPMs as custom layered content is not
|
||||
|
||||
As soon as you apply the custom layered image to your cluster, you effectively _take ownership_ of your custom layered images and those nodes. While Red Hat remains responsible for maintaining and updating the base {op-system} image on standard nodes, you are responsible for maintaining and updating images on nodes that use a custom layered image. You assume the responsibility for the package you applied with the custom layered image and any issues that might arise with the package.
|
||||
|
||||
There are two methods for deploying a custom layered image onto your nodes:
|
||||
There are three methods for deploying a custom layered image onto your nodes:
|
||||
|
||||
{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.
|
||||
|
||||
{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.
|
||||
|
||||
During {product-title} installation:: You can apply a pre-built custom layered image to specific nodes during {product-title} installation.
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
For both methods, use the same base {op-system} image installed on the rest of your cluster. Use the `oc adm release info --image-for rhel-coreos` command to obtain the base image used in your cluster.
|
||||
For these methods, use the same base {op-system} image installed on the rest of your cluster. Use the `oc adm release info --image-for rhel-coreos` command to obtain the base image used in your cluster.
|
||||
====
|
||||
|
||||
[id="coreos-layering-examples_{context}"]
|
||||
@@ -222,6 +224,8 @@ xref:../machine_configuration/mco-coreos-layering.adoc#coreos-layering-updating_
|
||||
|
||||
include::modules/coreos-layering-removing.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/coreos-layering-install-time.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/coreos-layering-updating.adoc[leveloffset=+1]
|
||||
|
||||
////
|
||||
|
||||
118
modules/coreos-layering-install-time.adoc
Normal file
118
modules/coreos-layering-install-time.adoc
Normal file
@@ -0,0 +1,118 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * machine_configuration/mco-coreos-layering.adoc
|
||||
|
||||
ifeval::["{context}" == "installing-"]
|
||||
:install:
|
||||
endif::[]
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="coreos-layering-install-time_{context}"]
|
||||
= Applying a custom layered image during {product-title} installation
|
||||
|
||||
[role="_abstract"]
|
||||
You can use the standard {product-title} installation process to apply a custom layered image to your nodes by adding a `MachineOSConfig` custom resource (CR) YAML and a push secret YAML to the `<installation_directory>/manifests/` directory. This allows you to use {image-mode-os-lower} to apply additional functionality to specific nodes upon cluster installation.
|
||||
|
||||
ifdef::install[]
|
||||
With {image-mode-os-lower}, you can extend the functionality of your base {op-system-first} image by layering additional images onto the base image. This layering does not modify the base RHCOS image. Instead, it creates a custom layered image that includes all {op-system} functionality and adds additional functionality to specific nodes in the cluster. For example, you can create custom layered images to apply hotfixes, RHEL packages, or third-party RPMs to the nodes your cluster.
|
||||
|
||||
For more information on {image-mode-os-lower}, see the "Additional resources" section.
|
||||
endif::install[]
|
||||
|
||||
After the installation, if you modify a machine config pool or update the {product-title} version, the Machine Config Operator (MCO) builds and applies a new custom layered image, and pushes the updated image to your repository.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* You have a custom layered image in a repository that your cluster can access.
|
||||
+
|
||||
.Example containerFile for a custom layered image
|
||||
[source,yaml]
|
||||
----
|
||||
FROM quay.io/centos/centos:stream9 AS centos
|
||||
RUN dnf install -y epel-release
|
||||
|
||||
FROM [rhel-coreos image] AS configs
|
||||
COPY --from=centos /etc/yum.repos.d /etc/yum.repos.d
|
||||
COPY --from=centos /etc/pki/rpm-gpg/RPM-GPG-KEY-* /etc/pki/rpm-gpg/
|
||||
RUN sed -i 's/\$stream/9-stream/g' /etc/yum.repos.d/centos*.repo && \
|
||||
rpm-ostree install cowsay && \
|
||||
ostree container commit
|
||||
----
|
||||
|
||||
* You have a repository and any needed secret where the MCO can push any updated custom layered images.
|
||||
|
||||
.Procedure
|
||||
|
||||
include::snippets/coreos-layering-on-callouts.adoc[]
|
||||
|
||||
. Create a YAML file for the push secret similar to the following:
|
||||
+
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: push-secret
|
||||
namespace: openshift-machine-config-operator
|
||||
data:
|
||||
.dockerconfigjson: secret
|
||||
type: kubernetes.io/dockerconfigjson
|
||||
----
|
||||
|
||||
. When the `manifests` directory is available, add the `MachineOSConfig` YAML to the directory by using a command similar to the following:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ cp <file-name>.yaml manifests/
|
||||
----
|
||||
where:
|
||||
+
|
||||
`file-name`:: Specifies the YAML file for the `MachineOSConfig` object.
|
||||
|
||||
. Add the push secret YAML to the `manifests` directory by using a command similar to the following:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ cp <file-name>.yaml manifests/
|
||||
----
|
||||
where:
|
||||
+
|
||||
`file-name`:: Specifies the YAML file for the push secret.
|
||||
|
||||
. Continue with the installation process as usual.
|
||||
|
||||
.Verification
|
||||
|
||||
* After the installation is complete, check that the `MachineOSConfig` object displays the `PreBuiltImageSeeded` status as `True` and contains a reference to the custom layered image by using the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc get machineosconfigs.machineconfiguration.openshift.io -o yaml
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: v1
|
||||
items:
|
||||
- apiVersion: machineconfiguration.openshift.io/v1
|
||||
kind: MachineOSConfig
|
||||
metadata:
|
||||
annotations:
|
||||
machineconfiguration.openshift.io/current-machine-os-build: worker-4cedbc10da849ae7019288febc3a2d17
|
||||
# ...
|
||||
status:
|
||||
conditions:
|
||||
- lastTransitionTime: "2025-11-19T13:32:17Z"
|
||||
message: MachineOSConfig seeded with pre-built image "quay.io/myorg/custom-rhcos@sha256:abc123..."
|
||||
reason: PreBuiltImageSeeded
|
||||
status: "True"
|
||||
type: Seeded
|
||||
currentImagePullSpec: image-registry.openshift-image-registry.svc:5000/openshift-machine-config-operator/layered-rhcos@sha256:3c8fc667adcb432ce0c83581f16086afec08a961dd28fed69bb6bad6db0a0754
|
||||
----
|
||||
where:
|
||||
+
|
||||
--
|
||||
`items.status.conditions.reason.PreBuiltImageSeeded.True`:: Specifies that the associated nodes were created using your custom layered image.
|
||||
`items.status.currentImagePullSpec`:: Specifies the digested image pull spec for the new custom layered image.
|
||||
--
|
||||
47
snippets/coreos-layering-on-callouts.adoc
Normal file
47
snippets/coreos-layering-on-callouts.adoc
Normal file
@@ -0,0 +1,47 @@
|
||||
// Text snippet included in the following modules:
|
||||
//
|
||||
// * modules/coreos-layering-install-time
|
||||
// * modules/
|
||||
|
||||
:_mod-docs-content-type: SNIPPET
|
||||
|
||||
. Create a YAML file for the `MachineOSConfig` object similar to the following:
|
||||
+
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: machineconfiguration.openshift.io/v1
|
||||
kind: MachineOSConfig
|
||||
metadata:
|
||||
name: worker
|
||||
annotations:
|
||||
machineconfiguration.openshift.io/pre-built-image: "quay.io/myorg/custom-rhcos@sha256:abc123..."
|
||||
spec:
|
||||
machineConfigPool:
|
||||
name: worker
|
||||
imageBuilder:
|
||||
imageBuilderType: Job
|
||||
renderedImagePushSpec: quay.io/your-registry/layered-rhcos:latest
|
||||
renderedImagePushSecret:
|
||||
name: push-secret
|
||||
containerFile:
|
||||
- containerfileArch: NoArch
|
||||
content: |
|
||||
FROM configs AS final
|
||||
RUN rpm-ostree install cowsay && \
|
||||
ostree container commit
|
||||
----
|
||||
where:
|
||||
+
|
||||
`metadata.name`:: Specifies a name for the `MachineOSConfig` object. The name must match the name of the associated machine config pool.
|
||||
|
||||
`metadata.annotations.machineconfiguration.openshift.io/pre-built-image`:: Specifies the digested image pull spec of your custom layered image.
|
||||
|
||||
`spec.machineConfigPool`:: Specifies the name of the machine config pool associated with the nodes where you want to deploy the custom layered image.
|
||||
|
||||
`spec.imageBuilder.imageBuilderType`:: 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.
|
||||
|
||||
`spec.renderedImagePushSpec`:: Specifies an image registry to push any updated custom layered images to, if needed, after the installation process is complete. 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. You can specify a mirror registry if you cluster is properly configured to use a mirror registry.
|
||||
|
||||
`spec.renderedImagePushSecret.name`:: Specifies the name of the push secret needed by the MCO to push the updated custom layered image to that registry.
|
||||
|
||||
`spec.containerFile`:: Specifies the containerFile that you used to create the custom layered image.
|
||||
Reference in New Issue
Block a user