OSDOCS-18373 HE-3 CQA B

Author: cbippley

hardware_enablement/psap-node-feature-discovery-operator.adoc

@@ -6,32 +6,26 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 Learn about the Node Feature Discovery (NFD) Operator and how you can use it to expose node-level information by orchestrating Node Feature Discovery, a Kubernetes add-on for detecting hardware features and system configuration.
 
 include::modules/psap-node-feature-discovery-operator.adoc[leveloffset=+1]
 
 include::modules/psap-installing-node-feature-discovery-operator.adoc[leveloffset=+1]
 
-[id="psap-node-feature-discovery-operator-using-the-operator"]
-== Using the Node Feature Discovery Operator
-
-The Node Feature Discovery (NFD) Operator orchestrates all resources needed to run the Node-Feature-Discovery daemon set by watching for a `NodeFeatureDiscovery` custom resource (CR). Based on the `NodeFeatureDiscovery` CR, the Operator creates the operand (NFD) components in the selected namespace. You can edit the CR to use another namespace, image, image pull policy, and `nfd-worker-conf` config map, among other options.
-
-As a cluster administrator, you can create a `NodeFeatureDiscovery` CR by using the {oc-first} or the web console.
-
-
-[NOTE]
-====
-Starting with version 4.12, the `operand.image` field in the `NodeFeatureDiscovery` CR is mandatory. If the NFD Operator is deployed by using {olm-first}, OLM automatically sets the `operand.image` field. If you create the `NodeFeatureDiscovery` CR by using the {product-title} CLI or the {product-title} web console, you must set the `operand.image` field explicitly.
-====
+include::modules/psap-using-node-feature-discovery-operator.adoc[leveloffset=+1]
 
 include::modules/creating-nfd-cr-cli.adoc[leveloffset=+2]
 
 include::modules/creating-nfd-cr-cli-disconnected.adoc[leveloffset=+2]
 
 include::modules/creating-nfd-cr-web-console.adoc[leveloffset=+2]
 
-include::modules/psap-configuring-node-feature-discovery.adoc[leveloffset=+1]
+include::modules/nfd-configuring-core.adoc[leveloffset=+1]
+
+include::modules/nfd-configuring-core-klog.adoc[leveloffset=+1]
+
+include::modules/nfd-configuring-sources.adoc[leveloffset=+1]
 
 include::modules/nfd-rules-about.adoc[leveloffset=+1]
 

modules/creating-nfd-cr-cli-disconnected.adoc

@@ -6,11 +6,12 @@
 [id="creating-nfd-cr-cli-disconnected_{context}"]
 = Creating a NodeFeatureDiscovery CR by using the CLI in a disconnected environment
 
-As a cluster administrator, you can create a `NodeFeatureDiscovery` CR instance by using the {oc-first}.
+[role="_abstract"]
+Create a `NodeFeatureDiscovery` CR instance in a disconnected environment by using the {oc-first} and a mirror registry to deploy the NFD operand without direct internet access.
 
 .Prerequisites
 
-* You have access to an {product-title} cluster
+* You have access to an {product-title} cluster.
 * You installed the {oc-first}.
 * You logged in as a user with `cluster-admin` privileges.
 * You installed the NFD Operator.
@@ -50,13 +51,13 @@ $ skopeo inspect docker://registry.redhat.io/openshift4/ose-node-feature-discove
 +
 [source,terminal]
 ----
-skopeo copy docker://registry.redhat.io/openshift4/ose-node-feature-discovery@<image_digest> docker://<mirror_registry>/openshift4/ose-node-feature-discovery@<image_digest>
+$ skopeo copy docker://registry.redhat.io/openshift4/ose-node-feature-discovery@<image_digest> docker://<mirror_registry>/openshift4/ose-node-feature-discovery@<image_digest>
 ----
 +
 .Example command
 [source,terminal]
 ----
-skopeo copy docker://registry.redhat.io/openshift4/ose-node-feature-discovery@sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef docker://<your-mirror-registry>/openshift4/ose-node-feature-discovery@sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+$ skopeo copy docker://registry.redhat.io/openshift4/ose-node-feature-discovery@sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef docker://<your_mirror_registry>/openshift4/ose-node-feature-discovery@sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
 ----
 
 . Create a `NodeFeatureDiscovery` CR:
