diff --git a/modules/about-network-resource-injector.adoc b/modules/about-network-resource-injector.adoc new file mode 100644 index 0000000000..3708b26413 --- /dev/null +++ b/modules/about-network-resource-injector.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * networking/hardware_networks/configuring-sriov-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="about-network-resource-injector_{context}"] += About the Network Resources Injector + +[role="_abstract"] +To automate network configuration for your workloads, use the Network Resources Injector. This Kubernetes Dynamic Admission Controller intercepts pod creation requests to automatically inject the necessary network resources and parameters defined for your cluster. + +The Network Resources Injector provides the following capabilities: + +* Mutation of resource requests and limits in a pod specification to add an SR-IOV resource name according to an SR-IOV network attachment definition annotation. +* Mutation of a pod specification with a Downward API volume to expose pod annotations, labels, and huge pages requests and limits. Containers that run in the pod can access the exposed information as files under the `/etc/podnetinfo` path. + +The SR-IOV Network Operator enables the Network Resources Injector when the `enableInjector` is set to `true` in the `SriovOperatorConfig` CR. The `network-resources-injector` pod runs as a daemon set on all control plane nodes. The following is an example of Network Resources Injector pods running in a cluster with three control plane nodes: + +[source,terminal] +---- +$ oc get pods -n openshift-sriov-network-operator +---- + +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +network-resources-injector-5cz5p 1/1 Running 0 10m +network-resources-injector-dwqpx 1/1 Running 0 10m +network-resources-injector-lktz5 1/1 Running 0 10m +---- + +By default, the `failurePolicy` field in the Network Resources Injector webhook is set to `Ignore`. This default setting prevents pod creation from being blocked if the webhook is unavailable. + +If you set the `failurePolicy` field to `Fail`, and the Network Resources Injector webhook is unavailable, the webhook attempts to mutate all pod creation and update requests. This behavior can block pod creation and disrupt normal cluster operations. To prevent such issues, you can enable the `featureGates.resourceInjectorMatchCondition` feature in the `SriovOperatorConfig` object to limit the scope of the Network Resources Injector webhook. If this feature is enabled, the webhook applies only to pods with the secondary network annotation `k8s.v1.cni.cncf.io/networks`. + +If you set the `failurePolicy` field to `Fail` after enabling the `resourceInjectorMatchCondition` feature, the webhook applies only to pods with the secondary network annotation `k8s.v1.cni.cncf.io/networks`. If the webhook is unavailable, the cluster still deploys pods without this annotation; this prevents unnecessary disruptions to cluster operations. + +The `featureGates.resourceInjectorMatchCondition` feature is disabled by default. To enable this feature, set the `featureGates.resourceInjectorMatchCondition` field to `true` in the `SriovOperatorConfig` object. + +.Example `SriovOperatorConfig` object configuration +[source,yaml] +---- +apiVersion: sriovnetwork.openshift.io/v1 +kind: SriovOperatorConfig +metadata: + name: default + namespace: sriov-network-operator +spec: +# ... + featureGates: + resourceInjectorMatchCondition: true +# ... +---- diff --git a/modules/about-sr-iov-operator-admission-control-webhook.adoc b/modules/about-sr-iov-operator-admission-control-webhook.adoc new file mode 100644 index 0000000000..2ff8a9ab9b --- /dev/null +++ b/modules/about-sr-iov-operator-admission-control-webhook.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * networking/hardware_networks/configuring-sriov-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="about-sr-iov-operator-admission-control-webhook_{context}"] += About the SR-IOV Network Operator admission controller webhook + +[role="_abstract"] +To validate network configurations and prevent errors, rely on the SR-IOV Network Operator admission controller webhook. This Kubernetes Dynamic Admission Controller intercepts API requests to ensure that your SR-IOV resource definitions and pod specifications comply with cluster policies. + +The SR-IOV Network Operator Admission Controller webhook provides the following capabilities: + +* Validation of the `SriovNetworkNodePolicy` CR when it is created or updated. +* Mutation of the `SriovNetworkNodePolicy` CR by setting the default value for the `priority` and `deviceType` fields when the CR is created or updated. + +The SR-IOV Network Operator Admission Controller webhook is enabled by the Operator when the `enableOperatorWebhook` is set to `true` in the `SriovOperatorConfig` CR. The `operator-webhook` pod runs as a daemon set on all control plane nodes. + +[NOTE] +==== +Use caution when disabling the SR-IOV Network Operator Admission Controller webhook. You can disable the webhook under specific circumstances, such as troubleshooting, or if you want to use unsupported devices. For information about configuring unsupported devices, see "Configuring the SR-IOV Network Operator to use an unsupported NIC". +==== + +The following is an example of the Operator Admission Controller webhook pods running in a cluster with three control plane nodes: + +[source,terminal] +---- +$ oc get pods -n openshift-sriov-network-operator +---- + +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +operator-webhook-9jkw6 1/1 Running 0 16m +operator-webhook-kbr5p 1/1 Running 0 16m +operator-webhook-rpfrl 1/1 Running 0 16m +---- + diff --git a/modules/configure-sr-iov-operator-single-node.adoc b/modules/configure-sr-iov-operator-single-node.adoc new file mode 100644 index 0000000000..77ee9ecf05 --- /dev/null +++ b/modules/configure-sr-iov-operator-single-node.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// +// * networking/hardware_networks/configuring-sriov-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configure-sr-iov-operator-single-node_{context}"] += Configuring the SR-IOV Network Operator for single node installations + +[role="_abstract"] +By default, the SR-IOV Network Operator drains workloads from a node before every policy change. The Operator performs this action to ensure that no workloads are using the virtual functions before the reconfiguration. As a result, you must configure the Operator to not drain workloads from the single node. + +For installations on a single node, other nodes do not receive the workloads. + +[IMPORTANT] +==== +After performing the following procedure to disable draining workloads, you must remove any workload that uses an SR-IOV network interface before you change any SR-IOV network node policy. +==== + +.Prerequisites + +* Install the {oc-first}. +* Log in as a user with `cluster-admin` privileges. +* You must have installed the SR-IOV Network Operator. + +.Procedure + +- To set the `disableDrain` field to `true` and the `configDaemonNodeSelector` field to `node-role.kubernetes.io/master: ""`, enter the following command: ++ +[source,terminal] +---- +$ oc patch sriovoperatorconfig default --type=merge -n openshift-sriov-network-operator --patch '{ "spec": { "disableDrain": true, "configDaemonNodeSelector": { "node-role.kubernetes.io/master": "" } } }' +---- ++ +[TIP] +==== +You can alternatively apply the following YAML to update the Operator: + +[source,yaml] +---- +apiVersion: sriovnetwork.openshift.io/v1 +kind: SriovOperatorConfig +metadata: + name: default + namespace: openshift-sriov-network-operator +spec: + disableDrain: true + configDaemonNodeSelector: + node-role.kubernetes.io/master: "" +# ... +---- +==== \ No newline at end of file diff --git a/modules/configuring-custom-nodeselector.adoc b/modules/configuring-custom-nodeselector.adoc new file mode 100644 index 0000000000..22798f0913 --- /dev/null +++ b/modules/configuring-custom-nodeselector.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * networking/hardware_networks/configuring-sriov-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configuring-custom-nodeselector_{context}"] += Configuring a custom NodeSelector for the SR-IOV Network Config daemon + +[role="_abstract"] +To specify which nodes host the SR-IOV Network Config daemon, configure a custom node selector by using node labels. By completing this task, you can restrict deployment to specific nodes instead of the default compute nodes. + +The SR-IOV Network Config daemon discovers and configures the SR-IOV network devices on cluster nodes. By default, the daemon is deployed to all the compute nodes in the cluster. + +[IMPORTANT] +===== +When you update the `configDaemonNodeSelector` field, the SR-IOV Network Config daemon is recreated on each selected node. +While the daemon is recreated, cluster users are unable to apply any new SR-IOV Network node policy or create new SR-IOV pods. +===== + +.Procedure + +* To update the node selector for the Operator, enter the following command: ++ +[source,terminal] +---- +$ oc patch sriovoperatorconfig default --type=json \ + -n openshift-sriov-network-operator \ + --patch '[{ + "op": "replace", + "path": "/spec/configDaemonNodeSelector", + "value": {} + }]' +---- ++ +Replace `` with a label to apply as in the following example: +`"node-role.kubernetes.io/worker": ""`. ++ +[TIP] +==== +You can alternatively apply the following YAML to update the Operator: + +[source,yaml] +---- +apiVersion: sriovnetwork.openshift.io/v1 +kind: SriovOperatorConfig +metadata: + name: default + namespace: openshift-sriov-network-operator +spec: + configDaemonNodeSelector: + +# ... +---- +==== \ No newline at end of file diff --git a/modules/disable-enable-network-resource-injector.adoc b/modules/disable-enable-network-resource-injector.adoc new file mode 100644 index 0000000000..0328d978ce --- /dev/null +++ b/modules/disable-enable-network-resource-injector.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * networking/hardware_networks/configuring-sriov-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="disable-enable-network-resource-injector_{context}"] += Disabling or enabling the Network Resources Injector + +[role="_abstract"] +To control the automatic configuration of your cluster workloads, enable or disable the Network Resources Injector. By adjusting these settings you can better manage whether the Kubernetes Dynamic Admission Controller automatically injects network resources and parameters into pods during their creation. + +.Prerequisites + +* Install the {oc-first}. +* Log in as a user with `cluster-admin` privileges. +* You must have installed the SR-IOV Network Operator. + +.Procedure + +* Set the `enableInjector` field. Replace `` with `false` to disable the feature or `true` to enable the feature. ++ +[source,terminal] +---- +$ oc patch sriovoperatorconfig default \ + --type=merge -n openshift-sriov-network-operator \ + --patch '{ "spec": { "enableInjector": } }' +---- ++ +[TIP] +==== +You can alternatively apply the following YAML to update the Operator: + +[source,yaml] +---- +apiVersion: sriovnetwork.openshift.io/v1 +kind: SriovOperatorConfig +metadata: + name: default + namespace: openshift-sriov-network-operator +spec: + enableInjector: +# ... +---- +==== diff --git a/modules/disable-enable-sr-iov-operator-admission-control-webhook.adoc b/modules/disable-enable-sr-iov-operator-admission-control-webhook.adoc new file mode 100644 index 0000000000..8990c241ff --- /dev/null +++ b/modules/disable-enable-sr-iov-operator-admission-control-webhook.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * networking/hardware_networks/configuring-sriov-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="disable-enable-sr-iov-operator-admission-control-webhook_{context}"] += Disabling or enabling the SR-IOV Network Operator admission controller webhook + +[role="_abstract"] +To manage validation of your network configurations, enable or disable the SR-IOV Network Operator admission controller webhook. When enabled, the Operator automatically verifies SR-IOV resource definitions and pod specifications against cluster policies. + +.Prerequisites + +* Install the {oc-first}. +* Log in as a user with `cluster-admin` privileges. +* You must have installed the SR-IOV Network Operator. + +.Procedure + +* Set the `enableOperatorWebhook` field. Replace `` with `false` to disable the feature or `true` to enable it: ++ +[source,terminal] +---- +$ oc patch sriovoperatorconfig default --type=merge \ + -n openshift-sriov-network-operator \ + --patch '{ "spec": { "enableOperatorWebhook": } }' +---- ++ +[TIP] +==== +You can alternatively apply the following YAML to update the Operator: + +[source,yaml] +---- +apiVersion: sriovnetwork.openshift.io/v1 +kind: SriovOperatorConfig +metadata: + name: default + namespace: openshift-sriov-network-operator +spec: + enableOperatorWebhook: +# ... +---- +==== + diff --git a/modules/nw-sriov-configuring-operator.adoc b/modules/nw-sriov-configuring-operator.adoc index baeccbe4fb..0be696d0b2 100644 --- a/modules/nw-sriov-configuring-operator.adoc +++ b/modules/nw-sriov-configuring-operator.adoc @@ -6,352 +6,42 @@ [id="nw-sriov-configuring-operator_{context}"] = Configuring the SR-IOV Network Operator -* Create a `SriovOperatorConfig` custom resource (CR) to deploy all the SR-IOV Operator components: +[role="_abstract"] +To manage SR-IOV network devices and network attachments in your cluster, configure the Single Root I/O Virtualization (SR-IOV) Network Operator. You can then deploy the Operator components to your cluster. -.. Create a file named `sriovOperatorConfig.yaml` using the following YAML: +.Procedure + +. Create a `SriovOperatorConfig` custom resource (CR). The following example creates a file named `sriovOperatorConfig.yaml`: + [source,yaml] ---- apiVersion: sriovnetwork.openshift.io/v1 kind: SriovOperatorConfig metadata: - name: default <1> + name: default namespace: openshift-sriov-network-operator spec: disableDrain: false - enableInjector: true <2> - enableOperatorWebhook: true <3> + enableInjector: true + enableOperatorWebhook: true logLevel: 2 featureGates: metricsExporter: false +# ... ---- + -<1> The only valid name for the `SriovOperatorConfig` resource is `default` and it must be in the namespace where the Operator is deployed. -<2> The `enableInjector` field, if not specified in the CR or explicitly set to `true`, defaults to `false` or ``, preventing any `network-resources-injector` pod from running in the namespace. The recommended setting is `true`. -<3> The `enableOperatorWebhook` field, if not specified in the CR or explicitly set to true, defaults to `false` or ``, preventing any `operator-webhook` pod from running in the namespace. The recommended setting is `true`. +where: -.. Create the resource by running the following command: +`metadata.name`:: Specifies the name of the SR-IOV Network Operator instance. The only valid name for the `SriovOperatorConfig` resource is `default` and the name must be in the namespace where the Operator is deployed. + +`spec.enableInjector`:: Specifies if any `network-resources-injector` pod can run in the namespace. If not specified in the CR or explicitly set to `true`, defaults to `false` or ``, preventing any `network-resources-injector` pod from running in the namespace. The recommended setting is `true`. + +`spec.enableOperatorWebhook`:: Specifies if any `operator-webhook` pods can run in the namespace. The `enableOperatorWebhook` field, if not specified in the CR or explicitly set to true, defaults to `false` or ``, preventing any `operator-webhook` pod from running in the namespace. The recommended setting is `true`. + +. Apply the resource to your cluster by running the following command: + [source,terminal] ---- $ oc apply -f sriovOperatorConfig.yaml ---- -[id="nw-sriov-operator-cr_{context}"] -== SR-IOV Network Operator config custom resource - -The fields for the `sriovoperatorconfig` custom resource are described in the following table: - -.SR-IOV Network Operator config custom resource -[cols=".^2,.^2,.^6a",options="header"] -|==== -|Field|Type|Description - -|`metadata.name` -|`string` -|Specifies the name of the SR-IOV Network Operator instance. -The default value is `default`. -Do not set a different value. - -|`metadata.namespace` -|`string` -|Specifies the namespace of the SR-IOV Network Operator instance. -The default value is `openshift-sriov-network-operator`. -Do not set a different value. - -|`spec.configDaemonNodeSelector` -|`string` -|Specifies the node selection to control scheduling the SR-IOV Network Config Daemon on selected nodes. -By default, this field is not set and the Operator deploys the SR-IOV Network Config daemon set on worker nodes. - -|`spec.disableDrain` -|`boolean` -|Specifies whether to disable the node draining process or enable the node draining process when you apply a new policy to configure the NIC on a node. -Setting this field to `true` facilitates software development and installing {product-title} on a single node. By default, this field is not set. - -For single-node clusters, set this field to `true` after installing the Operator. This field must remain set to `true`. - -|`spec.enableInjector` -|`boolean` -|Specifies whether to enable or disable the Network Resources Injector daemon set. - -|`spec.enableOperatorWebhook` -|`boolean` -|Specifies whether to enable or disable the Operator Admission Controller webhook daemon set. - -|`spec.logLevel` -|`integer` -|Specifies the log verbosity level of the Operator. By default, this field is set to `0`, which shows only basic logs. Set to `2` to show all the available logs. - -|`spec.featureGates` -|`map[string]bool` -|Specifies whether to enable or disable the optional features. For example, `metricsExporter`. - -|`spec.featureGates.metricsExporter` -|`boolean` -|Specifies whether to enable or disable the SR-IOV Network Operator metrics. By default, this field is set to `false`. - -|`spec.featureGates.mellanoxFirmwareReset` -|`boolean` -|Specifies whether to reset the firmware on virtual function (VF) changes in the SR-IOV Network Operator. Some chipsets, such as the Intel C740 Series, do not completely power off the PCI-E devices, which is required to configure VFs on NVIDIA/Mellanox NICs. By default, this field is set to `false`. - -:FeatureName: The `spec.featureGates.mellanoxFirmwareReset` parameter -include::snippets/technology-preview.adoc[] - -|==== - -[id="about-network-resource-injector_{context}"] -== About the Network Resources Injector - -The Network Resources Injector is a Kubernetes Dynamic Admission Controller application, which provides the following capabilities: - -* Mutation of resource requests and limits in a pod specification to add an SR-IOV resource name according to an SR-IOV network attachment definition annotation. -* Mutation of a pod specification with a Downward API volume to expose pod annotations, labels, and huge pages requests and limits. Containers that run in the pod can access the exposed information as files under the `/etc/podnetinfo` path. - -The Network Resources Injector is enabled by the SR-IOV Network Operator when the `enableInjector` is set to `true` in the `SriovOperatorConfig` CR. The `network-resources-injector` pod runs as a daemon set on all control plane nodes. The following is an example of Network Resources Injector pods running in a cluster with three control plane nodes: - -[source,terminal] ----- -$ oc get pods -n openshift-sriov-network-operator ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -network-resources-injector-5cz5p 1/1 Running 0 10m -network-resources-injector-dwqpx 1/1 Running 0 10m -network-resources-injector-lktz5 1/1 Running 0 10m ----- - -By default, the `failurePolicy` field in the Network Resources Injector webhook is set to `Ignore`. This default setting prevents pod creation from being blocked if the webhook is unavailable. - -If you set the `failurePolicy` field to `Fail`, and the Network Resources Injector webhook is unavailable, the webhook attempts to mutate all pod creation and update requests. This behavior can block pod creation and disrupt normal cluster operations. To prevent such issues, you can enable the `featureGates.resourceInjectorMatchCondition` feature in the `SriovOperatorConfig` object to limit the scope of the Network Resources Injector webhook. If this feature is enabled, the webhook applies only to pods with the secondary network annotation `k8s.v1.cni.cncf.io/networks`. - -If you set the `failurePolicy` field to `Fail` after enabling the `resourceInjectorMatchCondition` feature, the webhook applies only to pods with the secondary network annotation `k8s.v1.cni.cncf.io/networks`. If the webhook is unavailable, pods without this annotation are still deployed, preventing unnecessary disruptions to cluster operations. - -The `featureGates.resourceInjectorMatchCondition` feature is disabled by default. To enable this feature, set the `featureGates.resourceInjectorMatchCondition` field to `true` in the `SriovOperatorConfig` object. - -.Example `SriovOperatorConfig` object configuration -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovOperatorConfig -metadata: - name: default - namespace: sriov-network-operator -spec: -# ... - featureGates: - resourceInjectorMatchCondition: true -# ... ----- - -[id="disable-enable-network-resource-injector_{context}"] -== Disabling or enabling the Network Resources Injector - -To disable or enable the Network Resources Injector, complete the following procedure. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. -* You must have installed the SR-IOV Network Operator. - -.Procedure - -- Set the `enableInjector` field. Replace `` with `false` to disable the feature or `true` to enable the feature. -+ -[source,terminal] ----- -$ oc patch sriovoperatorconfig default \ - --type=merge -n openshift-sriov-network-operator \ - --patch '{ "spec": { "enableInjector": } }' ----- -+ -[TIP] -==== -You can alternatively apply the following YAML to update the Operator: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovOperatorConfig -metadata: - name: default - namespace: openshift-sriov-network-operator -spec: - enableInjector: ----- -==== - -[id="about-sr-iov-operator-admission-control-webhook_{context}"] -== About the SR-IOV Network Operator admission controller webhook - -The SR-IOV Network Operator Admission Controller webhook is a Kubernetes Dynamic Admission Controller application. It provides the following capabilities: - -* Validation of the `SriovNetworkNodePolicy` CR when it is created or updated. -* Mutation of the `SriovNetworkNodePolicy` CR by setting the default value for the `priority` and `deviceType` fields when the CR is created or updated. - -The SR-IOV Network Operator Admission Controller webhook is enabled by the Operator when the `enableOperatorWebhook` is set to `true` in the `SriovOperatorConfig` CR. The `operator-webhook` pod runs as a daemon set on all control plane nodes. - -[NOTE] -==== -Use caution when disabling the SR-IOV Network Operator Admission Controller webhook. You can disable the webhook under specific circumstances, such as troubleshooting, or if you want to use unsupported devices. For information about configuring unsupported devices, see link:https://access.redhat.com/articles/7010183[Configuring the SR-IOV Network Operator to use an unsupported NIC]. -==== - -The following is an example of the Operator Admission Controller webhook pods running in a cluster with three control plane nodes: - -[source,terminal] ----- -$ oc get pods -n openshift-sriov-network-operator ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -operator-webhook-9jkw6 1/1 Running 0 16m -operator-webhook-kbr5p 1/1 Running 0 16m -operator-webhook-rpfrl 1/1 Running 0 16m ----- - -[id="disable-enable-sr-iov-operator-admission-control-webhook_{context}"] -== Disabling or enabling the SR-IOV Network Operator admission controller webhook - -To disable or enable the admission controller webhook, complete the following procedure. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. -* You must have installed the SR-IOV Network Operator. - -.Procedure - -- Set the `enableOperatorWebhook` field. Replace `` with `false` to disable the feature or `true` to enable it: -+ -[source,terminal] ----- -$ oc patch sriovoperatorconfig default --type=merge \ - -n openshift-sriov-network-operator \ - --patch '{ "spec": { "enableOperatorWebhook": } }' ----- -+ -[TIP] -==== -You can alternatively apply the following YAML to update the Operator: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovOperatorConfig -metadata: - name: default - namespace: openshift-sriov-network-operator -spec: - enableOperatorWebhook: ----- -==== - -[id="about-custom-node-selectors_{context}"] -== About custom node selectors - -The SR-IOV Network Config daemon discovers and configures the SR-IOV network devices on cluster nodes. -By default, it is deployed to all the `worker` nodes in the cluster. -You can use node labels to specify on which nodes the SR-IOV Network Config daemon runs. - -[id="configuring-custom-nodeselector_{context}"] -== Configuring a custom NodeSelector for the SR-IOV Network Config daemon - -The SR-IOV Network Config daemon discovers and configures the SR-IOV network devices on cluster nodes. By default, it is deployed to all the `worker` nodes in the cluster. You can use node labels to specify on which nodes the SR-IOV Network Config daemon runs. - -To specify the nodes where the SR-IOV Network Config daemon is deployed, complete the following procedure. - -[IMPORTANT] -===== -When you update the `configDaemonNodeSelector` field, the SR-IOV Network Config daemon is recreated on each selected node. -While the daemon is recreated, cluster users are unable to apply any new SR-IOV Network node policy or create new SR-IOV pods. -===== - -.Procedure - -- To update the node selector for the operator, enter the following command: -+ -[source,terminal] ----- -$ oc patch sriovoperatorconfig default --type=json \ - -n openshift-sriov-network-operator \ - --patch '[{ - "op": "replace", - "path": "/spec/configDaemonNodeSelector", - "value": {} - }]' ----- -+ -Replace `` with a label to apply as in the following example: -`"node-role.kubernetes.io/worker": ""`. -+ -[TIP] -==== -You can alternatively apply the following YAML to update the Operator: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovOperatorConfig -metadata: - name: default - namespace: openshift-sriov-network-operator -spec: - configDaemonNodeSelector: - ----- -==== - -[id="configure-sr-iov-operator-single-node_{context}"] -== Configuring the SR-IOV Network Operator for single node installations - -By default, the SR-IOV Network Operator drains workloads from a node before every policy change. -The Operator performs this action to ensure that there no workloads using the virtual functions before the reconfiguration. - -For installations on a single node, there are no other nodes to receive the workloads. -As a result, the Operator must be configured not to drain the workloads from the single node. - -[IMPORTANT] -==== -After performing the following procedure to disable draining workloads, you must remove any workload that uses an SR-IOV network interface before you change any SR-IOV network node policy. -==== - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. -* You must have installed the SR-IOV Network Operator. - -.Procedure - -- To set the `disableDrain` field to `true` and the `configDaemonNodeSelector` field to `node-role.kubernetes.io/master: ""`, enter the following command: -+ -[source,terminal] ----- -$ oc patch sriovoperatorconfig default --type=merge -n openshift-sriov-network-operator --patch '{ "spec": { "disableDrain": true, "configDaemonNodeSelector": { "node-role.kubernetes.io/master": "" } } }' ----- -+ -[TIP] -==== -You can alternatively apply the following YAML to update the Operator: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovOperatorConfig -metadata: - name: default - namespace: openshift-sriov-network-operator -spec: - disableDrain: true - configDaemonNodeSelector: - node-role.kubernetes.io/master: "" ----- -==== diff --git a/modules/nw-sriov-operator-cr.adoc b/modules/nw-sriov-operator-cr.adoc new file mode 100644 index 0000000000..8fa1550ba0 --- /dev/null +++ b/modules/nw-sriov-operator-cr.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// * networking/hardware_networks/configuring-sriov-operator.adoc + +:_mod-docs-content-type: REFERENCE +[id="nw-sriov-operator-cr_{context}"] += SR-IOV Network Operator config custom resource + +[role="_abstract"] +To customize the SR-IOV Network Operator, configure the `sriovoperatorconfig` custom resource. The reference lists the parameters available for controlling the operator's global settings and deployment behavior. + +The following table describes the `sriovoperatorconfig` CR fields: + +.SR-IOV Network Operator config custom resource +[cols=".^2,.^2,.^6a",options="header"] +|==== +|Field|Type|Description + +|`metadata.name` +|`string` +|Specifies the name of the SR-IOV Network Operator instance. The default value is `default`. Do not set a different value. + +|`metadata.namespace` +|`string` +|Specifies the namespace of the SR-IOV Network Operator instance. The default value is `openshift-sriov-network-operator`. Do not set a different value. + +|`spec.configDaemonNodeSelector` +|`string` +|Specifies the node selection to control scheduling the SR-IOV Network Config Daemon on selected nodes. By default, this field is not set and the Operator deploys the SR-IOV Network Config daemon set on compute nodes. + +|`spec.disableDrain` +|`boolean` +|Specifies whether to disable the node draining process or enable the node draining process when you apply a new policy to configure the NIC on a node. Setting this field to `true` facilitates software development and installing {product-title} on a single node. By default, this field is not set. For single-node clusters, set this field to `true` after installing the Operator. This field must remain set to `true`. + +|`spec.enableInjector` +|`boolean` +|Specifies whether to enable or disable the Network Resources Injector daemon set. + +|`spec.enableOperatorWebhook` +|`boolean` +|Specifies whether to enable or disable the Operator Admission Controller webhook daemon set. + +|`spec.logLevel` +|`integer` +|Specifies the log verbosity level of the Operator. By default, this field is set to `0`, which shows only basic logs. Set to `2` to show all the available logs. + +|`spec.featureGates` +|`map[string]bool` +|Specifies whether to enable or disable the optional features. For example, `metricsExporter`. + +|`spec.featureGates.metricsExporter` +|`boolean` +|Specifies whether to enable or disable the SR-IOV Network Operator metrics. By default, this field is set to `false`. + +|`spec.featureGates.mellanoxFirmwareReset` +|`boolean` +|Specifies whether to reset the firmware on virtual function (VF) changes in the SR-IOV Network Operator. Some chipsets, such as the Intel C740 Series, do not completely power off the PCI-E devices, which is required to configure VFs on NVIDIA/Mellanox NICs. By default, this field is set to `false`. + +:FeatureName: The `spec.featureGates.mellanoxFirmwareReset` parameter +include::snippets/technology-preview.adoc[] + +|==== diff --git a/modules/sriov-network-metrics-exporter.adoc b/modules/sriov-network-metrics-exporter.adoc index f7584b4f97..23d06e5e54 100644 --- a/modules/sriov-network-metrics-exporter.adoc +++ b/modules/sriov-network-metrics-exporter.adoc @@ -6,11 +6,12 @@ [id="sriov-network-metrics-exporter_{context}"] = About the SR-IOV network metrics exporter -The Single Root I/O Virtualization (SR-IOV) network metrics exporter reads the metrics for SR-IOV virtual functions (VFs) and exposes these VF metrics in Prometheus format. When the SR-IOV network metrics exporter is enabled, you can query the SR-IOV VF metrics by using the {product-title} web console to monitor the networking activity of the SR-IOV pods. +[role="_abstract"] +To monitor the networking activity of SR-IOV pods, enable the SR-IOV network metrics exporter. This tool exposes metrics for SR-IOV virtual functions (VFs) in Prometheus format, so that you can query and visualize data through the {product-title} web console. When you query the SR-IOV VF metrics by using the web console, the SR-IOV network metrics exporter fetches and returns the VF network statistics along with the name and namespace of the pod that the VF is attached to. -The SR-IOV VF metrics that the metrics exporter reads and exposes in Prometheus format are described in the following table: +The following table describes the SR-IOV VF metrics that the metrics exporter reads and exposes in Prometheus format: .SR-IOV VF metrics [%autowidth,options="header"] @@ -29,7 +30,7 @@ The SR-IOV VF metrics that the metrics exporter reads and exposes in Prometheus |==== -You can also combine these queries with the kube-state-metrics to get more information about the SR-IOV pods. For example, you can use the following query to get the VF network statistics along with the application name from the standard Kubernetes pod label: +You can also combine these queries by using the `kube-state-metrics` tool to get more information about the SR-IOV pods. For example, you can use the following query to get the VF network statistics along with the application name from the standard Kubernetes pod label: [source,terminal] ---- diff --git a/modules/sriov-operator-metrics.adoc b/modules/sriov-operator-metrics.adoc index 92af4d409d..08921bf4fd 100644 --- a/modules/sriov-operator-metrics.adoc +++ b/modules/sriov-operator-metrics.adoc @@ -6,7 +6,8 @@ [id="sriov-operator-metrics_{context}"] = Enabling the SR-IOV network metrics exporter -The Single Root I/O Virtualization (SR-IOV) network metrics exporter is disabled by default. To enable the metrics exporter, you must set the `spec.featureGates.metricsExporter` field to `true`. +[role="_abstract"] +To enable the SR-IOV network metrics exporter, set the `spec.featureGates.metricsExporter` field to `true`. Because the exporter is disabled by default, you must explicitly activate this feature gate to start exposing metrics for your SR-IOV devices. [IMPORTANT] ==== @@ -57,6 +58,6 @@ sriov-network-metrics-exporter-z5d7t 1/1 Running 0 10s sriov-network-operator-cc6fd88bc-9bsmt 1/1 Running 0 5d22h ---- + -The `sriov-network-metrics-exporter` pod must be in the `READY` state. +Ensure that `sriov-network-metrics-exporter` pod is in the `READY` state. . Optional: Examine the SR-IOV virtual function (VF) metrics by using the {product-title} web console. For more information, see "Querying metrics". \ No newline at end of file diff --git a/networking/networking_operators/sr-iov-operator/configuring-sriov-operator.adoc b/networking/networking_operators/sr-iov-operator/configuring-sriov-operator.adoc index 98512f0f6d..693169ef5f 100644 --- a/networking/networking_operators/sr-iov-operator/configuring-sriov-operator.adoc +++ b/networking/networking_operators/sr-iov-operator/configuring-sriov-operator.adoc @@ -6,11 +6,38 @@ include::_attributes/common-attributes.adoc[] toc::[] -The Single Root I/O Virtualization (SR-IOV) Network Operator manages the SR-IOV network devices and network attachments in your cluster. +[role="_abstract"] +To manage SR-IOV network devices and network attachments in your cluster, use the Single Root I/O Virtualization (SR-IOV) Network Operator. // Configuring the SR-IOV Network Operator include::modules/nw-sriov-configuring-operator.adoc[leveloffset=+1] +// SR-IOV Network Operator config custom resource +include::modules/nw-sriov-operator-cr.adoc[leveloffset=+1] + +// About the Network Resources Injector +include::modules/about-network-resource-injector.adoc[leveloffset=+1] + +// Disabling or enabling the Network Resources Injector +include::modules/disable-enable-network-resource-injector.adoc[leveloffset=+1] + +// About the SR-IOV Network Operator admission controller webhook +include::modules/about-sr-iov-operator-admission-control-webhook.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* link:https://access.redhat.com/articles/7010183[Configuring the SR-IOV Network Operator to use an unsupported NIC] + +// Disabling or enabling the SR-IOV Network Operator admission controller webhook +include::modules/disable-enable-sr-iov-operator-admission-control-webhook.adoc[leveloffset=+1] + +//Configuring a custom NodeSelector for the SR-IOV Network Config daemon +include::modules/configuring-custom-nodeselector.adoc[leveloffset=+1] + +// Configuring the SR-IOV Network Operator for single node installations +include::modules/configure-sr-iov-operator-single-node.adoc[leveloffset=+1] + // Deploying the SR-IOV Operator for HCP include::modules/sriov-operator-hosted-control-planes.adoc[leveloffset=+2] @@ -24,11 +51,10 @@ include::modules/sriov-operator-metrics.adoc[leveloffset=+2] .Additional resources * link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.21/html/accessing_metrics/accessing-metrics-as-an-administrator#querying-metrics-for-all-projects-with-mon-dashboard_accessing-metrics-as-an-administrator[Querying metrics for all projects with the monitoring dashboard] + * link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.21/html/accessing_metrics/accessing-metrics-as-a-developer#querying-metrics-for-user-defined-projects-with-mon-dashboard_accessing-metrics-as-a-developer[Querying metrics for user-defined projects as a developer] -[id="configuring-sriov-operator-next-steps"] -== Next steps - * xref:../../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV network device] -* Optional: xref:../../../networking/networking_operators/sr-iov-operator/uninstalling-sriov-operator.adoc#uninstalling-sriov-operator[Uninstalling the SR-IOV Network Operator] + +* xref:../../../networking/networking_operators/sr-iov-operator/uninstalling-sriov-operator.adoc#uninstalling-sriov-operator[Uninstalling the SR-IOV Network Operator]