# mellanox/spectrum-x-operator architecture

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

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

## Overview

The NVIDIA Spectrum-X Operator runs in Kubernetes and coordinates node-level Spectrum-X networking. Its workflow watches Pod network state and programs OVS rail flows, while a separate SpectrumXRailPoolConfig reconciliation path applies node policies and tracks synchronization. Background components clean stale flows and mirror PF carrier state to VF representors; startup also installs OVS safe-start configuration. The main entry point and core controller imports are indexed, but several setup calls and subsystems are unsampled, so only documented or indexed relationships are connected.

Main entry points: [`internal/controller/spectrumxrailpoolconfig_host_flows_controller.go`](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/spectrumxrailpoolconfig_host_flows_controller.go) (Rail config reconciler), [`cmd/flowscontroller/main.go`](https://github.com/mellanox/spectrum-x-operator/blob/main/cmd/flowscontroller/main.go) (Controller manager), [`internal/vfstatefollower/monitor.go`](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/vfstatefollower/monitor.go) (VF carrier follower), [`internal/controller/flows.go`](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/flows.go) (Rail flow programming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Operator runtime"]
  node_operator["Controller manager<br/>[main.go]"]
end

subgraph group_flows["Pod rail flows"]
  node_flow_reconciler["Pod flow reconciler<br/>[flow_controller.go]"]
  node_flow_logic["Rail flow programming<br/>[flows.go]"]
  node_stale_cleaner["Stale flow cleanup<br/>[stalecleanup.go]"]
end

subgraph group_config["Rail configuration"]
  node_rail_config["Rail config reconciler"]
  node_config_api["Rail config API"]
  node_node_state["Node state lookup<br/>[state.go]"]
end

subgraph group_node["Node networking"]
  node_exec["Command execution<br/>[exec.go]"]
  node_netlink["Netlink operations<br/>[netlink.go]"]
  node_vf_monitor["VF carrier follower<br/>[monitor.go]"]
  node_safe_start["OVS safe-start installer<br/>[install.go]"]
  node_nic_config["Runtime configuration<br/>[config.go]"]
end

node_kubernetes(("Kubernetes API"))
node_ovs["Open vSwitch"]
node_host_net["Host network devices"]
node_sriov_operator["SR-IOV resources"]

node_operator -->|"starts controller"| node_flow_reconciler
node_operator -->|"starts controller"| node_rail_config
node_operator -->|"starts cleanup"| node_stale_cleaner
node_operator -->|"starts follower"| node_vf_monitor
node_flow_reconciler -->|"adds or deletes"| node_flow_logic
node_flow_reconciler -->|"queries OVS"| node_exec
node_flow_logic -->|"runs commands"| node_exec
node_flow_logic -->|"programs flows"| node_ovs
node_stale_cleaner -->|"cleans stale flows"| node_flow_logic
node_rail_config -->|"reconciles resource"| node_config_api
node_rail_config -->|"looks up state"| node_node_state
node_rail_config -->|"patches policies"| node_sriov_operator
node_rail_config -->|"manages OVS resources"| node_ovs
node_operator -->|"runs manager"| node_kubernetes
node_vf_monitor -->|"reads configs"| node_config_api
node_vf_monitor -->|"checks and sets links"| node_netlink
node_vf_monitor -->|"tracks carrier"| node_host_net
node_rail_config -->|"uses installer"| node_safe_start

click node_operator "https://github.com/mellanox/spectrum-x-operator/blob/main/cmd/flowscontroller/main.go"
click node_flow_reconciler "https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/flow_controller.go"
click node_flow_logic "https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/flows.go"
click node_stale_cleaner "https://github.com/mellanox/spectrum-x-operator/blob/main/internal/staleflows/stalecleanup.go"
click node_rail_config "https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/spectrumxrailpoolconfig_host_flows_controller.go"
click node_config_api "https://github.com/mellanox/spectrum-x-operator/blob/main/api/v1alpha2/spectrumxrailpoolconfig_types.go"
click node_node_state "https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/state/state.go"
click node_exec "https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/exec/exec.go"
click node_netlink "https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/lib/netlink/netlink.go"
click node_vf_monitor "https://github.com/mellanox/spectrum-x-operator/blob/main/internal/vfstatefollower/monitor.go"
click node_safe_start "https://github.com/mellanox/spectrum-x-operator/blob/main/internal/ovssafestart/install.go"
click node_nic_config "https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/config/config.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_flow_reconciler,node_flow_logic,node_stale_cleaner toneAmber
class node_rail_config,node_config_api,node_node_state,node_kubernetes toneMint
class node_exec,node_netlink,node_vf_monitor,node_safe_start,node_nic_config toneRose
class node_ovs,node_host_net,node_sriov_operator toneIndigo
```

## Components

### Operator runtime

- [Controller manager](https://github.com/mellanox/spectrum-x-operator/blob/main/cmd/flowscontroller/main.go): `cmd/flowscontroller/main.go`

### Pod rail flows

- [Pod flow reconciler](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/flow_controller.go): `internal/controller/flow_controller.go`
- [Rail flow programming](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/flows.go): `internal/controller/flows.go`
- [Stale flow cleanup](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/staleflows/stalecleanup.go): `internal/staleflows/stalecleanup.go`

### Rail configuration

- [Rail config reconciler](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/controller/spectrumxrailpoolconfig_host_flows_controller.go): `internal/controller/spectrumxrailpoolconfig_host_flows_controller.go`
- [Rail config API](https://github.com/mellanox/spectrum-x-operator/blob/main/api/v1alpha2/spectrumxrailpoolconfig_types.go): `api/v1alpha2/spectrumxrailpoolconfig_types.go`
- [Node state lookup](https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/state/state.go): `pkg/state/state.go`

### Node networking

- [Command execution](https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/exec/exec.go): `pkg/exec/exec.go`
- [Netlink operations](https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/lib/netlink/netlink.go): `pkg/lib/netlink/netlink.go`
- [VF carrier follower](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/vfstatefollower/monitor.go): `internal/vfstatefollower/monitor.go`
- [OVS safe-start installer](https://github.com/mellanox/spectrum-x-operator/blob/main/internal/ovssafestart/install.go): `internal/ovssafestart/install.go`
- [Runtime configuration](https://github.com/mellanox/spectrum-x-operator/blob/main/pkg/config/config.go): `pkg/config/config.go`

### Other components

- **Kubernetes API**
- **Open vSwitch**
- **Host network devices**
- **SR-IOV resources**

## Connections

- Controller manager → Pod flow reconciler: starts controller (evidence: `cmd/flowscontroller/main.go`)
- Controller manager → Rail config reconciler: starts controller (evidence: `cmd/flowscontroller/main.go`)
- Controller manager → Stale flow cleanup: starts cleanup (evidence: `cmd/flowscontroller/main.go`)
- Controller manager → VF carrier follower: starts follower (evidence: `cmd/flowscontroller/main.go`)
- Pod flow reconciler → Rail flow programming: adds or deletes (evidence: `internal/controller/flow_controller.go`)
- Pod flow reconciler → Command execution: queries OVS (evidence: `internal/controller/flow_controller.go`)
- Rail flow programming → Command execution: runs commands (evidence: `internal/controller/flows.go`)
- Rail flow programming → Open vSwitch: programs flows (evidence: `internal/controller/flows.go`)
- Stale flow cleanup → Rail flow programming: cleans stale flows (evidence: `internal/staleflows/stalecleanup.go`)
- Rail config reconciler → Rail config API: reconciles resource (evidence: `internal/controller/spectrumxrailpoolconfig_host_flows_controller.go`)
- Rail config reconciler → Node state lookup: looks up state (evidence: `internal/controller/spectrumxrailpoolconfig_host_flows_controller.go`)
- Rail config reconciler → SR-IOV resources: patches policies (evidence: `internal/controller/spectrumxrailpoolconfig_host_flows_controller.go`)
- Rail config reconciler → Open vSwitch: manages OVS resources (evidence: `internal/controller/spectrumxrailpoolconfig_host_flows_controller.go`)
- Controller manager → Kubernetes API: runs manager (evidence: `cmd/flowscontroller/main.go`)
- VF carrier follower → Rail config API: reads configs (evidence: `internal/vfstatefollower/monitor.go`)
- VF carrier follower → Netlink operations: checks and sets links (evidence: `internal/vfstatefollower/monitor.go`)
- VF carrier follower → Host network devices: tracks carrier (evidence: `internal/vfstatefollower/monitor.go`)
- Rail config reconciler → OVS safe-start installer: uses installer (evidence: `internal/controller/spectrumxrailpoolconfig_host_flows_controller.go`)