@@ -70,7 +71,7 @@ metadata:
   name: nfd-instance
 spec:
   operand:
-    image: <mirror_registry>/openshift4/ose-node-feature-discovery@<image_digest> <1>
+    image: <mirror_registry>/openshift4/ose-node-feature-discovery@<image_digest>
     imagePullPolicy: Always
   workerConfig:
     configData: |
@@ -142,7 +143,10 @@ spec:
             matchOn:
             - loadedKMod: ["example_kmod3"]
 ----
-<1> The `operand.image` field is mandatory.
++
+where:
++
+`operand.image`:: Specifies the required operand image.
 
 . Create the `NodeFeatureDiscovery` CR by running the following command:
 +

modules/creating-nfd-cr-cli.adoc

@@ -6,7 +6,8 @@
 [id="creating-nfd-cr-cli_{context}"]
 = Creating a NodeFeatureDiscovery CR by using the CLI
 
-As a cluster administrator, you can create a `NodeFeatureDiscovery` CR instance by using the {oc-first}.
+[role="_abstract"]
+Create a `NodeFeatureDiscovery` CR instance by using the {oc-first} to deploy the NFD operand and enable hardware feature detection on your cluster nodes.
 
 [NOTE]
 ====
@@ -17,7 +18,7 @@ The following example shows the use of `-rhel9` to acquire the correct image.
 
 .Prerequisites
 
-* You have access to an {product-title} cluster
+* You have access to an {product-title} cluster.
 * You installed the {oc-first}.
 * You logged in as a user with `cluster-admin` privileges.
 * You installed the NFD Operator.
@@ -38,7 +39,7 @@ spec:
   instance: "" # instance is empty by default
   topologyupdater: false # False by default
   operand:
-    image: registry.redhat.io/openshift4/ose-node-feature-discovery-rhel9:v{product-version} <1>
+    image: registry.redhat.io/openshift4/ose-node-feature-discovery-rhel9:v{product-version}
     imagePullPolicy: Always
   workerConfig:
     configData: |
@@ -110,7 +111,10 @@ spec:
             matchOn:
             - loadedKMod: ["example_kmod3"]
 ----
-<1> The `operand.image` field is mandatory.
++
+where:
++
+`operand.image`:: Specifies the required operand image.
 
 . Create the `NodeFeatureDiscovery` CR by running the following command:
 +

modules/creating-nfd-cr-web-console.adoc

@@ -6,11 +6,12 @@
 [id="creating-nfd-cr-web-console_{context}"]
 = Creating a NodeFeatureDiscovery CR by using the web console
 
-As a cluster administrator, you can create a `NodeFeatureDiscovery` CR by using the {product-title} web console.
+[role="_abstract"]
+Create a `NodeFeatureDiscovery` CR by using the {product-title} web console to deploy the NFD operand and enable hardware feature detection on your cluster nodes.
 
 .Prerequisites
 
-* You have access to an {product-title} cluster
+* You have access to an {product-title} cluster.
 * You logged in as a user with `cluster-admin` privileges.
 * You installed the NFD Operator.
 
@@ -20,7 +21,7 @@ As a cluster administrator, you can create a `NodeFeatureDiscovery` CR by using
 . In the *Node Feature Discovery* section, under *Provided APIs*, click *Create instance*.
 . Edit the values of the `NodeFeatureDiscovery` CR.
 . Click *Create*.
-
++
 [NOTE]
 ====
 Starting with version 4.12, the `operand.image` field in the `NodeFeatureDiscovery` CR is mandatory. If the NFD Operator is deployed by using {olm-first}, OLM automatically sets the `operand.image` field. If you create the `NodeFeatureDiscovery` CR by using the {product-title} CLI or the {product-title} web console, you must set the `operand.image` field explicitly.

