// Module included in the following assemblies:
//
// * networking/hardware_networks/configuring-sriov-device.adoc

:_mod-docs-content-type: REFERENCE
[id="nw-sriov-networknodepolicy-object_{context}"]
= SR-IOV network node configuration object

[role="_abstract"]
You specify the SR-IOV network device configuration for a node by creating an SR-IOV network node policy. The API object for the policy is part of the `sriovnetwork.openshift.io` API group.

The following YAML describes an SR-IOV network node policy:

[source,yaml]
----
apiVersion: sriovnetwork.openshift.io/v1
kind: SriovNetworkNodePolicy
metadata:
  name: <name>
  namespace: openshift-sriov-network-operator
spec:
  resourceName: <sriov_resource_name>
  nodeSelector:
    feature.node.kubernetes.io/network-sriov.capable: "true"
  priority: <priority>
  mtu: <mtu>
  needVhostNet: false
  numVfs: <num>
  externallyManaged: false
  nicSelector:
    vendor: "<vendor_code>"
    deviceID: "<device_id>"
    pfNames: ["<pf_name>", ...]
    rootDevices: ["<pci_bus_id>", ...]
    netFilter: "<filter_string>"
  deviceType: <device_type>
  isRdma: false
  linkType: <link_type>
  eSwitchMode: "switchdev"
  excludeTopology: false
----

where:

--
`metadata.name`:: Specifies the name for the custom resource object.
`metadata.namespace`:: Specifies the namespace where the SR-IOV Network Operator is installed.
`spec.resourceName`:: Specifies the resource name of the SR-IOV network device plugin. You can create multiple SR-IOV network node policies for a resource name. When specifying a name, be sure to use the accepted syntax expression `^[a-zA-Z0-9_]+$`.
`spec.nodeSelector`:: Specifies the nodes to configure. Only SR-IOV network devices on the selected nodes are configured. The SR-IOV Container Network Interface (CNI) plugin and device plugin are deployed on selected nodes only.
+
[IMPORTANT]
====
The SR-IOV Network Operator applies node network configuration policies to nodes in sequence. Before applying node network configuration policies, the SR-IOV Network Operator checks if the machine config pool (MCP) for a node is in an unhealthy state such as `Degraded` or `Updating`. If a node is in an unhealthy MCP, the process of applying node network configuration policies to all targeted nodes in the cluster pauses until the MCP returns to a healthy state.

To avoid a node in an unhealthy MCP from blocking the application of node network configuration policies to other nodes, including nodes in other MCPs, you must create a separate node network configuration policy for each MCP.
====
`spec.priority`:: Optional: Specifies the priority as an integer value between `0` and `99`. A smaller value receives higher priority. For example, a priority of `10` is a higher priority than `99`. The default value is `99`.
`spec.mtu`:: Optional: Specifies the maximum transmission unit (MTU) of the physical function and all its virtual functions. The maximum MTU value can vary for different network interface controller (NIC) models.
+
[IMPORTANT]
====
If you want to create virtual function on the default network interface, ensure that the MTU is set to a value that matches the cluster MTU.

If you want to modify the MTU of a single virtual function while the function is assigned to a pod, leave the MTU value blank in the SR-IOV network node policy.
Otherwise, the SR-IOV Network Operator reverts the MTU of the virtual function to the MTU value defined in the SR-IOV network node policy, which might trigger a node drain.
====
`spec.needVhostNet`:: Optional: Set to `true` to mount the `/dev/vhost-net` device in the pod. Use the mounted `/dev/vhost-net` device with Data Plane Development Kit (DPDK) to forward traffic to the kernel network stack.
`spec.numVfs`:: Specifies the number of the virtual functions (VF) to create for the SR-IOV physical network device. For an Intel network interface controller (NIC), the number of VFs cannot be larger than the total VFs supported by the device. For a Mellanox NIC, the number of VFs cannot be larger than `127`.
`spec.externallyManaged`:: Indicates whether the SR-IOV Network Operator manages all, or only a subset of virtual functions (VFs). With the value set to `false` the SR-IOV Network Operator manages and configures all VFs on the PF.
+
[NOTE]
====
When `externallyManaged` is set to `true`, you must manually create the Virtual Functions (VFs) on the physical function (PF) before applying the `SriovNetworkNodePolicy` resource. If the VFs are not pre-created, the SR-IOV Network Operator's webhook will block the policy request.

