OSDOCS On Cluster Layering: Install Time Support

machine_configuration/mco-coreos-layering.adoc

@@ -224,6 +224,8 @@ include::modules/coreos-layering-removing.adoc[leveloffset=+2]
 
 include::modules/coreos-layering-updating.adoc[leveloffset=+1]
 
+include::modules/coreos-layering-install-time.adoc[leveloffset=+1]
+
 ////
 Sources:
 https://docs.google.com/document/d/1Eow2IReNWqnIh5HvCfcKV2MWgHUmFKSnBkt2rH6_V_M/edit

modules/coreos-layering-install-time.adoc

@@ -0,0 +1,104 @@
+// Module included in the following assemblies:
+//
+// * machine_configuration/mco-coreos-layering.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="coreos-layering-install-time_{context}"]
+= Using {image-mode-os-lower} upon {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 YAML files for a `MachineOSConfig` custom resource (CR) and a push secret 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.
+
+.Prerequisites
+
+* You must have a custom layered image in a repository that your cluster can access.
++
+.Example containerFile
+[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
+----
+
+.Procedure
+
+include::snippets/coreos-layering-on-callouts.adoc[]
+
+. Create the YAML 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` object 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 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/mcoqe/layering@sha256:330de1f03a0bb57b4e37eac272fdc7817b4a712bf3202ee24158a066e5d48686"
+      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. 
+`status.currentImagePullSpec`:: Specifies the digested image pull spec for the new custom layered image.
+--

snippets/coreos-layering-on-callouts.adoc

@@ -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: "<pull_spec>"
+spec:
+  machineConfigPool:
+    name: worker
+  imageBuilder:
+    imageBuilderType: Job
+  renderedImagePushSecret:
+    name: push-secret
+  renderedImagePushSpec: quay.io/your-registry/layered-rhcos:latest
+  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: "<pull_spec>"`:: Specifies the digested image pull spec of your custom layered image. This parameter triggers the {image-mode-os-lower} installation workflow. 
+
+`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.renderedImagePushSecret.name`:: Specifies the name of the push secret that the MCO needs to push any new images that are built after the installation to the registry.
+
+`spec.renderedImagePushSpec`:: Specifies the image registry to push any new images to that are built after the installation. 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.
+
+`spec.containerFile`:: Specifies the Containerfile that you used to create the custom layered image.