modules/nfd-configuring-core-klog.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/psap-node-feature-discovery-operator.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="nfd-configuring-core-klog_{context}"]
+= NFD core klog configuration parameters
+
+[role="_abstract"]
+Configure Node Feature Discovery (NFD) logging behavior, including log verbosity, output destinations, and file rotation, to support debugging and operational monitoring.
+
+The logger options can also be specified using command-line flags, which take precedence over any corresponding config file options.
+
+`core.klog.addDirHeader`::
+If set to `true`, adds the file directory to the header of the log messages. Default: `false`. Runtime configurable: yes.
+
+`core.klog.alsologtostderr`::
+Log to standard error as well as files. Default: `false`. Runtime configurable: yes.
+
+`core.klog.logBacktraceAt`::
+When logging hits line `file:N`, emit a stack trace. Default: empty. Runtime configurable: yes.
+
+`core.klog.logDir`::
+If non-empty, write log files in this directory. Default: empty. Runtime configurable: no.
+
+`core.klog.logFile`::
+If not empty, use this log file. Default: empty. Runtime configurable: no.
+
+`core.klog.logFileMaxSize`::
+Defines the maximum size a log file can grow to. Unit is megabytes. If the value is `0`, the maximum file size is unlimited. Default: `1800`. Runtime configurable: no.
+
+`core.klog.logtostderr`::
+Log to standard error instead of files. Default: `true`. Runtime configurable: yes.
+
+`core.klog.skipHeaders`::
+If set to `true`, avoid header prefixes in the log messages. Default: `false`. Runtime configurable: yes.
+
+`core.klog.skipLogHeaders`::
+If set to `true`, avoid headers when opening log files. Default: `false`. Runtime configurable: no.
+
+`core.klog.stderrthreshold`::
+Logs at or above this threshold go to stderr. Default: `2`. Runtime configurable: yes.
+
+`core.klog.v`::
+Specifies the number for the log level verbosity. Default: `0`. Runtime configurable: yes.
+
+`core.klog.vmodule`::
+Specifies a comma-separated list of `pattern=N` settings for file-filtered logging. Default: empty. Runtime configurable: yes.

modules/nfd-configuring-core.adoc

@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/psap-node-feature-discovery-operator.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="nfd-configuring-core_{context}"]
+= NFD core configuration parameters
+
+[role="_abstract"]
+Configure core Node Feature Discovery (NFD) settings to control feature detection intervals, label filtering, and publishing behavior across all feature sources.
+
+`core.sleepInterval`::
+Specifies the interval between consecutive passes of feature detection or re-detection, and thus also the interval between node re-labeling. A non-positive value implies infinite sleep interval; no re-detection or re-labeling is done. This value is overridden by the deprecated `--sleep-interval` command-line flag, if specified. The default value is `60s`.
++
+.Example usage
+[source,yaml]
+----
+core:
+  sleepInterval: 60s
+----
+
+`core.sources`::
+Specifies the list of enabled feature sources. A special value `all` enables all feature sources. This value is overridden by the deprecated `--sources` command-line flag, if specified. Default: `[all]`.
++
+.Example usage
+[source,yaml]
+----
+core:
+  sources:
+    - system
+    - custom
+----
+
+`core.labelWhiteList`::
+Specifies a regular expression for filtering feature labels based on the label name. Non-matching labels are not published. The regular expression is only matched against the basename part of the label, the part of the name after '/'. The label prefix, or namespace, is omitted. This value is overridden by the deprecated `--label-whitelist` command-line flag, if specified. Default: `null`.
++
+.Example usage
+[source,yaml]
+----
+core:
+  labelWhiteList: '^cpu-cpuid'
+----
+
+`core.noPublish`::
+Setting `core.noPublish` to `true` disables all communication with the `nfd-master`. It is effectively a dry run flag; `nfd-worker` runs feature detection normally, but no labeling requests are sent to `nfd-master`. This value is overridden by the `--no-publish` command-line flag, if specified. The default value is `false`.
++
+.Example usage
+[source,yaml]
+----
+core:
+  noPublish: true
+----

modules/nfd-configuring-sources.adoc