When `externallyManaged` is set to `false`, the SR-IOV Network Operator automatically creates and manages the VFs, including resetting them if necessary.

To use VFs on the host system, you must create them through NMState, and set `externallyManaged` to `true`. In this mode, the SR-IOV Network Operator does not modify the PF or the manually managed VFs, except for those explicitly defined in the `nicSelector` field of your policy. However, the SR-IOV Network Operator continues to manage VFs that are used as pod secondary interfaces.
====
`spec.nicSelector`:: Identifies the device to which this resource applies. You do not have to specify values for all the parameters. It is recommended to identify the network device with enough precision to avoid selecting a device unintentionally.
+
If you specify `rootDevices`, you must also specify a value for `vendor`, `deviceID`, or `pfNames`. If you specify both `pfNames` and `rootDevices` at the same time, ensure that they refer to the same device. If you specify a value for `netFilter`, then you do not need to specify any other parameter because a network ID is unique.
`spec.nicSelector.vendor`:: Optional: Specifies the vendor hexadecimal identifier of the SR-IOV network device. The only allowed values are `8086` (Intel) and `15b3` (Mellanox).
`spec.nicSelector.deviceID`:: Optional: Specifies the device hexadecimal identifier of the SR-IOV network device. For example, `101b` is the device ID for a Mellanox ConnectX-6 device.
`spec.nicSelector.pfNames`:: Optional: Specifies an array of one or more physical function (PF) names the resource must apply to. You can specify either the kernel-assigned interface name or an alternative name configured through the Kubernetes NMState Operator.
`spec.nicSelector.rootDevices`:: Optional: Specifies an array of one or more PCI bus addresses the resource must apply to. For example `0000:02:00.1`.
`spec.nicSelector.netFilter`:: Optional: Specifies the platform-specific network filter. The only supported platform is {rh-openstack-first}. Acceptable values use the following format: `openstack/NetworkID:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. Replace `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` with the value from the `/var/config/openstack/latest/network_data.json` metadata file. This filter ensures that VFs are associated with a specific OpenStack network. The operator uses this filter to map the VFs to the appropriate network based on metadata provided by the OpenStack platform.
`spec.deviceType`:: Optional: Specifies the driver to configure for the VFs created from this resource. The only allowed values are `netdevice` and `vfio-pci`. The default value is `netdevice`.
+
For a Mellanox NIC to work in DPDK mode on bare-metal nodes, use the `netdevice` driver type and set `isRdma` to `true`.
`spec.isRdma`:: Optional: Configures whether to enable remote direct memory access (RDMA) mode. The default value is `false`.
+
If the `isRdma` parameter is set to `true`, you can continue to use the RDMA-enabled VF as a normal network device. A device can be used in either mode.
+
Set `isRdma` to `true` and additionally set `needVhostNet` to `true` to configure a Mellanox NIC for use with Fast data path DPDK applications.
+
[NOTE]
====
You cannot set the `isRdma` parameter to `true` for Intel NICs.
====
`spec.linkType`:: Optional: Specifies the link type for the VFs. The default value is `eth` for Ethernet. Change this value to 'ib' for InfiniBand.
+
When `linkType` is set to `ib`, `isRdma` is automatically set to `true` by the SR-IOV Network Operator webhook. When `linkType` is set to `ib`, `deviceType` should not be set to `vfio-pci`.
+
Do not set `linkType` to `eth` for `SriovNetworkNodePolicy`, because this can lead to an incorrect number of available devices reported by the device plugin.
`spec.eSwitchMode`:: Optional: Set to `"switchdev"` to enable hardware offloading. For more information about hardware offloading, see "Configuring hardware offloading".
`spec.excludeTopology`:: Optional: Set to `true` to exclude advertising an SR-IOV network resource's NUMA node to the Topology Manager. The default value is `false`.
--
