# rocm/gpu-operator architecture

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

- Interactive diagram: https://gitdiagram.com/rocm/gpu-operator
- Repository: https://github.com/rocm/gpu-operator

## Overview

AMD GPU Operator manages accelerator configuration and workloads in Kubernetes. An administrator creates or edits a DeviceConfig; the controller reconciles that desired state into driver and device-serving components, while supporting node labeling, metrics, testing, configuration management, and recovery. The API types define configuration and status, and the controller package contains the principal reconciliation and watcher layers. README capabilities include DRA as an alternative allocation path. Some subsystem wiring is not shown in the sampled source, so the graph omits uncertain call relationships; unsampled DRA implementation is represented without an invented file path.

Main entry points: [`internal/controllers/device_config_reconciler.go`](https://github.com/rocm/gpu-operator/blob/main/internal/controllers/device_config_reconciler.go) (DeviceConfig reconciler), [`api/v1alpha1/deviceconfig_types.go`](https://github.com/rocm/gpu-operator/blob/main/api/v1alpha1/deviceconfig_types.go) (DeviceConfig API), [`internal/kmmmodule/kmmmodule.go`](https://github.com/rocm/gpu-operator/blob/main/internal/kmmmodule/kmmmodule.go) (Kernel module manager), [`internal/controllers/workermgr/workermgr.go`](https://github.com/rocm/gpu-operator/blob/main/internal/controllers/workermgr/workermgr.go) (Node worker manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control"]
  node_deviceconfig["DeviceConfig API"]
  node_controller["DeviceConfig reconciler"]
  node_validators["Config validation<br/>[validator.go]"]
  node_conditions["Status conditions<br/>[deviceconfig.go]"]
end

subgraph group_drivers["Driver management"]
  node_kmm["Kernel module manager<br/>[kmmmodule.go]"]
  node_worker["Node worker manager<br/>[workermgr.go]"]
  node_upgrade["Driver upgrades<br/>[upgrademgr.go]"]
end

subgraph group_serving["GPU services"]
  node_plugin["Device plugin<br/>[plugin.go]"]
  node_nodelabel["Node labeller<br/>[nodelabeller.go]"]
  node_dra["DRA driver"]
  node_configmanager["Device config manager<br/>[configmanager.go]"]
  node_metrics["Metrics exporter<br/>[metricsexporter.go]"]
  node_testrunner["Device test runner<br/>[testrunner.go]"]
end

subgraph group_health["Health and recovery"]
  node_remediation["Node remediation"]
  node_watchers["Resource watchers<br/>[device_config.go]"]
end

node_admin(("Cluster administrator"))
node_kubernetes[("Kubernetes cluster")]

node_admin -->|"configures"| node_deviceconfig
node_deviceconfig -->|"triggers reconcile"| node_controller
node_controller -->|"validates config"| node_validators
node_controller -->|"updates status"| node_conditions
node_controller -->|"reconciles resources"| node_kubernetes
node_controller -->|"manages modules"| node_kmm
node_controller -->|"coordinates node work"| node_worker
node_controller -->|"manages upgrades"| node_upgrade
node_controller -->|"configures serving"| node_plugin
node_controller -->|"labels nodes"| node_nodelabel
node_controller -.->|"enables allocation"| node_dra
node_controller -->|"configures manager"| node_configmanager
node_controller -->|"configures metrics"| node_metrics
node_controller -->|"configures tests"| node_testrunner
node_controller -->|"handles recovery"| node_remediation
node_watchers -->|"watches changes"| node_controller
node_kmm -->|"manages module resources"| node_kubernetes
node_worker -->|"patches nodes"| node_kubernetes
node_remediation -->|"manages workflows"| node_kubernetes

click node_deviceconfig "https://github.com/rocm/gpu-operator/blob/main/api/v1alpha1/deviceconfig_types.go"
click node_controller "https://github.com/rocm/gpu-operator/blob/main/internal/controllers/device_config_reconciler.go"
click node_validators "https://github.com/rocm/gpu-operator/blob/main/internal/validator/validator.go"
click node_conditions "https://github.com/rocm/gpu-operator/blob/main/internal/conditions/deviceconfig.go"
click node_kmm "https://github.com/rocm/gpu-operator/blob/main/internal/kmmmodule/kmmmodule.go"
click node_worker "https://github.com/rocm/gpu-operator/blob/main/internal/controllers/workermgr/workermgr.go"
click node_upgrade "https://github.com/rocm/gpu-operator/blob/main/internal/controllers/upgrademgr.go"
click node_plugin "https://github.com/rocm/gpu-operator/blob/main/internal/plugin/plugin.go"
click node_nodelabel "https://github.com/rocm/gpu-operator/blob/main/internal/nodelabeller/nodelabeller.go"
click node_configmanager "https://github.com/rocm/gpu-operator/blob/main/internal/configmanager/configmanager.go"
click node_metrics "https://github.com/rocm/gpu-operator/blob/main/internal/metricsexporter/metricsexporter.go"
click node_testrunner "https://github.com/rocm/gpu-operator/blob/main/internal/testrunner/testrunner.go"
click node_remediation "https://github.com/rocm/gpu-operator/blob/main/internal/controllers/remediation_handler.go"
click node_watchers "https://github.com/rocm/gpu-operator/blob/main/internal/controllers/watchers/device_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_deviceconfig,node_controller,node_validators,node_conditions toneBlue
class node_kmm,node_worker,node_upgrade,node_kubernetes toneAmber
class node_plugin,node_nodelabel,node_dra,node_configmanager,node_metrics,node_testrunner toneMint
class node_remediation,node_watchers toneRose
class node_admin toneIndigo
```

## Components

### Operator control

- [DeviceConfig API](https://github.com/rocm/gpu-operator/blob/main/api/v1alpha1/deviceconfig_types.go): `api/v1alpha1/deviceconfig_types.go`
- [DeviceConfig reconciler](https://github.com/rocm/gpu-operator/blob/main/internal/controllers/device_config_reconciler.go): `internal/controllers/device_config_reconciler.go`
- [Config validation](https://github.com/rocm/gpu-operator/blob/main/internal/validator/validator.go): `internal/validator/validator.go`
- [Status conditions](https://github.com/rocm/gpu-operator/blob/main/internal/conditions/deviceconfig.go): `internal/conditions/deviceconfig.go`

### Driver management

- [Kernel module manager](https://github.com/rocm/gpu-operator/blob/main/internal/kmmmodule/kmmmodule.go): `internal/kmmmodule/kmmmodule.go`
- [Node worker manager](https://github.com/rocm/gpu-operator/blob/main/internal/controllers/workermgr/workermgr.go): `internal/controllers/workermgr/workermgr.go`
- [Driver upgrades](https://github.com/rocm/gpu-operator/blob/main/internal/controllers/upgrademgr.go): `internal/controllers/upgrademgr.go`

### GPU services

- [Device plugin](https://github.com/rocm/gpu-operator/blob/main/internal/plugin/plugin.go): `internal/plugin/plugin.go`
- [Node labeller](https://github.com/rocm/gpu-operator/blob/main/internal/nodelabeller/nodelabeller.go): `internal/nodelabeller/nodelabeller.go`
- **DRA driver**
- [Device config manager](https://github.com/rocm/gpu-operator/blob/main/internal/configmanager/configmanager.go): `internal/configmanager/configmanager.go`
- [Metrics exporter](https://github.com/rocm/gpu-operator/blob/main/internal/metricsexporter/metricsexporter.go): `internal/metricsexporter/metricsexporter.go`
- [Device test runner](https://github.com/rocm/gpu-operator/blob/main/internal/testrunner/testrunner.go): `internal/testrunner/testrunner.go`

### Health and recovery

- [Node remediation](https://github.com/rocm/gpu-operator/blob/main/internal/controllers/remediation_handler.go): `internal/controllers/remediation_handler.go`
- [Resource watchers](https://github.com/rocm/gpu-operator/blob/main/internal/controllers/watchers/device_config.go): `internal/controllers/watchers/device_config.go`

### Other components

- **Cluster administrator**
- **Kubernetes cluster**

## Connections

- Cluster administrator → DeviceConfig API: configures
- DeviceConfig API → DeviceConfig reconciler: triggers reconcile
- DeviceConfig reconciler → Config validation: validates config
- DeviceConfig reconciler → Status conditions: updates status
- DeviceConfig reconciler → Kubernetes cluster: reconciles resources
- DeviceConfig reconciler → Kernel module manager: manages modules
- DeviceConfig reconciler → Node worker manager: coordinates node work
- DeviceConfig reconciler → Driver upgrades: manages upgrades
- DeviceConfig reconciler → Device plugin: configures serving
- DeviceConfig reconciler → Node labeller: labels nodes
- DeviceConfig reconciler → DRA driver: enables allocation
- DeviceConfig reconciler → Device config manager: configures manager
- DeviceConfig reconciler → Metrics exporter: configures metrics
- DeviceConfig reconciler → Device test runner: configures tests
- DeviceConfig reconciler → Node remediation: handles recovery
- Resource watchers → DeviceConfig reconciler: watches changes
- Kernel module manager → Kubernetes cluster: manages module resources
- Node worker manager → Kubernetes cluster: patches nodes
- Node remediation → Kubernetes cluster: manages workflows