Merge pull request #36674 from kmccarron-rh/sro-doc

bergerhoffer · web-flow · commit 44c4f8df404f · 2021-10-05T12:08:39.000-04:00
OSDOCS-2396: Add hardware_enablement category and SRO documentation
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -2017,12 +2017,6 @@ Topics:
 - Name: Scaling the Cluster Monitoring Operator
   File: scaling-cluster-monitoring-operator
   Distros: openshift-origin,openshift-enterprise
-- Name: The Node Feature Discovery Operator
-  File: psap-node-feature-discovery-operator
-  Distros: openshift-origin,openshift-enterprise
-- Name: The Driver Toolkit
-  File: psap-driver-toolkit
-  Distros: openshift-origin,openshift-enterprise
 - Name: Planning your environment according to object maximums
   File: planning-your-environment-according-to-object-maximums
   Distros: openshift-origin,openshift-enterprise
@@ -2053,6 +2047,19 @@ Topics:
   File: ztp-deploying-disconnected
   Distros: openshift-origin,openshift-enterprise
 ---
+Name: Hardware enablement
+Dir: hardware_enablement
+Distros: openshift-origin,openshift-enterprise
+Topics:
+- Name: About hardware enablement
+  File: about-hardware-enablement
+- Name: Driver Toolkit
+  File: psap-driver-toolkit
+- Name: Special Resource Operator
+  File: psap-special-resource-operator
+- Name: Node Feature Discovery Operator
+  File: psap-node-feature-discovery-operator
+---
 Name: Backup and restore
 Dir: backup_and_restore
 Distros: openshift-origin,openshift-enterprise
diff --git a/hardware_enablement/about-hardware-enablement.adoc b/hardware_enablement/about-hardware-enablement.adoc
@@ -0,0 +1,12 @@
+[id="about-hardware-enablement"]
+= About hardware enablement
+include::modules/common-attributes.adoc[]
+:context: about-hardware-enablement
+
+toc::[]
+
+Many applications require specialized hardware or software that depends on kernel modules or drivers. You can use driver containers to load out-of-tree kernel modules on {op-system-first} nodes. To deploy out-of-tree drivers during cluster installation, use the `kmods-via-containers` framework. To load drivers or kernel modules on an existing {product-title} cluster, {product-title} offers several tools:
+
+* The Driver Toolkit is a container image that is a part of every {product-title} release. It contains the kernel packages and other common dependencies that are needed to build a driver or kernel module. The Driver Toolkit can be used as a base image for driver container image builds on {product-title}.
+* The Special Resource Operator (SRO) orchestrates the building and management of driver containers to load kernel modules and drivers on an existing OpenShift or Kubernetes cluster.
+* The Node Feature Discovery (NFD) Operator adds node labels for CPU capabilities, kernel version, PCIe device vendor IDs, and more.
diff --git a/hardware_enablement/images b/hardware_enablement/images
@@ -0,0 +1 @@
+../images
diff --git a/hardware_enablement/modules b/hardware_enablement/modules
@@ -0,0 +1 @@
+../modules
diff --git a/hardware_enablement/psap-driver-toolkit.adoc b/hardware_enablement/psap-driver-toolkit.adoc
@@ -1,5 +1,5 @@
 [id="driver-toolkit"]
-= The Driver Toolkit
+= Driver Toolkit
 include::modules/common-attributes.adoc[]
 :context: driver-toolkit
 
@@ -15,3 +15,8 @@ include::modules/psap-driver-toolkit.adoc[leveloffset=+1]
 include::modules/psap-driver-toolkit-pulling.adoc[leveloffset=+1]
 
 include::modules/psap-driver-toolkit-using.adoc[leveloffset=+1]
+
+[id="additional-resources_driver-toolkkit-id"]
+== Additional resources
+
+* For more information about configuring registry storage for your cluster, see xref:../registry/configuring-registry-operator.adoc#registry-removed_configuring-registry-operator[Image Registry Operator in OpenShift Container Platform].
diff --git a/hardware_enablement/psap-node-feature-discovery-operator.adoc b/hardware_enablement/psap-node-feature-discovery-operator.adoc
@@ -1,5 +1,5 @@
 [id="node-feature-discovery-operator"]
-= The Node Feature Discovery Operator
+= Node Feature Discovery Operator
 include::modules/common-attributes.adoc[]
 :context: node-feature-discovery-operator
 
diff --git a/hardware_enablement/psap-special-resource-operator.adoc b/hardware_enablement/psap-special-resource-operator.adoc
@@ -0,0 +1,36 @@
+[id="special-resource-operator"]
+= Special Resource Operator
+include::modules/common-attributes.adoc[]
+:context: special-resource-operator
+
+toc::[]
+
+Learn about the Special Resource Operator (SRO) and how you can use it to build and manage driver containers for loading kernel modules and device drivers on nodes in an {product-title} cluster.
+
+
+:FeatureName: The Special Resource Operator
+include::modules/technology-preview.adoc[leveloffset=+0]
+
+include::modules/psap-special-resource-operator.adoc[leveloffset=+1]
+
+[id="installing-special-resource-operator"]
+== Installing the Special Resource Operator
+
+As a cluster administrator, you can install the Special Resource Operator (SRO) by using the OpenShift CLI or the web console.
+
+include::modules/psap-special-resource-operator-installing-using-cli.adoc[leveloffset=+2]
+
+include::modules/psap-special-resource-operator-installing-using-web-console.adoc[leveloffset=+2]
+
+include::modules/psap-special-resource-operator-using.adoc[leveloffset=+1]
+
+include::modules/psap-special-resource-operator-using-manifests.adoc[leveloffset=+2]
+
+include::modules/psap-special-resource-operator-using-configmaps.adoc[leveloffset=+2]
+
+[id="additional-resources_special-resource-operator"]
+== Additional resources
+
+* For information about restoring the Image Registry Operator state before using the Special Resource Operator, see
+xref:../registry/configuring-registry-operator.adoc#registry-removed_configuring-registry-operator[Image registry removed during installation].
+* For details about installing the NFD Operator see xref:psap-node-feature-discovery-operator.adoc#installing-the-node-feature-discovery-operator_node-feature-discovery-operator[Node Feature Discovery (NFD) Operator].
diff --git a/modules/psap-driver-toolkit-pulling.adoc b/modules/psap-driver-toolkit-pulling.adoc
@@ -1,8 +1,8 @@
 // Module included in the following assemblies:
 //
-// * scalability_and_performance/psap-driver-toolkit.adoc
+// * hardware_enablement/psap-driver-toolkit.adoc
 
-[id="pulling-the-driver-toolkit"]
+[id="pulling-the-driver-toolkit_{context}"]
 = Pulling the Driver Toolkit container image
 
 The `driver-toolkit` image is available from the link:https://registry.redhat.io/[Container images section of the Red Hat Ecosystem Catalog] and in the {product-title} release payload. The image corresponding to the most recent minor release of {product-title} will be tagged with the version number in the catalog. The image URL for a specific release can be found using the `oc adm` CLI command.
@@ -18,8 +18,8 @@ The driver-toolkit image for the latest minor release will be tagged with the mi
 
 .Prerequisites
 
-* Obtain the image pull secret needed to perform an installation of {product-title}, from the link:https://console.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site.
-* Install the OpenShift CLI (`oc`).
+* You obtained the image pull secret needed to perform an installation of {product-title}, from the link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site.
+* You installed the OpenShift CLI (`oc`).
 
 .Procedure
 
diff --git a/modules/psap-driver-toolkit-using.adoc b/modules/psap-driver-toolkit-using.adoc
@@ -1,20 +1,26 @@
 // Module included in the following assemblies:
 //
-// * scalability_and_performance/psap-driver-toolkit.adoc
+// * hardware_enablement/psap-driver-toolkit.adoc
 
-[id="using-the-driver-toolkit"]
+[id="using-the-driver-toolkit_{context}"]
 = Using the Driver Toolkit
 
 As an example, the Driver Toolkit can be used as the base image for building a very simple kernel module called simple-kmod.
 
-[id="create-simple-kmod-image"]
+[NOTE]
+====
+The Driver Toolkit contains the necessary dependencies, `openssl`, `mokutil`, and `keyutils`, needed to sign a kernel module. However, in this example, the simple-kmod kernel module is not signed and therefore cannot be loaded on systems with `Secure Boot` enabled. 
+====
+
+[id="create-simple-kmod-image_{context}"]
 == Build and run the simple-kmod driver container on a cluster
 
 .Prerequisites
 
-* An {product-title} cluster
-* Install the OpenShift CLI (`oc`).
-* Log in as a user with `cluster-admin` privileges.
+* You have a running {product-title} cluster.
+* You set the Image Registry Operator state to `Managed` for your cluster.
+* You installed the OpenShift CLI (`oc`).
+* You are logged into the OpenShift CLI as a user with `cluster-admin` privileges.
 
 .Procedure
 
diff --git a/modules/psap-driver-toolkit.adoc b/modules/psap-driver-toolkit.adoc
@@ -1,8 +1,8 @@
 // Module included in the following assemblies:
 //
-// * scalability_and_performance/psap-driver-toolkit.adoc
+// * hardware_enablement/psap-driver-toolkit.adoc
 
-[id="about-driver-toolkit"]
+[id="about-driver-toolkit_{context}"]
 = About the Driver Toolkit
 
 [discrete]
diff --git a/modules/psap-installing-node-feature-discovery-operator.adoc b/modules/psap-installing-node-feature-discovery-operator.adoc
@@ -1,11 +1,11 @@
 // Module included in the following assemblies:
 //
-// * scalability_and_performance/psap-node-feature-discovery-operator.adoc
+// * hardware_enablement/psap-node-feature-discovery-operator.adoc
 
 [id="installing-the-node-feature-discovery-operator_{context}"]
 = Installing the Node Feature Discovery Operator
 
-The Node Feature Discovery (NFD) Operator orchestrates all resources needed to run the NFD daemon set. As a cluster administrator, you can install the NFD Operator using the {product-title} CLI or the web console.
+The Node Feature Discovery (NFD) Operator orchestrates all resources needed to run the NFD daemon set. As a cluster administrator, you can install the NFD Operator by using the {product-title} CLI or the web console.
 
 [id="install-operator-cli_{context}"]
 == Installing the NFD Operator using the CLI
diff --git a/modules/psap-node-feature-discovery-operator.adoc b/modules/psap-node-feature-discovery-operator.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * scalability_and_performance/psap-node-feature-discovery-operator.adoc
+// * hardware_enablement/psap-node-feature-discovery-operator.adoc
 
 ifeval::["{context}" == "red-hat-operators"]
 :operators:
diff --git a/modules/psap-special-resource-operator-installing-using-cli.adoc b/modules/psap-special-resource-operator-installing-using-cli.adoc
@@ -0,0 +1,124 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/psap-special-resource-operator.adoc
+
+[id="installing-the-special-resource-operator-using-cli_{context}"]
+= Installing the Special Resource Operator by using the CLI
+
+As a cluster administrator, you can install the Special Resource Operator (SRO) by using the OpenShift CLI.
+
+.Prerequisites
+
+* You have a running {product-title} cluster.
+* You installed the OpenShift CLI (`oc`).
+* You are logged into the OpenShift CLI as a user with `cluster-admin` privileges.
+* You installed the Node Feature Discovery (NFD) Operator.
+
+.Procedure
+
+. Create a namespace for the Special Resource Operator:
+
+.. Create the following `Namespace` custom resource (CR) that defines the `openshift-special-resource-operator` namespace, and then save the YAML in the `sro-namespace.yaml` file:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: openshift-special-resource-operator
+----
+
+.. Create the namespace by running the following command:
++
+[source,terminal]
+----
+$ oc create -f sro-namespace.yaml
+----
+
+. Install SRO in the namespace you created in the previous step:
+
+.. Create the following `OperatorGroup` CR and save the YAML in the `sro-operatorgroup.yaml` file:
++
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1
+kind: OperatorGroup
+metadata:
+  generateName: openshift-special-resource-operator-
+  name: openshift-special-resource-operator
+  namespace: openshift-special-resource-operator
+spec:
+  targetNamespaces:
+  - openshift-special-resource-operator
+----
+
+.. Create the operator group by running the following command:
++
+[source,terminal]
+----
+$ oc create -f sro-operatorgroup.yaml
+----
+
+.. Run the following `oc get` command to get the `channel` value required for the next step:
++
+[source,terminal]
+----
+$ oc get packagemanifest special-resource-operator -n openshift-marketplace -o jsonpath='{.status.defaultChannel}'
+----
++
+.Example output
+[source,terminal]
+----
+4.9
+----
+
+.. Create the following `Subscription` CR and save the YAML in the `sro-sub.yaml` file:
++
+.Example subscription CR
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: special-resource-operator
+  namespace: openshift-special-resource-operator
+spec:
+  channel: "4.9" <1>
+  installPlanApproval: Automatic
+  name: special-resource-operator
+  source: redhat-operators
+  sourceNamespace: openshift-marketplace
+----
+<1> Replace the channel value with the output from the previous command.
+
+.. Create the subscription object by running the following command:
++
+[source,terminal]
+----
+$ oc create -f sro-sub.yaml
+----
+
+.. Switch to the `openshift-special-resource-operator` project:
++
+[source,terminal]
+----
+$ oc project openshift-special-resource-operator
+----
+
+.Verification
+
+* To verify that the Operator deployment is successful, run:
++
+[source,terminal]
+----
+$ oc get pods
+----
++
+.Example output
+[source,terminal]
+----
+NAME                                                   READY   STATUS    RESTARTS   AGE
+special-resource-controller-manager-7bfb544d45-xx62r   2/2     Running   0          2m28s
+----
++
+A successful deployment shows a `Running` status.
diff --git a/modules/psap-special-resource-operator-installing-using-web-console.adoc b/modules/psap-special-resource-operator-installing-using-web-console.adoc
@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/psap-special-resource-operator.adoc
+
+[id="installing-the-special-resource-operator-using-web-console_{context}"]
+= Installing the Special Resource Operator by using the web console
+
+As a cluster administrator, you can install the Special Resource Operator (SRO) by using the {product-title} web console.
+
+.Prerequisites
+
+* You installed the Node Feature Discovery (NFD) Operator.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+. Create the required namespace for the Special Resource Operator:
+.. Navigate to *Administration* -> *Namespaces* and click *Create Namespace*.
+.. Enter `openshift-special-resource-operator` in the *Name* field and click *Create*.
+
+. Install the Special Resource Operator:
+.. In the {product-title} web console, click *Operators* -> *OperatorHub*.
+
+.. Choose *Special Resource Operator* from the list of available Operators, and then click *Install*.
+
+.. On the *Install Operator* page, select *a specific namespace on the cluster*, select the namespace created in the previous section, and then click *Install*.
+
+.Verification
+
+To verify that the Special Resource Operator installed successfully:
+
+. Navigate to the *Operators* -> *Installed Operators* page.
+. Ensure that *Special Resource Operator* is listed in the *openshift-special-resource-operator* project with a *Status* of *InstallSucceeded*.
++
+[NOTE]
+====
+During installation, an Operator might display a *Failed* status. If the installation later succeeds with an *InstallSucceeded* message, you can ignore the *Failed* message.
+====
++
+. If the Operator does not appear as installed, to troubleshoot further:
++
+.. Navigate to the *Operators* -> *Installed Operators* page and inspect the *Operator Subscriptions* and *Install Plans* tabs for any failure or errors under *Status*.
+.. Navigate to the *Workloads* -> *Pods* page and check the logs for pods in the `openshift-special-resource-operator` project.
+
++
+[NOTE]
+====
+The Node Feature Discovery (NFD) Operator is a dependency of the Special Resource Operator (SRO). If the NFD Operator is not installed before installing SRO, the Operator Lifecycle Manager will automatically install the NFD Operator. However, the required Node Feature Discovery operand will not be deployed automatically. The Node Feature Discovery Operator documentation provides details about how to deploy NFD by using the NFD Operator.
+====
diff --git a/modules/psap-special-resource-operator-using-configmaps.adoc b/modules/psap-special-resource-operator-using-configmaps.adoc
diff --git a/modules/psap-special-resource-operator-using-manifests.adoc b/modules/psap-special-resource-operator-using-manifests.adoc
diff --git a/modules/psap-special-resource-operator-using.adoc b/modules/psap-special-resource-operator-using.adoc
diff --git a/modules/psap-special-resource-operator.adoc b/modules/psap-special-resource-operator.adoc
diff --git a/modules/psap-using-node-feature-discovery-operator.adoc b/modules/psap-using-node-feature-discovery-operator.adoc
