quickstart edits

Author: Michael Burke

modules/coreos-layering-configuring-on.adoc

@@ -6,26 +6,28 @@
 [id="coreos-layering-configuring-on_{context}"]
 = Using on-cluster layering to apply a custom layered image
 
-To apply a custom layered image to your cluster by using the on-cluster build process, make a `MachineOSConfig` custom resource that includes a Containerfile, a machine config pool reference, repository push and pull secrets, and other parameters as described in the prerequisites.
+To apply a custom layered image to your cluster by using the on-cluster build process, make a `MachineOSConfig` custom resource (CR) that specifies the following parameters: 
 
-When you create the object, the Machine Config Operator (MCO) creates a `MachineOSBuild` object and a `machine-os-builder` pod. The build process also creates transient objects, such as config maps, which are cleaned up after the build is complete. 
+* the Containerfile to build
+* the machine config pool to associate the build
+* where the final image should be pushed and pulled from
+* the push and pull secrets to use
+
+When you create the object, the Machine Config Operator (MCO) creates a `MachineOSBuild` object and a `machine-os-builder` pod. The build process also creates transient objects, such as config maps, which are cleaned up after the build is complete.
 
 When the build is complete, the MCO pushes the new custom layered image to your repository for use when deploying new nodes. You can see the digested image pull spec for the new custom layered image in the `MachineOSBuild` object and `machine-os-builder` pod.
 
 You should not need to interact with these new objects or the `machine-os-builder` pod. However, you can use all of these resources for troubleshooting, if necessary.
 
 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[]
-
 .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 global pull secret in the `openshift-machine-config-operator` namespace that the MCO needs in order to pull the base operating system image.
 
-* You have the pull secret in the `openshift-machine-config-operator` namespace that the MCO needs to pull the base operating system image.
+* You have a copy of the `etc-pki-entitlement` secret in the `openshift-machine-api` namespace.
 
-* You have the push secret that the MCO needs to push the new custom layered image to your registry.
+* You have the push secret that the MCO needs in order to push the new custom layered image to your registry.
 
 * You have a pull secret that your nodes need to pull the new custom layered image from your registry. This should be a different secret than the one used to push the image to the repository.
 
@@ -50,30 +52,32 @@ spec:
     name: <mcp_name> <1>
   buildInputs:
     containerFile: # <2>
-    - containerfileArch: noarch
+    - containerfileArch: noarch <3>
       content: |-
-        FROM configs AS final
+        FROM configs AS final <4>
         RUN dnf install -y cowsay && \
          dnf clean all && \
          ostree container commit
-    imageBuilder: # <3>
+    imageBuilder: # <5>
       imageBuilderType: PodImageBuilder
-    baseImagePullSecret: # <4>
+    baseImagePullSecret: # <6>
       name: global-pull-secret-copy
-    renderedImagePushspec: image-registry.openshift-image-registry.svc:5000/openshift/os-image:latest  # <5>
-    renderedImagePushSecret: # <6>
+    renderedImagePushspec: image-registry.openshift-image-registry.svc:5000/openshift/os-image:latest  # <7>
+    renderedImagePushSecret: # <8>
       name: builder-dockercfg-7lzwl
-  buildOutputs: # <7>
+  buildOutputs: # <9>
     currentImagePullSecret:
       name: builder-dockercfg-7lzwl
 ----
-<1> Specifies the name of the machine config pool associated with the nodes where you want to deploy the custom layered image.
-<2> Specifies the Containerfile to configure the custom layered image.
-<3> Specifies the name of the image builder to use. This must be `PodImageBuilder`.
-<4> Specifies the name of the pull secret that the MCO needs to pull the base operating system image from the registry.
-<5> 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.
-<6> Specifies the name of the push secret that the MCO needs to push the newly-built custom layered image to that registry.
-<7> Specifies the secret required by the image registry that the nodes need 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.
+<1> Specifies the machine config pool to deploy the custom layered image.
+<2> Specifies the Containerfile to configure the custom layered image. You can specify multiple build stages in the Containerfile.
+<3> Specifies the architecture of the image to be built. You must set this parameter to `noarch`.
+<4> Specifies the build stage as final. This field is required and applies to the last image in the build.
+<5> Specifies the name of the image builder to use. You must set this parameter to `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 the 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.
 
 .. Create the `MachineOSConfig` object:
 +
@@ -115,13 +119,14 @@ When you save the changes, the MCO drains, cordons, and reboots the nodes. After
 
 .Verification
 
-. Verify that the new pods are running by using the following command:
+. Verify that the new pods are ready by running the following command:
 +
 [source,terminal]
 ----
-$ oc get pods -n <machineosbuilds_namespace>
+$ oc get pods -n openshift-machine-config-operator
 ----
 +
+.Example output
 [source,terminal]
 ----
 NAME                                                              READY   STATUS    RESTARTS   AGE
@@ -132,48 +137,28 @@ machine-os-builder-6fb66cfb99-zcpvq                               1/1     Runnin
 <1> This is the build pod where the custom layered image is building.
 <2> This pod can be used for troubleshooting.
 
-. Verify that the `MachineOSConfig` object contains a reference to the new custom layered image:
+. Verify the current stage of your layered build by running the following command:
 +
 [source,terminal]
 ----
-$ oc describe MachineOSConfig <object_name>
+$ oc get machineosbuilds
 ----
 +
-[source,yaml]
+.Example output
+[source,terminal]
 ----
-apiVersion: machineconfiguration.openshift.io/v1alpha1
-kind: MachineOSConfig
-metadata:
-  name: layered
-spec:
-  buildInputs:
-    baseImagePullSecret:
-      name: global-pull-secret-copy
-    containerFile:
-    - containerfileArch: noarch
-      content: ""
-    imageBuilder:
-      imageBuilderType: PodImageBuilder
-    renderedImagePushSecret:
-      name: builder-dockercfg-ng82t-canonical
-    renderedImagePushspec: image-registry.openshift-image-registry.svc:5000/openshift-machine-config-operator/os-image:latest
-  buildOutputs:
-    currentImagePullSecret:
-      name: global-pull-secret-copy
-  machineConfigPool:
-    name: layered
-status:
-  currentImagePullspec: image-registry.openshift-image-registry.svc:5000/openshift-machine-config-operator/os-image@sha256:f636fa5b504e92e6faa22ecd71a60b089dab72200f3d130c68dfec07148d11cd # <1>
+NAME                                                                PREPARED   BUILDING   SUCCEEDED   INTERRUPTED   FAILED
+layered-rendered-layered-ef6460613affe503b530047a11b28710-builder   False      True       False       False         False
 ----
-<1> Digested image pull spec for the new custom layered image.
 
-. Verify that the `MachineOSBuild` object contains a reference to the new custom layered image.
+. Verify that the `MachineOSBuild` object contains a reference to the new custom layered image by running the following command:
 +
 [source,terminal]
 ----
 $ oc describe machineosbuild <object_name>
 ----
 +
+.Example output
 [source,yaml]
 ----
 apiVersion: machineconfiguration.openshift.io/v1alpha1

modules/coreos-layering-configuring.adoc

@@ -65,7 +65,7 @@ metadata:
 spec:
   osImageURL: quay.io/my-registry/custom-image@sha256... <2>
 ----
-<1> Specifies the machine config pool to apply the custom layered image.
+<1> Specifies the machine config pool to deploy the custom layered image.
 <2> Specifies the path to the custom layered image in the repository.
 
 .. Create the `MachineConfig` object: