On Cluster Layering: Make it easier to see errors

Author: Michael Burke

modules/coreos-layering-configuring-on-proc.adoc

@@ -130,6 +130,37 @@ machine-os-builder-6fb66cfb99-zcpvq                                     1/1
 <1> This is the build pod where the custom layered image is building, named in the `build-<MachineOSConfig_CR_name>-<hash>` format.
 <2> This pod can be used for troubleshooting.
 
+. Verify the custom layered image build by running a command similar to the following:
++
+[source,terminal]
+----
+$ oc get machineconfigpool <mcp_name> -o yaml
+----
++
+.Example output
+[source,terminal]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineConfigPool
+metadata:
+  labels:
+    machineconfiguration.openshift.io/mco-built-in: ""
+    pools.operator.machineconfiguration.openshift.io/layered: ""
+  name: layered
+# ...
+status:
+# ...
+  conditions
+# ...
+  - lastTransitionTime: "2025-09-09T13:43:35Z"
+    message: 'Failed to build OS image for pool worker (MachineOSBuild: worker-2d03dc921ff0c242c5892a3ef1ed1608):
+      Failed: Build Failed'
+    reason: BuildFailed
+    status: "True" <1>
+    type: ImageBuildDegraded
+----
+<1> Indicates whether the custom layered image build failed. If `False`, the build succeeded. If `True`, the build failed. You can use the build pod logs to troubleshoot any build failures.
+
 . Verify the current stage of your layered build by running the following command:
 +
 [source,terminal]
@@ -141,7 +172,7 @@ $ oc get machineosbuilds
 [source,terminal]
 ----
 NAME                                             PREPARED   BUILDING   SUCCEEDED   INTERRUPTED   FAILED   AGE
-layered-image-ad5a3cad36303c363cf458ab0524e7c0   False      True       False       False         False    12m <1> 
+layered-image-ad5a3cad36303c363cf458ab0524e7c0   False      True       False       False         False    12m <1>
 ----
 <1> The `MachineOSBuild` is named in the `<MachineOSConfig_CR_name>-<hash>` format.
 

modules/coreos-layering-configuring-on.adoc

@@ -58,7 +58,7 @@ For {sno} clusters, you can apply a custom layered image to the control plane no
 
 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. Note that the MCO automatically removes these build pods after a short period of time. 
+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. Note that the MCO automatically removes these build pods after a short period of time. Also, the affected machine config pool reports a build failure through the `ImageBuildDegraded` status condition. You can use the build pod logs to troubleshoot any build failures.
 
 .Example failed `MachineOSBuild` object
 [source,terminal]