Network Operator API reference v1alpha1
Packages:
Package v1alpha1 contains API Schema definitions for the configuration.net v1alpha1 API group
Resource Types:
ConfigurationTemplateSpec
(Appears on: NicConfigurationTemplateSpec, NicDeviceConfigurationSpec)
ConfigurationTemplateSpec is a set of configurations for the NICs
Field | Description |
|---|---|
numVfs
int |
Number of VFs to be configured |
linkType
LinkTypeEnum |
(Optional) LinkType to be configured, Ethernet|Infiniband. Required unless networkBay is configured; for Network Bay the link type is governed by the system configuration and must not be set. |
pciPerformanceOptimized
PciPerformanceOptimizedSpec |
PCI performance optimization settings |
roceOptimized
RoceOptimizedSpec |
RoCE optimization settings |
gpuDirectOptimized
GpuDirectOptimizedSpec |
GPU Direct optimization settings |
runtimePerformanceOptimized
RuntimePerformanceOptimizedSpec |
Runtime NIC performance tuning (ring buffers, channels, LRO) applied via ethtool |
spectrumXOptimized
SpectrumXOptimizedSpec |
Spectrum-X optimization settings. Works only with linkType==Ethernet && numVfs==1. RawNvConfig parameters, if provided, are merged as overrides on top of Spectrum-X calculated params. |
networkBay
NetworkBaySpec |
(Optional) NetworkBay configures a ConnectX-9 Network Bay card (per-ASIC set_system_conf). Allowed only for ConnectX-9 (nicType 1025). |
rawNvConfig
[]NvConfigParam |
List of arbitrary nv config parameters |
force
bool |
(Optional)
Force passes --force to mlxconfig set commands. When set, the daemon applies the nv config
batch and set_system_conf with –force, letting mlxconfig accept a batch it would otherwise refuse
due to implicit parameter dependencies. |
ECNSpec
(Appears on: QosSpec)
ECNSpec specifies Explicit Congestion Notification settings
Field | Description |
|---|---|
enabled
bool |
Enable ECN on the specified priority |
priority
int |
Traffic class / priority to enable ECN on (0-7) |
FirmwareTemplateSpec
(Appears on: NicDeviceSpec, NicFirmwareTemplateSpec)
FirmwareTemplateSpec specifies a FW update policy for a given FW source ref
Field | Description |
|---|---|
nicFirmwareSourceRef
string |
NicFirmwareSourceRef refers to existing NicFirmwareSource CR on where to get the FW from |
updatePolicy
string |
UpdatePolicy indicates whether the operator needs to validate installed FW or upgrade it |
GpuDirectOptimizedSpec
(Appears on: ConfigurationTemplateSpec)
GpuDirectOptimizedSpec specifies GPU Direct optimization settings
Field | Description |
|---|---|
enabled
bool |
Optimize GPU Direct |
env
string |
GPU direct environment, e.g. Baremetal |
LinkTypeEnum (
string
alias)
(Appears on: ConfigurationTemplateSpec)
LinkTypeEnum described the link type (Ethernet / Infiniband)
NetworkBaySpec
(Appears on: ConfigurationTemplateSpec)
NetworkBaySpec configures a ConnectX-9 Network Bay (“orchid”) card. A Network Bay card exposes two CX9 ASICs as two PCI endpoints that share a single OSFP cage and must be configured as a pair. Allowed only when nicSelector.nicType == “1025” (ConnectX-9), enforced by CEL on NicConfigurationTemplateSpec.
Field | Description |
|---|---|
conf
string |
Conf is the argument passed to mlxconfig set_system_conf. The per-ASIC index is appended
automatically by the daemon based on the device’s detected Network Bay ASIC index, e.g.
set_system_conf [0]. |
NicConfigurationTemplate
NicConfigurationTemplate is the Schema for the nicconfigurationtemplates API
Field | Description |
|---|---|
metadata
Kubernetes
meta/v1.ObjectMeta |
Refer to the Kubernetes API documentation for the fields of the metadata field. |
spec
NicConfigurationTemplateSpec |
Defines the desired state of NICs |
status
NicTemplateStatus |
Defines the observed state of NicConfigurationTemplate |
NicConfigurationTemplateSpec
(Appears on: NicConfigurationTemplate)
NicConfigurationTemplateSpec defines the desired state of NicConfigurationTemplate
Field | Description |
|---|---|
nodeSelector
map[string]string |
NodeSelector contains labels required on the node. When empty, the template will be applied to matching devices on all nodes. |
nicSelector
NicSelectorSpec |
NIC selector configuration |
resetToDefault
bool |
(Optional) ResetToDefault specifies whether node agent needs to perform a reset flow The following operations will be performed: * Nvconfig reset of all non-volatile configurations - Mstconfig -d reset for each PF - Mstconfig -d set ADVANCED_PCI_SETTINGS=1 * Node reboot - Applies new NIC NV config - Will undo any runtime configuration previously performed for the device/driver |
template
ConfigurationTemplateSpec |
Configuration template to be applied to matching devices |
NicDevice
NicDevice is the Schema for the nicdevices API
Field | Description |
|---|---|
metadata
Kubernetes
meta/v1.ObjectMeta |
Refer to the Kubernetes API documentation for the fields of the metadata field. |
spec
NicDeviceSpec |
|
status
NicDeviceStatus |
NicDeviceConfigurationSpec
(Appears on: NicDeviceSpec)
NicDeviceConfigurationSpec contains desired configuration of the NIC
Field | Description |
|---|---|
resetToDefault
bool |
ResetToDefault specifies whether node agent needs to perform a reset flow. The following operations will be performed: * Nvconfig reset of all non-volatile configurations - Mstconfig -d reset for each PF - Mstconfig -d set ADVANCED_PCI_SETTINGS=1 * Node reboot - Applies new NIC NV config - Will undo any runtime configuration previously performed for the device/driver |
template
ConfigurationTemplateSpec |
Configuration template applied from the NicConfigurationTemplate CR |
NicDeviceInterfaceNameSpec
(Appears on: NicDeviceSpec)
Field | Description |
|---|---|
nicIndex
int |
NicIndex is the index of the NIC in the flattened list of NICs based on the Template |
railIndex
int |
RailIndex is the index of the rail where the given NIC belongs to based on the Template |
planeIndices
[]int |
PlaneIndices is the indices of the planes for the given NIC based on the Template |
rdmaDevicePrefix
string |
— Parameters from the NicInterfaceNameTemplate CR — RdmaDevicePrefix specifies the prefix for the rdma device name. Empty means RDMA naming is skipped. |
netDevicePrefix
string |
NetDevicePrefix specifies the prefix for the net device name |
NicDeviceNetworkBayStatus
(Appears on: NicDeviceStatus)
NicDeviceNetworkBayStatus holds the ConnectX-9 Network Bay identity of a device.
Field | Description |
|---|---|
asic
int |
Asic is the orchid ASIC index (0 or 1) inferred from the MGIR.ga register field. |
peerPci
string |
(Optional) PeerPCI is the PCI address of the sibling ASIC in the same Network Bay card (the other device sharing this device’s serial number). Empty if the peer could not be resolved. |
NicDevicePortSpec
(Appears on: NicDeviceStatus)
NicDevicePortSpec describes the ports of the NIC
Field | Description |
|---|---|
pci
string |
PCI is a PCI address of the port, e.g. 0000:3b:00.0 |
fwctlDevice
string |
(Optional) FwctlDevice is the fwctl character device path for this port, e.g. /dev/fwctl/fwctl0. Empty when the host does not expose a fwctl device for this PCI function. |
networkInterface
string |
NetworkInterface is the name of the network interface for this port, e.g. eth1 |
rdmaInterface
string |
RdmaInterface is the name of the rdma interface for this port, e.g. mlx5_1 |
NicDeviceSpec
(Appears on: NicDevice)
NicDeviceSpec defines the desired state of NicDevice
Field | Description |
|---|---|
configuration
NicDeviceConfigurationSpec |
Configuration specifies the configuration requested by NicConfigurationTemplate |
firmware
FirmwareTemplateSpec |
Firmware specifies the fw upgrade policy requested by NicFirmwareTemplate |
interfaceNameTemplate
NicDeviceInterfaceNameSpec |
InterfaceNameTemplate specifies the interface name template to be applied to the NIC |
NicDeviceStatus
(Appears on: NicDevice)
NicDeviceStatus defines the observed state of NicDevice
Field | Description |
|---|---|
node
string |
Node where the device is located |
type
string |
Type of device, e.g. ConnectX7 |
serialNumber
string |
SerialNumber of the device, e.g. MT2116X09299. Informational only — not guaranteed unique across
all cards on a host: on systems with embedded NICs sharing a flashed VPD image (e.g. HGX B300)
multiple cards will report the same serial number. The operator identifies NICs uniquely by their
PCI device address (the pci field on the first entry in ports, with the function digit
stripped). |
partNumber
string |
Part number of the device, e.g. MCX713106AEHEA_QP1 |
psid
string |
Product Serial ID of the device, e.g. MT_0000000221 |
firmwareVersion
string |
Firmware version currently installed on the device, e.g. 22.31.1014 |
dpu
bool |
DPU indicates if the device is a BlueField in DPU mode |
modelName
string |
ModelName is the model name of the device, e.g. ConnectX-6 or BlueField-3 |
superNIC
bool |
SuperNIC indicates if the device is a SuperNIC |
ports
[]NicDevicePortSpec |
List of ports for the device |
networkBay
NicDeviceNetworkBayStatus |
(Optional) NetworkBay holds ConnectX-9 Network Bay (“orchid”) identity for the device. Set only when the device is detected as part of a Network Bay card. |
conditions
[]Kubernetes
meta/v1.Condition |
List of conditions observed for the device |
NicFirmwareSource
NicFirmwareSource is the Schema for the nicfirmwaresources API
Field | Description |
|---|---|
metadata
Kubernetes
meta/v1.ObjectMeta |
Refer to the Kubernetes API documentation for the fields of the metadata field. |
spec
NicFirmwareSourceSpec |
|
status
NicFirmwareSourceStatus |
NicFirmwareSourceSpec
(Appears on: NicFirmwareSource)
NicFirmwareSourceSpec represents a list of url sources for FW
Field | Description |
|---|---|
binUrlSources
[]string |
(Optional) BinUrlSources represents a list of url sources for ConnectX Firmware |
bfbUrlSource
string |
(Optional) BFBUrlSource represents a url source for BlueField Bundle |
docaSpcXCCUrlSource
string |
(Optional) DocaSpcXCCUrlSource represents a url source for DOCA SPC-X CC .deb package for ubuntu 22.04 Will be removed in the future, once Doca SPC-X CC algorithm will be publicly available |
NicFirmwareSourceStatus
(Appears on: NicFirmwareSource)
NicFirmwareSourceStatus represents the status of the FW from given sources, e.g. version available for PSIDs
Field | Description |
|---|---|
state
string |
State represents the firmware processing state |
reason
string |
Reason shows an error message if occurred |
binaryVersions
map[string][]string |
Versions is a map of available FW binaries versions to PSIDs a PSID should have only a single FW version available for it |
bfbVersions
map[string]string |
BFBVersions represents the FW versions available in the provided BFB bundle |
docaSpcXCCVersion
string |
DocaSpcXCCVersion represents the FW versions available in the provided DOCA SPC-X CC .deb package for ubuntu 22.04 |
NicFirmwareTemplate
NicFirmwareTemplate is the Schema for the nicfirmwaretemplates API
Field | Description |
|---|---|
metadata
Kubernetes
meta/v1.ObjectMeta |
Refer to the Kubernetes API documentation for the fields of the metadata field. |
spec
NicFirmwareTemplateSpec |
|
status
NicTemplateStatus |
NicFirmwareTemplateSpec
(Appears on: NicFirmwareTemplate)
NicFirmwareTemplateSpec defines the FW templates and node/nic selectors for it
Field | Description |
|---|---|
nodeSelector
map[string]string |
NodeSelector contains labels required on the node. When empty, the template will be applied to matching devices on all nodes. |
nicSelector
NicSelectorSpec |
NIC selector configuration |
template
FirmwareTemplateSpec |
Firmware update template |
NicInterfaceNameTemplate
NicInterfaceNameTemplate is the Schema for the nicinterfacenametemplates API
Field | Description |
|---|---|
metadata
Kubernetes
meta/v1.ObjectMeta |
Refer to the Kubernetes API documentation for the fields of the metadata field. |
spec
NicInterfaceNameTemplateSpec |
|
status
NicInterfaceNameTemplateStatus |
NicInterfaceNameTemplateSpec
(Appears on: NicInterfaceNameTemplate)
NicInterfaceNameTemplateSpec defines the desired state of NicInterfaceNameTemplate
Field | Description |
|---|---|
nodeSelector
map[string]string |
NodeSelector contains labels required on the node. When empty, the template will be applied to matching devices on all nodes. |
pfsPerNic
int |
PfsPerNic specifies the number of PFs per NIC Used to calculate the number of planes per NIC |
rdmaDevicePrefix
string |
(Optional) RdmaDevicePrefix specifies the prefix for the rdma device name. When empty, no RDMA udev rules are generated and RDMA device naming is skipped. %nic_id%, %plane_id% and %rail_id% placeholders can be used to construct the device name %nic_id% is the index of the NIC in the flattened list of NICs %plane_id% is the index of the plane of the specific NIC %rail_id% is the index of the rail where the given NIC belongs to |
netDevicePrefix
string |
NetDevicePrefix specifies the prefix for the net device name %nic_id%, %plane_id% and %rail_id% placeholders can be used to construct the device name %nic_id% is the index of the NIC in the flattened list of NICs %plane_id% is the index of the plane of the specific NIC %rail_id% is the index of the rail where the given NIC belongs to |
railPciAddresses
[]string |
RailPciAddresses defines the PCI address to rail mapping and order The first dimension is the rail index, the second dimension is the PCI addresses of the NICs in the rail. The PCI addresses must be sorted in the order of the rails. Example: [[“0000:1a:00.0”, “0000:2a:00.0”], [“0000:3a:00.0”, “0000:4a:00.0”]] specifies 2 rails with 2 NICs each. |
NicInterfaceNameTemplateStatus
(Appears on: NicInterfaceNameTemplate)
NicInterfaceNameTemplateStatus defines the observed state of NicInterfaceNameTemplate
NicSelectorSpec
(Appears on: NicConfigurationTemplateSpec, NicFirmwareTemplateSpec)
NicSelectorSpec is a desired configuration for NICs
Field | Description |
|---|---|
nicType
string |
Type of the NIC to be selected, e.g. 101d,1015,a2d6 etc. |
pciAddresses
[]string |
Array of PCI addresses to be selected, e.g. “0000:03:00.0” |
serialNumbers
[]string |
Serial numbers of the NICs to be selected, e.g. MT2116X09299. Note: serial numbers are not
guaranteed unique — on systems with embedded NICs that share a flashed VPD image (e.g. HGX B300),
multiple physical cards report the same serial, and this selector will match all of them. Use
pciAddresses for precise per-card selection on such systems. |
partNumbers
[]string |
Part numbers of the NICs to be selected, e.g. MCX713106AEHEA_QP1 |
NicTemplateStatus
(Appears on: NicConfigurationTemplate, NicFirmwareTemplate)
NicTemplateStatus defines the observed state of NicConfigurationTemplate and NicFirmwareTemplate
Field | Description |
|---|---|
nicDevices
[]string |
NicDevice CRs matching this configuration / firmware template |
conditions
[]Kubernetes
meta/v1.Condition |
Conditions observed for this template, e.g. a Network Bay pairing imbalance on a node |
NvConfigParam
(Appears on: ConfigurationTemplateSpec)
Field | Description |
|---|---|
name
string |
Name of the arbitrary nvconfig parameter |
value
string |
Value of the arbitrary nvconfig parameter |
PauseFramesSpec
(Appears on: QosSpec)
PauseFramesSpec specifies global pause frame settings
Field | Description |
|---|---|
enabled
bool |
Enable global pause frames (autoneg, rx, tx). Set to false to disable all pause frames (recommended when PFC is used). |
PciPerformanceOptimizedSpec
(Appears on: ConfigurationTemplateSpec)
PciPerformanceOptimizedSpec specifies PCI performance optimization settings
Field | Description |
|---|---|
enabled
bool |
Specifies whether to enable PCI performance optimization |
maxAccOutRead
int |
Deprecated: this field is ignored and no longer maps to MAX_ACC_OUT_READ. |
maxReadRequest
int |
Specifies the size of a single PCI read request in bytes |
QosSpec
(Appears on: RoceOptimizedSpec)
QosSpec specifies Quality of Service settings
Field | Description |
|---|---|
trust
string |
Trust mode for QoS settings, e.g. dscp |
pfc
string |
Priority-based Flow Control configuration, e.g. “0,0,0,1,0,0,0,0” |
tos
int |
8-bit value for type of service |
cableLen
int |
Cable length in meters, used for ECN buffer threshold calculation |
ecn
ECNSpec |
ECN (Explicit Congestion Notification) settings |
pauseFrames
PauseFramesSpec |
Global pause frame settings (disable when using PFC) |
RoceOptimizedSpec
(Appears on: ConfigurationTemplateSpec)
RoceOptimizedSpec specifies RoCE optimization settings
Field | Description |
|---|---|
enabled
bool |
Optimize RoCE |
qos
QosSpec |
Quality of Service settings |
roceMode
int |
RoCE mode: 1 for RoCE v1, 2 for RoCE v2. Only effective when roceOptimized.enabled is true. |
RuntimePerformanceOptimizedSpec
(Appears on: ConfigurationTemplateSpec)
RuntimePerformanceOptimizedSpec specifies runtime NIC performance tuning applied via ethtool
Field | Description |
|---|---|
enabled
bool |
Enable runtime performance optimization |
rxRingSize
int |
RX ring buffer size (ethtool -G rx) |
txRingSize
int |
TX ring buffer size (ethtool -G tx) |
combinedChannels
int |
Number of combined channels (ethtool -L combined) |
lro
bool |
Enable Large Receive Offload (ethtool -K lro) |
SpectrumXOptimizedSpec
(Appears on: ConfigurationTemplateSpec)
SpectrumXOptimizedSpec enables Spectrum-X specific optimizations
Field | Description |
|---|---|
enabled
bool |
Optimize Spectrum X |
version
string |
Version of the Spectrum-X architecture to optimize for. Should match the name of the config map with Spectrum-X profile |
overlay
string |
(Optional) Overlay mode to be configured Can be “l3” or “none” |
multiplaneMode
string |
(Optional) Multiplane mode to be configured Can be “none”, “swplb”, “hwplb”, or “uniplane” |
numberOfPlanes
int |
(Optional) Number of planes to be configured |