Merge pull request #57252 from mburke5678/mco-third-party-layering

OSDOCS-5139: Allow admins to add 3rd party and custom content to RHCOS

Author: mburke5678

modules/coreos-layering-configuring.adoc

@@ -59,7 +59,7 @@ kind: MachineConfig
 metadata:
   labels:
     machineconfiguration.openshift.io/role: worker <1>
-  name: os-layer-hotfix
+  name: os-layer-custom
 spec:
   osImageURL: quay.io/my-registry/custom-image@sha256:306b606615dcf8f0e5e7d87fee3 <2>
 ----
@@ -105,7 +105,7 @@ NAME                                               GENERATEDBYCONTROLLER
 99-master-ssh                                                                                 3.2.0             98m
 99-worker-generated-registries                     5bdb57489b720096ef912f738b46330a8f577803   3.2.0             95m
 99-worker-ssh                                                                                 3.2.0             98m
-os-layer-hotfix                                                                                                 10s <1>
+os-layer-custom                                                                                                 10s <1>
 rendered-master-15961f1da260f7be141006404d17d39b   5bdb57489b720096ef912f738b46330a8f577803   3.2.0             95m
 rendered-worker-5aff604cb1381a4fe07feaf1595a797e   5bdb57489b720096ef912f738b46330a8f577803   3.2.0             95m
 rendered-worker-5de4837625b1cbc237de6b22bc0bc873   5bdb57489b720096ef912f738b46330a8f577803   3.2.0             4s  <2>

modules/coreos-layering-removing.adoc

@@ -16,7 +16,7 @@ To remove a {op-system-first} custom layered image from your cluster, you need t
 +
 [source,terminal]
 ----
-$ oc delete mc os-layer-hotfix
+$ oc delete mc os-layer-custom
 ----
 +
 After deleting the machine config, the nodes reboot.

post_installation_configuration/coreos-layering.adoc

@@ -22,40 +22,27 @@ RPMs installed through a custom layered image can conflict with RPMs installed b
 
 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.
 
+To apply a custom layered image, you create a Containerfile that references an {product-title} image and the RPM that you want to apply. You then push the resulting custom layered image to an image registry. In a non-production {product-title} cluster, create a `MachineConfig` object for the targeted node pool that points to the new image.
+
+[NOTE]
+====
+Use the same base {op-system} image installed on the rest of your cluster. Use the `oc adm release info --image-for rhel-coreos-8` command to obtain the base image used in your cluster.
+====
+
 :FeatureName: Image layering
 include::snippets/technology-preview.adoc[]
 
-Currently, {op-system} image layering allows you to work with Customer Experience and Engagement (CEE) to obtain and apply link:https://access.redhat.com/solutions/2996001[Hotfix packages] on top of your {op-system} image. In some instances, you might want a bug fix or enhancement before it is included in an official {product-title} release. {op-system} image layering allows you to easily add the Hotfix before it is officially released and remove the Hotfix when the underlying {op-system} image incorporates the fix.
+{op-system} image layering allows you to use the following types of images to create custom layered images:
 
+* *{product-title} Hotfixes*. You can work with Customer Experience and Engagement (CEE) to obtain and apply link:https://access.redhat.com/solutions/2996001[Hotfix packages] on top of your {op-system} image. In some instances, you might want a bug fix or enhancement before it is included in an official {product-title} release. {op-system} image layering allows you to easily add the Hotfix before it is officially released and remove the Hotfix when the underlying {op-system} image incorporates the fix.
++
 [IMPORTANT]
 ====
 Some Hotfixes require a Red Hat Support Exception and are outside of the normal scope of {product-title} support coverage or life cycle policies.
 ====
-
++
 In the event you want a Hotfix, it will be provided to you based on link:https://access.redhat.com/solutions/2996001[Red Hat Hotfix policy]. Apply it on top of the base image and test that new custom layered image in a non-production environment. When you are satisfied that the custom layered image is safe to use in production, you can roll it out on your own schedule to specific node pools. For any reason, you can easily roll back the custom layered image and return to using the default {op-system}.
-
-[NOTE]
-====
-It is planned for future releases that you can use {op-system} image layering to incorporate third-party software packages such as libreswan or numactl.
-====
-
-////
-Future features
-By using layering, you can extend your {op-system} in a number of ways, including:
-
-* {op-system} Hotfixes
-* Third-party RHEL packages.
-* Bleeding edge drivers and kernel enhancements to improve performance or add capabilities.
-* Foresic client tools to investigate possible and actual break-ins.
-* Inventory agents that provide a coherent view of the entire fleet.
-* Critical and important CVEs as soon as errata are available in RHEL to keep your systems secure.
-* SSH Key management packages.
-////
-
-To apply a custom layered image, you create a Containerfile that references an {product-title} image and the Hotfix that you want to apply. For example:
-
-// For example, the following Containerfile installs a Hotfix:
-
++
 .Example Containerfile to apply a Hotfix
 [source,yaml]
 ----
@@ -67,28 +54,36 @@ RUN rpm-ostree override replace https://example.com/myrepo/haproxy-1.0.16-5.el8.
     ostree container commit
 ----
 
-////
-For example, the following Containerfile installs the libreswan package from quay.io:
-[source,terminal]
+* *{op-system-base} packages*. You can download {op-system-base-full} packages from the link:https://access.redhat.com/downloads/content/479/ver=/rhel---9/9.1/x86_64/packages[Red Hat Customer Portal], such as chrony, firewalld, and iputils.
++
+.Example Containerfile to apply a RHEL package
+[source,yaml]
 ----
-# Using aa 4.12.0 image
-FROM quay.io/openshift-release-dev/ocp-release@sha256:6499bc69a0707fcad481c3cb73225b867dc31b345c6e6204e28
-RUN rpm-ostree install libreswan && \
-    rpm-ostree cleanup -m && \
+FROM quay.io/openshift-release-dev/ocp-release@sha256:6499bc69a0707fcad481c3cb73225b867d
+ADD configure-firewall-playbook.yml .
+RUN rpm-ostree install firewalld ansible && \
+    ansible-playbook configure-firewall-playbook.yml && \
+    rpm -e ansible && \
     ostree container commit
 ----
-////
 
-[NOTE]
-====
-Use the same base {op-system} image installed on the rest of your cluster. Use the `oc adm release info --image-for rhel-coreos-8` command to obtain the base image used in your cluster.
-====
-
-Push the resulting custom layered image to an image registry. In a non-production {product-title} cluster, create a `MachineConfig` object for the targeted node pool that points to the new image.
-
-The Machine Config Operator (MCO) updates the operating system with content provided in the machine config. This creates a custom layered image that overrides the base {op-system} image on those nodes.
+* *Third-party packages*. You can download and install RPMs from third-party organizations, such as the following types of packages:
++
+--
+** Bleeding edge drivers and kernel enhancements to improve performance or add capabilities.
+** Forensic client tools to investigate possible and actual break-ins.
+** Security agents.
+** Inventory agents that provide a coherent view of the entire cluster.
+** SSH Key management packages.
+--
++
+.Example Containerfile to apply a third-party package from EPEL
+[source,yaml]
+----
+include::https://raw.githubusercontent.com/openshift/rhcos-image-layering-examples/master/htop/Containerfile[]
+----
 
-After you create the machine config, the MCO:
+After you create the machine config, the Machine Config Operator (MCO) performs the following steps:
 
 . Renders a new machine config for the specified pool or pools.
 . Performs cordon and drain operations on the nodes in the pool or pools.