# sub-mod/amd-gpu-mock architecture

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

- Interactive diagram: https://gitdiagram.com/sub-mod/amd-gpu-mock
- Repository: https://github.com/sub-mod/amd-gpu-mock

## Overview

amd-gpu-mock simulates AMD GPU control-plane surfaces on CPU-only Kubernetes nodes. The primary workflow loads a profile into the node agent, renders host-visible GPU topology and device artifacts, then exposes controls and telemetry for dashboards and cluster consumers. Users can inject faults, change profiles, or view simulated metrics; Kubernetes integrations discover the mock through sysfs, AMD SMI, and CDI. The README documents device-plugin and DRA consumer paths, but their implementations are external to this repository; those links are documented at a high level.

Main entry points: [`cmd/node-agent/main.go`](https://github.com/sub-mod/amd-gpu-mock/blob/main/cmd/node-agent/main.go) (Node agent), [`pkg/gpu/kfd/api.go`](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/api.go) (Control API), [`pkg/gpu/kfd/renderer.go`](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/renderer.go) (Sysfs renderer), [`profiles`](https://github.com/sub-mod/amd-gpu-mock/tree/main/profiles) (GPU profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Node Agent"]
  node_profile["GPU profiles"]
  node_nodeagent["Node agent<br/>[main.go]"]
end

subgraph group_surfaces["GPU Surfaces"]
  node_renderer["Sysfs renderer<br/>[renderer.go]"]
  node_kfd["KFD topology<br/>[renderer.go]"]
  node_pci["PCI and DRM<br/>[renderer.go]"]
  node_devnodes["Device nodes<br/>[main.go]"]
  node_cdigen["CDI generator<br/>[cdi.go]"]
  node_cdispec["CDI specs<br/>[cdi.go]"]
  node_smi["AMD SMI mock<br/>[mock_amdsmi.c]"]
  node_smitypes["SMI type contract<br/>[amdsmi_types.h]"]
  node_smistubs["SMI stubs<br/>[stubs.c]"]
end

subgraph group_control["Fleet Control"]
  node_state["Fleet state<br/>[state.go]"]
  node_dynamic["Dynamic metrics<br/>[dynamic.go]"]
  node_api["Control API<br/>[api.go]"]
  node_dashboard["Web dashboard<br/>[dashboard.go]"]
end

subgraph group_integrations["Consumer Integrations"]
  node_nri["NRI injector<br/>[main.go]"]
  node_kubernetes(("Kubernetes workloads"))
  node_deviceplugin["AMD device plugin"]
  node_dra["AMD DRA driver"]
  node_prometheus(("Prometheus"))
  node_grafana["Grafana"]
end

node_operator(("Cluster operator"))

node_operator -->|"selects"| node_profile
node_profile -->|"configures"| node_nodeagent
node_nodeagent -->|"renders"| node_renderer
node_renderer -->|"writes"| node_kfd
node_renderer -->|"writes"| node_pci
node_nodeagent -->|"creates"| node_devnodes
node_nodeagent -->|"generates"| node_cdigen
node_cdigen -->|"writes"| node_cdispec
node_nodeagent -->|"initializes"| node_state
node_nodeagent -->|"starts"| node_dynamic
node_nodeagent -->|"starts"| node_api
node_api -->|"updates"| node_state
node_api -->|"syncs sysfs"| node_renderer
node_dashboard -->|"requests"| node_api
node_operator -->|"views controls"| node_dashboard
node_nri -->|"injects mounts"| node_kubernetes
node_deviceplugin -->|"discovers GPUs"| node_kfd
node_deviceplugin -->|"exposes devices"| node_devnodes
node_dra -->|"uses allocation specs"| node_cdispec
node_prometheus -->|"scrapes metrics"| node_api
node_grafana -->|"visualizes telemetry"| node_prometheus
node_smi -->|"implements contract"| node_smitypes
node_smistubs -->|"uses types"| node_smitypes
node_operator -->|"injects faults"| node_api

click node_profile "https://github.com/sub-mod/amd-gpu-mock/tree/main/profiles"
click node_nodeagent "https://github.com/sub-mod/amd-gpu-mock/blob/main/cmd/node-agent/main.go"
click node_renderer "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/renderer.go"
click node_kfd "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/renderer.go"
click node_pci "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/renderer.go"
click node_devnodes "https://github.com/sub-mod/amd-gpu-mock/blob/main/cmd/node-agent/main.go"
click node_cdigen "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/cdi.go"
click node_cdispec "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/cdi.go"
click node_smi "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/mocksmi/mock_amdsmi.c"
click node_smitypes "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/mocksmi/amdsmi_types.h"
click node_smistubs "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/mocksmi/stubs.c"
click node_state "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/state.go"
click node_dynamic "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/dynamic.go"
click node_api "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/api.go"
click node_dashboard "https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/dashboard.go"
click node_nri "https://github.com/sub-mod/amd-gpu-mock/blob/main/cmd/nri-plugin/main.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_profile,node_nodeagent toneBlue
class node_renderer,node_kfd,node_pci,node_devnodes,node_cdigen,node_cdispec,node_smi,node_smitypes,node_smistubs toneAmber
class node_state,node_dynamic,node_api,node_dashboard toneMint
class node_nri,node_kubernetes,node_deviceplugin,node_dra,node_prometheus,node_grafana toneRose
class node_operator toneIndigo
```

## Components

### Node Agent

- [GPU profiles](https://github.com/sub-mod/amd-gpu-mock/tree/main/profiles): `profiles`
- [Node agent](https://github.com/sub-mod/amd-gpu-mock/blob/main/cmd/node-agent/main.go): `cmd/node-agent/main.go`

### GPU Surfaces

- [Sysfs renderer](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/renderer.go): `pkg/gpu/kfd/renderer.go`
- [KFD topology](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/renderer.go): `pkg/gpu/kfd/renderer.go`
- [PCI and DRM](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/renderer.go): `pkg/gpu/kfd/renderer.go`
- [Device nodes](https://github.com/sub-mod/amd-gpu-mock/blob/main/cmd/node-agent/main.go): `cmd/node-agent/main.go`
- [CDI generator](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/cdi.go): `pkg/gpu/kfd/cdi.go`
- [CDI specs](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/cdi.go): `pkg/gpu/kfd/cdi.go`
- [AMD SMI mock](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/mocksmi/mock_amdsmi.c): `pkg/mocksmi/mock_amdsmi.c`
- [SMI type contract](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/mocksmi/amdsmi_types.h): `pkg/mocksmi/amdsmi_types.h`
- [SMI stubs](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/mocksmi/stubs.c): `pkg/mocksmi/stubs.c`

### Fleet Control

- [Fleet state](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/state.go): `pkg/gpu/kfd/state.go`
- [Dynamic metrics](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/dynamic.go): `pkg/gpu/kfd/dynamic.go`
- [Control API](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/api.go): `pkg/gpu/kfd/api.go`
- [Web dashboard](https://github.com/sub-mod/amd-gpu-mock/blob/main/pkg/gpu/kfd/dashboard.go): `pkg/gpu/kfd/dashboard.go`

### Consumer Integrations

- [NRI injector](https://github.com/sub-mod/amd-gpu-mock/blob/main/cmd/nri-plugin/main.go): `cmd/nri-plugin/main.go`
- **Kubernetes workloads**
- **AMD device plugin**
- **AMD DRA driver**
- **Prometheus**
- **Grafana**

### Other components

- **Cluster operator**

## Connections

- Cluster operator → GPU profiles: selects (evidence: `README.md`)
- GPU profiles → Node agent: configures (evidence: `cmd/node-agent/main.go`)
- Node agent → Sysfs renderer: renders (evidence: `cmd/node-agent/main.go`)
- Sysfs renderer → KFD topology: writes (evidence: `pkg/gpu/kfd/renderer.go`)
- Sysfs renderer → PCI and DRM: writes (evidence: `pkg/gpu/kfd/renderer.go`)
- Node agent → Device nodes: creates (evidence: `cmd/node-agent/main.go`)
- Node agent → CDI generator: generates (evidence: `cmd/node-agent/main.go`)
- CDI generator → CDI specs: writes (evidence: `pkg/gpu/kfd/cdi.go`)
- Node agent → Fleet state: initializes (evidence: `cmd/node-agent/main.go`)
- Node agent → Dynamic metrics: starts (evidence: `cmd/node-agent/main.go`)
- Node agent → Control API: starts (evidence: `cmd/node-agent/main.go`)
- Control API → Fleet state: updates (evidence: `pkg/gpu/kfd/api.go`)
- Control API → Sysfs renderer: syncs sysfs (evidence: `pkg/gpu/kfd/api.go`)
- Web dashboard → Control API: requests (evidence: `pkg/gpu/kfd/dashboard.go`)
- Cluster operator → Web dashboard: views controls (evidence: `README.md`)
- NRI injector → Kubernetes workloads: injects mounts (evidence: `cmd/nri-plugin/main.go`)
- AMD device plugin → KFD topology: discovers GPUs (evidence: `README.md`)
- AMD device plugin → Device nodes: exposes devices (evidence: `README.md`)
- AMD DRA driver → CDI specs: uses allocation specs (evidence: `README.md`)
- Prometheus → Control API: scrapes metrics (evidence: `README.md`)
- Grafana → Prometheus: visualizes telemetry (evidence: `README.md`)
- AMD SMI mock → SMI type contract: implements contract (evidence: `pkg/mocksmi/mock_amdsmi.c`)
- SMI stubs → SMI type contract: uses types (evidence: `pkg/mocksmi/stubs.c`)
- Cluster operator → Control API: injects faults (evidence: `README.md`)
