Add hardware_enablement category and SRO documentation #35687
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,12 @@ | ||||||
| [id="about-hardware-enablement"] | ||||||
|
There was a problem hiding this comment. Could this either be:
Just a thought! |
||||||
| = About hardware enablement on OpenShift | ||||||
| include::modules/common-attributes.adoc[] | ||||||
| :context: about-hardware-enablement | ||||||
|
|
||||||
| toc::[] | ||||||
|
|
||||||
| Many applications require specialized hardware or software which depend on kernel modules or drivers. The recommended approach to load out-of-tree kernel modules on {op-system-first} nodes is to use driver containers. To deploy out-of-tree drivers at the same time as cluster installation (day-1) the kmods-via-containers framework can be used. For loading drivers or kernel modules on an existing {product-title} cluster (day-2) {product-title} offers several tools: | ||||||
|
There was a problem hiding this comment. ISG
Suggested change
I would think about ways to rephrase or eliminate "day 1" and "day 2." We don't use those widely in customer-facing docs. There was a problem hiding this comment. "The recommended approach..." is passive. Could restructure like: "You can use driver containers to load out-of-tree kernel modules..." (Just as an example.) Similar idea for the sentence after it. |
||||||
|
|
||||||
dagrayvid marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||
| * The Driver Toolkit is a container image which is a part of every OpenShift release. It contains the kernel packages and other common dependencies needed for building a driver or kernel module. The Driver Toolkit can be used as a base image for driver container image builds on the {product-title}. | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. Unsure about the capitalization of "Driver Toolkit." Is this a branding decision? |
||||||
| * The Special Resource Operator (SRO) orchestrates the building and management of driver containers for loading kernel modules and drivers on an existing (day 2) OpenShift or Kubernetes cluster. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| * The Node Feature Discovery (NFD) Operator for adding node labels for CPU capabilities, kernel version, PCIe device vendor IDs, and more. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ../images |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ../modules |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| [id="special-resource-operator"] | ||
| = The 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] | ||
|
|
||
| include::modules/psap-special-resource-operator-installing.adoc[leveloffset=+1] | ||
|
|
||
| include::modules/psap-special-resource-operator-using.adoc[leveloffset=+1] | ||
|
|
||
| .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]. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,6 +1,6 @@ | ||||||
| // Module included in the following assemblies: | ||||||
| // | ||||||
| // * hardware_enablement/psap-driver-toolkit.adoc | ||||||
|
|
||||||
| [id="pulling-the-driver-toolkit"] | ||||||
|
There was a problem hiding this comment. Look at https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#anchoring-in-module-files for module anchor formatting rules.
Suggested change
|
||||||
| = Pulling the Driver Toolkit container image | ||||||
|
|
@@ -18,8 +18,8 @@ The driver-toolkit image for the latest minor release will be tagged with the mi | |||||
|
|
||||||
| .Prerequisites | ||||||
|
|
||||||
| * You have 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. | ||||||
|
There was a problem hiding this comment. ISG recommends simple present tense as much as possible. Simple past if necessary. Ex: "You have the image..."/"You obtained the image..." |
||||||
| * You have installed the OpenShift CLI (`oc`). | ||||||
|
|
||||||
| .Procedure | ||||||
|
|
||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * hardware_enablement/psap-driver-toolkit.adoc | ||
|
|
||
| [id="about-driver-toolkit"] | ||
| = About the Driver Toolkit | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * hardware_enablement/psap-node-feature-discovery-operator.adoc | ||
|
|
||
| [id="installing-the-node-feature-discovery-operator_{context}"] | ||
| = Installing the Node Feature Discovery Operator | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * hardware_enablement/psap-node-feature-discovery-operator.adoc | ||
|
|
||
| ifeval::["{context}" == "red-hat-operators"] | ||
| :operators: | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,170 @@ | ||||||
| // Module included in the following assemblies: | ||||||
| // | ||||||
| // * hardware_enablement/psap-special-resource-operator.adoc | ||||||
|
|
||||||
| [id="installing-the-special-resource-operator_{context}"] | ||||||
| = Installing the Special Resource Operator | ||||||
|
|
||||||
| As a cluster administrator, you can install the Special Resource Operator (SRO) using the {product-title} CLI or the web console. | ||||||
|
There was a problem hiding this comment. Watch for this construction elsewhere.
Suggested change
|
||||||
|
|
||||||
| [id="install-operator-cli_{context}"] | ||||||
| == Installing the Special Resource Operator using the CLI | ||||||
|
|
||||||
| As a cluster administrator, you can install SRO using the CLI. | ||||||
|
|
||||||
| .Prerequisites | ||||||
|
|
||||||
| * You have a running {product-title} cluster. | ||||||
| * You have installed the OpenShift CLI (`oc`). | ||||||
| * You are logged into the OpenShift CLI as a user with `cluster-admin` privileges. | ||||||
| * You have installed the Node Feature Discovery (NFD) Operator. | ||||||
|
|
||||||
| .Procedure | ||||||
|
|
||||||
| . Create a namespace for the Special Resource Operator. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| .. Create the `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. | ||||||
|
There was a problem hiding this comment.
Suggested change
Typically, the lead-ins on nested OLs end with colons. There was a problem hiding this comment. Could the items underneath this be moved up a level? Is the nesting important? |
||||||
|
|
||||||
| .. Create the `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 | ||||||
| ---- | ||||||
|
|
||||||
| .. Run the following `oc create` command to create the `OperatorGroup` CR: | ||||||
|
There was a problem hiding this comment. Alternative:
Suggested change
|
||||||
| + | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| $ oc create -f sro-operatorgroup.yaml | ||||||
| ---- | ||||||
|
|
||||||
| .. Run the following 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 `Subscription` CR and save the YAML in the `sro-sub.yaml` file. If the output from the previous command is different than the `spec.channel` field, replace it with the output from the previous command: | ||||||
| + | ||||||
| .Example Subscription | ||||||
|
There was a problem hiding this comment.
Suggested change
Just attempting to get around the monospace rule for this title. |
||||||
| [source,yaml] | ||||||
| ---- | ||||||
| apiVersion: operators.coreos.com/v1alpha1 | ||||||
| kind: Subscription | ||||||
| metadata: | ||||||
| name: special-resource-operator | ||||||
| namespace: openshift-special-resource-operator | ||||||
| spec: | ||||||
| channel: "4.9" | ||||||
| installPlanApproval: Automatic | ||||||
| name: special-resource-operator | ||||||
| source: redhat-operators | ||||||
| sourceNamespace: openshift-marketplace | ||||||
| ---- | ||||||
|
|
||||||
| .. Create the subscription object by running the following command: | ||||||
| + | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| $ oc create -f sro-sub.yaml | ||||||
| ---- | ||||||
|
|
||||||
| .. Change 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. | ||||||
|
|
||||||
| [id="install-operator-web-console_{context}"] | ||||||
| == Installing the Special Resource Operator using the web console | ||||||
|
There was a problem hiding this comment. This module needs to be broken in two. |
||||||
|
|
||||||
| As a cluster administrator, you can install the Special Resource Operator using the web console. | ||||||
|
|
||||||
| [NOTE] | ||||||
| ==== | ||||||
| It is recommended that you create the `Namespace` as detailed in the previous section. | ||||||
| ==== | ||||||
|
|
||||||
| .Procedure | ||||||
|
|
||||||
| . 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. | ||||||
|
There was a problem hiding this comment.
|
||||||
| . 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. | ||||||
| ==== | ||||||
|
|
||||||
| .Troubleshooting | ||||||
|
|
||||||
| 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 using the NFD Operator. | ||||||
| ==== | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.