# mellanox/network-operator architecture

> Architecture diagram of the GitHub repository mellanox/network-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mellanox/network-operator
- Repository: https://github.com/mellanox/network-operator

## Overview

NVIDIA Network Operator reconciles Kubernetes networking custom resources into cluster components and secondary-network resources. The main workflow is a NICClusterPolicy or NICNodePolicy being validated, reconciled, and synchronized through state managers; controllers then report applied status. Separate controllers reconcile Macvlan, HostDevice, and IPoIB network resources. The README documents driver, device-plugin, CNI, IPAM, and NIC-configuration capabilities. Several implementation files are unsampled, so their internal wiring is omitted or marked unverified.

Main entry points: [`controllers/nicclusterpolicy_controller.go`](https://github.com/mellanox/network-operator/blob/master/controllers/nicclusterpolicy_controller.go) (Cluster policy), [`pkg/state/manager.go`](https://github.com/mellanox/network-operator/blob/master/pkg/state/manager.go) (State manager), [`controllers/nicnodepolicy_controller.go`](https://github.com/mellanox/network-operator/blob/master/controllers/nicnodepolicy_controller.go) (Node policy), [`main.go`](https://github.com/mellanox/network-operator/blob/master/main.go) (Operator startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control"]
  node_operator["Operator startup<br/>[main.go]"]
end

subgraph group_policy["Policy lifecycle"]
  node_clusterpolicy["Cluster policy"]
  node_nodepolicy["Node policy"]
  node_policyvalidation["Policy validation"]
end

subgraph group_components["Managed components"]
  node_state_manager["State manager<br/>[manager.go]"]
  node_ofed["OFED driver<br/>[state_ofed.go]"]
  node_rdma["RDMA plugin"]
  node_state_skel["State framework<br/>[state_skel.go]"]
  node_sriov["SR-IOV plugin<br/>[state_sriov_dp.go]"]
  node_ib["IB Kubernetes"]
  node_multus["Multus CNI"]
  node_cni["CNI plugins"]
  node_ipoib_cni["IPoIB CNI<br/>[state_ipoib_cni.go]"]
  node_ipam["NV IPAM"]
  node_nic_config["NIC configuration"]
  node_doca["DOCA images<br/>[doca_drivers.go]"]
end

subgraph group_networks["Secondary networks"]
  node_mac_controller["Macvlan reconciler"]
  node_mac_state["Macvlan state"]
  node_host_controller["Host-device reconciler"]
  node_host_state["Host-device state"]
  node_ipoib_controller["IPoIB reconciler"]
  node_ipoib_state["IPoIB state"]
end

subgraph group_maintenance["Node maintenance"]
  node_upgrade["Upgrade coordinator"]
  node_drain_controller["Drain controller"]
  node_drain_requestor["Drain requestor<br/>[drain_requestor.go]"]
end

node_kubernetes[("Kubernetes API")]
node_cluster_user(("Cluster operator"))

node_cluster_user -->|"submits policies"| node_kubernetes
node_kubernetes -->|"watches policy"| node_clusterpolicy
node_kubernetes -->|"watches policy"| node_nodepolicy
node_operator -->|"registers controller"| node_clusterpolicy
node_operator -->|"registers controller"| node_nodepolicy
node_policyvalidation -.->|"validates spec"| node_clusterpolicy
node_clusterpolicy -->|"syncs states"| node_state_manager
node_nodepolicy -.->|"syncs states"| node_state_manager
node_state_manager -.->|"syncs state"| node_ofed
node_state_manager -.->|"syncs state"| node_rdma
node_state_manager -.->|"uses framework"| node_state_skel
node_clusterpolicy -->|"uses image provider"| node_doca
node_clusterpolicy -.->|"configures component"| node_sriov
node_clusterpolicy -.->|"configures component"| node_ib
node_clusterpolicy -.->|"configures component"| node_multus
node_clusterpolicy -.->|"configures component"| node_cni
node_clusterpolicy -.->|"configures component"| node_ipoib_cni
node_clusterpolicy -.->|"configures component"| node_ipam
node_clusterpolicy -.->|"configures component"| node_nic_config
node_kubernetes -.->|"watches network"| node_mac_controller
node_mac_controller -.->|"syncs state"| node_mac_state
node_kubernetes -->|"watches network"| node_host_controller
node_host_controller -->|"syncs state"| node_host_state
node_kubernetes -.->|"watches network"| node_ipoib_controller
node_ipoib_controller -.->|"syncs state"| node_ipoib_state
node_kubernetes -.->|"provides policy events"| node_upgrade
node_drain_controller -->|"creates requestor"| node_drain_requestor
node_drain_controller -->|"updates maintenance state"| node_kubernetes
node_cluster_user -.->|"requests node drain"| node_kubernetes

click node_operator "https://github.com/mellanox/network-operator/blob/master/main.go"
click node_clusterpolicy "https://github.com/mellanox/network-operator/blob/master/controllers/nicclusterpolicy_controller.go"
click node_nodepolicy "https://github.com/mellanox/network-operator/blob/master/controllers/nicnodepolicy_controller.go"
click node_policyvalidation "https://github.com/mellanox/network-operator/blob/master/api/v1alpha1/validator/nicpolicy_webhook.go"
click node_state_manager "https://github.com/mellanox/network-operator/blob/master/pkg/state/manager.go"
click node_ofed "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ofed.go"
click node_rdma "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_rdma_shared_device_plugin.go"
click node_state_skel "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_skel.go"
click node_sriov "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_sriov_dp.go"
click node_ib "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ib_kubernetes.go"
click node_multus "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_multus_cni.go"
click node_cni "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_cni_plugins.go"
click node_ipoib_cni "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ipoib_cni.go"
click node_ipam "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_nv_ipam_cni.go"
click node_nic_config "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_nic_configuration_operator.go"
click node_doca "https://github.com/mellanox/network-operator/blob/master/pkg/docadriverimages/doca_drivers.go"
click node_mac_controller "https://github.com/mellanox/network-operator/blob/master/controllers/macvlannetwork_controller.go"
click node_mac_state "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_macvlan_network.go"
click node_host_controller "https://github.com/mellanox/network-operator/blob/master/controllers/hostdevicenetwork_controller.go"
click node_host_state "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_hostdevice_network.go"
click node_ipoib_controller "https://github.com/mellanox/network-operator/blob/master/controllers/ipoibnetwork_controller.go"
click node_ipoib_state "https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ipoib_network.go"
click node_upgrade "https://github.com/mellanox/network-operator/blob/master/controllers/upgrade_controller.go"
click node_drain_controller "https://github.com/mellanox/network-operator/blob/master/controllers/drain_controller.go"
click node_drain_requestor "https://github.com/mellanox/network-operator/blob/master/pkg/drain/drain_requestor.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_operator toneBlue
class node_clusterpolicy,node_nodepolicy,node_policyvalidation,node_kubernetes toneAmber
class node_state_manager,node_ofed,node_rdma,node_state_skel,node_sriov,node_ib,node_multus,node_cni,node_ipoib_cni,node_ipam,node_nic_config,node_doca toneMint
class node_mac_controller,node_mac_state,node_host_controller,node_host_state,node_ipoib_controller,node_ipoib_state toneRose
class node_upgrade,node_drain_controller,node_drain_requestor,node_cluster_user toneIndigo
```

## Components

### Operator control

- [Operator startup](https://github.com/mellanox/network-operator/blob/master/main.go): `main.go`

### Policy lifecycle

- [Cluster policy](https://github.com/mellanox/network-operator/blob/master/controllers/nicclusterpolicy_controller.go): `controllers/nicclusterpolicy_controller.go`
- [Node policy](https://github.com/mellanox/network-operator/blob/master/controllers/nicnodepolicy_controller.go): `controllers/nicnodepolicy_controller.go`
- [Policy validation](https://github.com/mellanox/network-operator/blob/master/api/v1alpha1/validator/nicpolicy_webhook.go): `api/v1alpha1/validator/nicpolicy_webhook.go`

### Managed components

- [State manager](https://github.com/mellanox/network-operator/blob/master/pkg/state/manager.go): `pkg/state/manager.go`
- [OFED driver](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ofed.go): `pkg/state/state_ofed.go`
- [RDMA plugin](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_rdma_shared_device_plugin.go): `pkg/state/state_rdma_shared_device_plugin.go`
- [State framework](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_skel.go): `pkg/state/state_skel.go`
- [SR-IOV plugin](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_sriov_dp.go): `pkg/state/state_sriov_dp.go`
- [IB Kubernetes](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ib_kubernetes.go): `pkg/state/state_ib_kubernetes.go`
- [Multus CNI](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_multus_cni.go): `pkg/state/state_multus_cni.go`
- [CNI plugins](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_cni_plugins.go): `pkg/state/state_cni_plugins.go`
- [IPoIB CNI](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ipoib_cni.go): `pkg/state/state_ipoib_cni.go`
- [NV IPAM](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_nv_ipam_cni.go): `pkg/state/state_nv_ipam_cni.go`
- [NIC configuration](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_nic_configuration_operator.go): `pkg/state/state_nic_configuration_operator.go`
- [DOCA images](https://github.com/mellanox/network-operator/blob/master/pkg/docadriverimages/doca_drivers.go): `pkg/docadriverimages/doca_drivers.go`

### Secondary networks

- [Macvlan reconciler](https://github.com/mellanox/network-operator/blob/master/controllers/macvlannetwork_controller.go): `controllers/macvlannetwork_controller.go`
- [Macvlan state](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_macvlan_network.go): `pkg/state/state_macvlan_network.go`
- [Host-device reconciler](https://github.com/mellanox/network-operator/blob/master/controllers/hostdevicenetwork_controller.go): `controllers/hostdevicenetwork_controller.go`
- [Host-device state](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_hostdevice_network.go): `pkg/state/state_hostdevice_network.go`
- [IPoIB reconciler](https://github.com/mellanox/network-operator/blob/master/controllers/ipoibnetwork_controller.go): `controllers/ipoibnetwork_controller.go`
- [IPoIB state](https://github.com/mellanox/network-operator/blob/master/pkg/state/state_ipoib_network.go): `pkg/state/state_ipoib_network.go`

### Node maintenance

- [Upgrade coordinator](https://github.com/mellanox/network-operator/blob/master/controllers/upgrade_controller.go): `controllers/upgrade_controller.go`
- [Drain controller](https://github.com/mellanox/network-operator/blob/master/controllers/drain_controller.go): `controllers/drain_controller.go`
- [Drain requestor](https://github.com/mellanox/network-operator/blob/master/pkg/drain/drain_requestor.go): `pkg/drain/drain_requestor.go`

### Other components

- **Kubernetes API**
- **Cluster operator**

## Connections

- Cluster operator → Kubernetes API: submits policies
- Kubernetes API → Cluster policy: watches policy (evidence: `controllers/nicclusterpolicy_controller.go`)
- Kubernetes API → Node policy: watches policy (evidence: `controllers/nicnodepolicy_controller.go`)
- Operator startup → Cluster policy: registers controller (evidence: `main.go`)
- Operator startup → Node policy: registers controller (evidence: `main.go`)
- Policy validation → Cluster policy: validates spec
- Cluster policy → State manager: syncs states (evidence: `controllers/nicclusterpolicy_controller.go`)
- Node policy → State manager: syncs states
- State manager → OFED driver: syncs state
- State manager → RDMA plugin: syncs state
- State manager → State framework: uses framework
- Cluster policy → DOCA images: uses image provider (evidence: `controllers/nicclusterpolicy_controller.go`)
- Cluster policy → SR-IOV plugin: configures component
- Cluster policy → IB Kubernetes: configures component
- Cluster policy → Multus CNI: configures component
- Cluster policy → CNI plugins: configures component
- Cluster policy → IPoIB CNI: configures component
- Cluster policy → NV IPAM: configures component
- Cluster policy → NIC configuration: configures component
- Kubernetes API → Macvlan reconciler: watches network
- Macvlan reconciler → Macvlan state: syncs state
- Kubernetes API → Host-device reconciler: watches network (evidence: `controllers/hostdevicenetwork_controller.go`)
- Host-device reconciler → Host-device state: syncs state (evidence: `controllers/hostdevicenetwork_controller.go`)
- Kubernetes API → IPoIB reconciler: watches network
- IPoIB reconciler → IPoIB state: syncs state
- Kubernetes API → Upgrade coordinator: provides policy events
- Drain controller → Drain requestor: creates requestor (evidence: `controllers/drain_controller.go`)
- Drain controller → Kubernetes API: updates maintenance state (evidence: `controllers/drain_controller.go`)
- Cluster operator → Kubernetes API: requests node drain