@@ -0,0 +1,120 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/psap-node-feature-discovery-operator.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="nfd-configuring-sources_{context}"]
+= NFD sources configuration parameters
+
+[role="_abstract"]
+Configure Node Feature Discovery (NFD) feature sources to control which CPU, kernel, PCI, USB, and custom hardware attributes are detected and published as node labels.
+
+`sources.cpu.cpuid.attributeBlacklist`::
+Prevents publishing `cpuid` features listed in this option. This value is overridden by `sources.cpu.cpuid.attributeWhitelist`, if specified. Default: `[BMI1, BMI2, CLMUL, CMOV, CX16, ERMS, F16C, HTT, LZCNT, MMX, MMXEXT, NX, POPCNT, RDRAND, RDSEED, RDTSCP, SGX, SGXLC, SSE, SSE2, SSE3, SSE4.1, SSE4.2, SSSE3]`.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  cpu:
+    cpuid:
+      attributeBlacklist: [MMX, MMXEXT]
+----
+
+`sources.cpu.cpuid.attributeWhitelist`::
+Publishes only the `cpuid` features listed in this option. Takes precedence over `sources.cpu.cpuid.attributeBlacklist`. Default: empty.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  cpu:
+    cpuid:
+      attributeWhitelist: [AVX512BW, AVX512CD, AVX512DQ, AVX512F, AVX512VL]
+----
+
+`sources.kernel.kconfigFile`::
+Specifies the path of the kernel config file. If empty, NFD runs a search in the well-known standard locations. Default: empty.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  kernel:
+    kconfigFile: "/path/to/kconfig"
+----
+
+`sources.kernel.configOpts`::
+Specifies kernel configuration options to publish as feature labels. Default: `[NO_HZ, NO_HZ_IDLE, NO_HZ_FULL, PREEMPT]`.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  kernel:
+    configOpts: [NO_HZ, X86, DMI]
+----
+
+`sources.pci.deviceClassWhitelist`::
+Specifies a list of link:https://pci-ids.ucw.cz/read/PD[PCI device class IDs] for which to publish a label. It can be specified as a main class only (for example, `03`) or full class-subclass combination (for example `0300`). The former implies that all subclasses are accepted. The format of the labels can be further configured with `deviceLabelFields`. Default: `["03", "0b40", "12"]`.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  pci:
+    deviceClassWhitelist: ["0200", "03"]
+----
+
+`sources.pci.deviceLabelFields`::
+Specifies the set of PCI ID fields to use when constructing the name of the feature label. Valid fields are `class`, `vendor`, `device`, `subsystem_vendor` and `subsystem_device`. Default: `[class, vendor]`.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  pci:
+    deviceLabelFields: [class, vendor, device]
+----
++
+With the example config above, NFD would publish labels such as `feature.node.kubernetes.io/pci-<class-id>_<vendor-id>_<device-id>.present=true`.
+
+`sources.usb.deviceClassWhitelist`::
+Specifies a list of USB link:https://www.usb.org/defined-class-codes[device class] IDs for which to publish a feature label. The format of the labels can be further configured with `deviceLabelFields`. Default: `["0e", "ef", "fe", "ff"]`.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  usb:
+    deviceClassWhitelist: ["ef", "ff"]
+----
+
+`sources.usb.deviceLabelFields`::
+Specifies the set of USB ID fields from which to compose the name of the feature label. Valid fields are `class`, `vendor`, and `device`. Default: `[class, vendor, device]`.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  pci:
+    deviceLabelFields: [class, vendor]
+----
++
+With the example config above, NFD would publish labels such as `feature.node.kubernetes.io/usb-<class-id>_<vendor-id>.present=true`.
+
+`sources.custom`::
+Specifies the list of rules to process in the custom feature source to create user-specific labels. Default: empty.
++
+.Example usage
+[source,yaml]
+----
+sources:
+  custom:
+  - name: "my.custom.feature"
+    matchOn:
+    - loadedKMod: ["e1000e"]
+    - pciId:
+        class: ["0200"]
+        vendor: ["8086"]
+----

modules/nfd-rules-about.adoc

@@ -6,6 +6,7 @@
 [id="nfd-rules-about_{context}"]
 = About the NodeFeatureRule custom resource
 
-`NodeFeatureRule` objects are a `NodeFeatureDiscovery` custom resource designed for rule-based custom labeling of nodes. Some use cases include application-specific labeling or distribution by hardware vendors to create specific labels for their devices.
+[role="_abstract"]
+`NodeFeatureRule` objects enable rule-based custom labeling of nodes, allowing vendors and application teams to create targeted labels and taints based on detected hardware features and system configuration.
 
 `NodeFeatureRule` objects provide a method to create vendor- or application-specific labels and taints. It uses a flexible rule-based mechanism for creating labels and optionally taints based on node features.