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,134 @@
+// Module included in the following assemblies:
+//
+// * machine_configuration/mco-coreos-layering.adoc
+
+ifeval::["{context}" == "mco-coreos-layering"] 	
+:ocl:
+endif::[]
+
+:_mod-docs-content-type: CONCEPT
+[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 creating a `MachineOSConfig` custom resource (CR) and a push secret in the in 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 to 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 renderedImagePushSecret:
++
+[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/
+----
+
+. Add the push secret to the `manifests` directory by using a command similar to the following:
++
+[source,terminal]
+----
+$ cp ../<file-name>.yaml manifests/
+----
+
+. Continue with the installation process as usual.
+
+ifdef::ocl[]
+. Verification
+
+You can verify that the custom layered image is applied by performing any of the following checks:
+
+** Check that the worker machine config pool is updating with the previous machine config by using the following command:
++
+[source,terminal]
+----
+$ oc get mcp
+----
++
+. Example output
++
+[source,terminal]
+----
+NAME      CONFIG                                              UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
+master    rendered-master-50d7bc27ee8b9ca2250383f0647ade7f    True      False      False      3              3                   3                     0                      39m
+worker    rendered-worker-e8c8bc1de69777325003e80bc0c04b82    True      False      False      3              3                   3                     0                      39m 
+----
++
+When the `UPDATING` field is `True`, the machine config pool is updating with the machine config. When the field becomes `False`, the worker machine config pool has rolled out to the machine config.
+
+** Check that the `MachineOSConfig` object references the correct image by using a command similar to the following:
++
+[source,terminal]
+----
+oc get machineosconfig worker -o yaml
+----
+
+.Example output
+[source,yaml]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineOSConfig
+metadata:
+  annotations:
+    machineconfiguration.openshift.io/current-machine-os-build: layered-9a8f89455246fa0c42ecee6ff1fa1a45
+  labels:
+    machineconfiguration.openshift.io/createdByOnClusterBuildsHelper: ""
+  name: layered-image
+# ...
+status:
+  currentImagePullSpec: image-registry.openshift-image-registry.svc:5000/openshift-machine-config-operator/layered-rhcos@sha256:3c8fc667adcb432ce0c83581f16086afec08a961dd28fed69bb6bad6db0a0754 
+----
+where:
++
+`status.currentImagePullSpec`:: Specifies the digested image pull spec for the new custom layered image.
+
+** Check that the build pod reports a successful build by using a command similar to the following:
++
+[source,terminal]
+----
+oc get machineosbuild <build-name> -o yaml
+----
+
+# Look for:
+# 1. PreBuiltImage label set to "true" 
+# 2. Status shows "Succeeded" condition
+# 3. DigestedImagePushSpec matches your pre-built image
+# 4. BuildEnd timestamp is set
+# 5. Reason: "PreBuiltImageSeeded"
+endif::ocl[]
+
+ifeval::["{context}" == "mco-coreos-layering"] 	
+:!ocl:
+endif::[]

snippets/coreos-layering-on-callouts.adoc

@@ -0,0 +1,55 @@
+// Text snippet included in the following modules:
+//
+// * modules/coreos-layering-install-time
+// * modules/
+
+:_mod-docs-content-type: SNIPPET
+
+. Create a `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
+  baseImagePullSecret:
+    name: pull-secret
+  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. This name is used with other {image-mode-os-on-lower} resources. The examples in this documentation use the name `layered-image`.
+
+ifdef::ocl[]
+`metadata.annotations.machineconfiguration.openshift.io/pre-built-image: "<pull_spec>"`:: Triggers the {image-mode-os-lower} installation workflow.
+endif::ocl[]
+
+`spec.machineConfigPool`:: 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-image` machine config pool.
+
+`spec.containerFile`:: Specifies the Containerfile to configure the custom layered image.
+
+`spec.containerfileArch.containerFile`:: 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. 
+
+`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.baseImagePullSecret.name`:: 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. This parameter is optional.
+
+`spec.renderedImagePushSpec`:: 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.
+
+`spec.renderedImagePushSecret.name`:: Specifies the name of the push secret that the MCO needs to push the newly-built custom layered image to that registry.