This document explains the core Dynamic Resource Allocation (DRA) object relationship model and details how DRAForge monitors, simulates, and diagnoses accelerator scheduling.
| Actor | Trust boundary | Actions |
|---|---|---|
| Dashboard user | Browser to DRAForge server | Reads summaries, pools, devices, claims, graph data, diagnostics, metrics, health, readiness, and SSE updates. The dashboard exposes no mutation endpoint. |
| Cluster operator / CLI user | Local process using the operator’s kubeconfig | Reads Kubernetes DRA resources; may apply or reset simulator scenarios and inject or clear faults when explicitly requested. |
| DRAForge server | Pod service account to Kubernetes API | Performs read-only discovery and watch operations, builds graph and diagnostic models, and serves the HTTP/SSE interface. |
| DRAForge controller | Pod service account to Kubernetes API | Reconciles SimulatedDevicePool, publishes simulated ResourceSlice objects, and allocates eligible simulated claims under leader election. |
| DRAForge node plugin | Node-scoped Pod to Kubernetes API and optional CDI directory | Reads node allocation state and writes an atomic CDI document only when host-integrated mode is explicitly enabled. |
| Kubernetes API server | External authoritative control plane | Authenticates and authorizes Kubernetes requests, stores DRA and simulator resources, and emits watch events consumed by DRAForge. |
| Identity-aware proxy / TLS gateway | Optional external access boundary | Authenticates users and terminates TLS before forwarding permitted read-only dashboard traffic; it is operator-managed and not deployed by default. |
| GitHub Actions release automation | Repository workflow identity using scoped GITHUB_TOKEN and OIDC |
Tests reviewed source, builds artifacts and images, generates checksums and SBOMs, signs release outputs, publishes immutable versioned assets, and verifies the public result. |
The detailed external software interfaces are maintained in Public API and CLI Surface. Security claims, threats, controls, evidence, and residual risks are maintained in SECURITY.md.
DRAForge is designed around Kubernetes APIs, standard RBAC, Helm, and OCI images. The server, controller, simulator, CLI, and dashboard do not depend on a specific managed Kubernetes provider. A compatible cluster may be hosted by a cloud provider, operated on-premises, self-managed, or created locally for testing. Provider-specific infrastructure and registry integrations are optional showcase adapters and are not part of the core platform contract. See ADR-0013.
Kubernetes DRA introduces a flexible model where resource requests are handled by specific drivers. Below is the hierarchical relationship model implemented by Kubernetes DRA and observed by DRAForge:
+------------------+
| Pod |
+------------------+
| (claims pod-resource claims)
v
+------------------+
| ResourceClaim |
+------------------+
| (requests allocation of a device class)
v
+------------------+
| DeviceClass |
+------------------+
| (allocated from)
v
+------------------+
| ResourceSlice | (cluster-scoped, published per node)
+------------------+
| (contains)
v
+------------------+
| Device | (represented by Attributes & Capacity)
+------------------+
| (part of)
v
+------------------+
| DevicePool | (managed by Driver)
+------------------+
A DevicePool is a logical set of accelerator hardware devices (such as GPUs, FPGAs, or edge devices) managed by a specific DRA driver on a node. The driver publishes this pool state to the Kubernetes API server using the ResourceSlice API.
resource.k8s.io/v1, ResourceSlices are cluster-scoped.Devices, including their unique names, attributes (e.g. model, vendor, driver version), and capacities (e.g. device memory).A DeviceClass defines the parameters for selecting and configuring a device. It serves as a template, defining which driver to use and specifying selection filters (CEL expressions or label selectors) for matching target devices.
A ResourceClaim represents a pod’s request for resource allocation. The claim specifies which DeviceClass it requires and outlines details of the request (e.g. “exactly 1 GPU” or “first-available GPU with memory > 80Gi”).
When a Pod is scheduled, its spec.resourceClaims reference the ResourceClaim. One claim may contain multiple Exactly requests or FirstAvailable alternatives and may receive multiple allocation results. DRAForge preserves every request and every <request, driver, pool, device, node> result. A node is recorded only when the allocation NodeSelector identifies one exact node; cluster-scoped and ambiguous results remain explicitly unknown.
+-----------------------------+
| Vite Web UI |
+-----------------------------+
^
| (Server-Sent Events)
v
+--------------------------------------------------------+
| DRAForge Server |
| - Real-time Graph Builder |
| - REST API & SSE Streaming |
+--------------------------------------------------------+
^
| (Query / Watch)
v
+--------------------------------------------------------+
| Kubernetes API Server |
| - ResourceSlices (v1) |
| - ResourceClaims (v1) |
| - DeviceClasses (v1) |
| - SimulatedDevicePools (v1alpha1 CRD) |
+--------------------------------------------------------+
^ ^
| (Reconcile / Allocate) | (Publish spec)
v v
+-------------------------+ +------------------------+
| DRAForge Controller | | DRAForge Node Plugin |
| - Allocation Simulator | | - Dynamic CDI Specs |
+-------------------------+ +------------------------+
The Server queries the Kubernetes API for active DRA resources and constructs a relationship graph of all nodes. It exposes this data through a REST API and streams updates via Server-Sent Events (SSE) to the frontend React dashboard.
The Controller watches SimulatedDevicePool custom resources (applied by scenarios) and generates corresponding cluster-scoped ResourceSlice objects to simulate hardware. It also acts as a fallback allocator: it watches for pending ResourceClaims and allocates simulated devices by updating the claim status with node-affinity details.
The Node Plugin runs on each node and generates CDI (Container Device Interface) specification JSONs. In the default demo mode it writes an explicit static document to an isolated emptyDir. In opt-in node mode it lists allocated ResourceClaim devices for the current node and atomically replaces the kubelet-visible CDI document using a same-directory temporary file, file and directory fsync, and rename. Kubernetes API or write failures preserve the last-known-good document and make /readyz return 503; /healthz remains process-only liveness. Device deduplication uses the complete <driver>/<pool>/<device> identity.