Understand why a Kubernetes GPU or accelerator claim is pending, allocated, or failing.
DRAForge connects Kubernetes ResourceClaims, device pools, and ResourceSlices into a readable graph, explains allocation decisions, and lets you reproduce DRA scenarios with simulated hardware—no physical GPU required.
| Inspect allocations | Reproduce scenarios | Explain the failure |
|---|---|---|
| See real Kubernetes claims, classes, pools, and devices in one relationship graph. | Create synthetic accelerator pools on a local kind cluster; no GPU or cloud provider needed. | Open a claim's explanation to investigate selectors, capacity, node affinity, and DRA health checks. |
| Dashboard guide | Local quickstart | Troubleshooting |
Actual DRAForge React dashboard rendered with synthetic demonstration data. This is a product preview—not a publicly connected Kubernetes cluster or proof of physical GPU support. View the full-size image.
Try a complete local DRA flow. You need Docker Engine or Docker Desktop with WSL integration, Bash, kind, kubectl, Helm, jq, curl, and sha256sum. No cloud account or physical accelerator is required.
git clone https://github.com/oaslananka/draforge.git
cd draforge
DRAFORGE_INSTALL_E2E_KEEP_CLUSTER=1 bash scripts/kind-install-e2e.sh pull-request
# In a separate terminal, open http://localhost:8080
kubectl port-forward svc/draforge-server -n draforge-system 8080:8080The disposable kind installation checks its prerequisites, refuses to overwrite an existing cluster, and leaves the cluster running for exploration. Visit http://localhost:8080, select Relationships, then Explain a claim to follow a simulated allocation. When finished, use kind delete cluster --name draforge-install-e2e only for the disposable cluster you created.
Already have Kubernetes? Use the production/local installation guide for read-only deployment and ingress controls. On Windows? Enable Docker Desktop's WSL 2 integration for the distribution running the commands, then confirm docker info in that same terminal.
More resources — architecture, compatibility, operations, and project policies
Architecture · Kubernetes compatibility · Operations · Contributing · Governance · Security · Support
Kubernetes Dynamic Resource Allocation (DRA) offers fine-grained, driver-controlled accelerator sharing. However, developing and debugging DRA configurations presents a major challenge:
- Hardware Scarcity: Acquiring and configuring dedicated accelerator nodes (e.g., NVIDIA H100 GPUs) for test environments is costly and slow.
- Observability Gap: Native Kubernetes scheduling logs make it difficult to visualize why a resource claim failed to bind to a pod.
DRAForge bridges this gap by providing an evidence-based diagnostics toolkit, a dynamic virtual device simulator, a terminal user interface (TUI), and a real-time interactive relationship graph dashboard.
- Virtual Device Pools: Simulate arbitrary hardware profiles (e.g. GPUs, FPGAs, High-Speed NICs) on worker nodes using custom attributes and capacities.
- Diagnostics Doctor: Honest, non-mocked configuration analysis (e.g. API availability, version compatibility, ResourceSlice consistency checks).
- Explain Engine: Real-time evaluation of selectors, capacity bounds, and node affinity to pinpoint why claims are pending.
- Bubble Tea TUI: Professional terminal-based monitor for dynamic pool capacities.
- Interactive Graph Dashboard: Real-time SVG visualization of relationships between Pods, Claims, Devices, and Pools.
graph TD
subgraph Kubernetes Cluster
Server[DRAForge Server] <--> WebSPA[Vite + React SPA Dashboard]
Controller[DRAForge Controller] <--> SimulatedDevicePool[SimulatedDevicePool CRD]
Plugin[Node Plugin DaemonSet] --> ResourceSlice[ResourceSlice Spec]
APIServer[Kubernetes API Server] <--> Server
APIServer <--> Controller
APIServer <--> Plugin
end
CLI[DRAForge CLI] <--> APIServer
DRAForge components use Kubernetes APIs and Helm contracts rather than provider-specific services. They can run on compatible managed Kubernetes offerings, self-managed clusters, on-premises environments, and local test clusters. Provider-specific Terraform or registry assets in this repository are optional showcases.
go install github.com/oaslananka/draforge/cmd/draforge@latestOr clone and build locally:
git clone https://github.com/oaslananka/draforge.git
cd draforge
task build # Builds all three binaries into bin/
./bin/draforge versionBinaries are also available as pre-built archives from the GitHub Releases page.
For the complete local stack, install Bash (WSL on Windows), a running Docker daemon, kubectl, Helm, jq, curl, sha256sum, and the exact kind version pinned in tests/install-e2e/kubernetes-versions.json. Go is only needed if you also build the standalone CLI/TUI; Node.js and pnpm are only needed for optional local frontend/browser tests. The container image build brings its own toolchains.
Windows/WSL: Docker Desktop working in PowerShell does not prove that Docker works inside Ubuntu/WSL. Use the Docker Desktop WSL 2 backend and per-distribution integration, then run docker info in the same WSL terminal before starting. The quickstart now reports missing tools together and refuses to create a kind cluster if the Docker daemon is unavailable. Native Linux Docker Engine works with the same docker info check.
Clone the repository and create the disposable kind stack:
git clone https://github.com/oaslananka/draforge.git
cd draforge
DRAFORGE_INSTALL_E2E_KEEP_CLUSTER=1 bash scripts/kind-install-e2e.sh pull-requestIf you already use Task, the equivalent command is DRAFORGE_INSTALL_E2E_KEEP_CLUSTER=1 task e2e:install-kind. The installer refuses to replace an existing kind cluster, including a previous draforge-install-e2e cluster: inspect the existing cluster, choose a unique DRAFORGE_INSTALL_E2E_CLUSTER_NAME, or deliberately remove it before retrying. It only cleans up clusters it successfully created itself.
Access the dashboard:
kubectl port-forward svc/draforge-server -n draforge-system 8080:8080Open http://localhost:8080 on the same machine to explore the live, read-only DRAForge dashboard (Claims, Graph and Explain). This is a local connection, not a publicly hosted demo.
Build the local CLI/TUI when needed (requires Go 1.26+):
go build -o bin/draforge ./cmd/draforge
./bin/draforge doctor
./bin/draforge tuiDestroy the disposable cluster when finished:
kind delete cluster --name draforge-install-e2eThis provider-specific path is an optional demonstration of DRAForge on one managed Kubernetes service. It is not required for installation, testing, or releases.
⚠️ Billable Resources: This task provisions a live DOKS cluster and DOCR registry on your DigitalOcean account and incurs cloud costs. Always runtask demo:downwhen finished to destroy all billable resources.
To deploy the short-lived DOKS showcase:
task demo:upThis task explicitly applies the non-production values-showcase-docr.yaml profile, which enables unauthenticated HTTP exposure. It audits resource limits, provisions infrastructure, builds images remotely, installs the Helm release, and outputs the demo URL. Do not use this profile with sensitive clusters or as a production deployment.
A normal Helm install creates only internal ClusterIP services. Production public access requires TLS and an operator-managed OIDC/identity-aware proxy; see the installation guide.
The node plugin defaults to isolated demo CDI output. Host-integrated kubelet CDI output is an explicit nodePlugin.outputMode=node opt-in and fails closed when Kubernetes or the host CDI directory is unavailable.
To tear down the showcase and clean all billable resources:
task demo:down# Run all unit tests (fast, no race)
go test ./...
# or: task test:unit
# Run unit tests with race detector and coverage
go test -race -coverprofile=coverage.out ./...
# or: task test:race
# Run all Go vet checks
go vet ./...
# or: task vet
# Run frontend unit and integration tests
pnpm --dir web test
# or: task web:test
# Run full Go CI suite (unit + race)
task testThe tagged smoke tests run against any compatible Kubernetes cluster that serves the required DRA APIs and are gated by DRAFORGE_E2E=1. The Portable Kubernetes E2E workflow validates this path on credential-free kind for relevant pull requests and can use a protected short-lived kubeconfig for an external cluster:
DRAFORGE_E2E=1 go test -tags=e2e ./tests/e2e/... -vSee docs/release.md for the full release process.
task release:local
# or: goreleaser release --snapshot --clean --skip=docker,sbom,signNEXT_VERSION="${NEXT_VERSION:?set NEXT_VERSION to the intended SemVer, for example 0.3.1}"
release_tag="v${NEXT_VERSION}"
git tag -a "$release_tag" -m "DRAForge $release_tag"
RELEASE_TAG="$release_tag" RELEASE_MAIN_REF=main bash scripts/verify-release-tag.sh
git push origin "$release_tag"Pushing the annotated tag starts the protected release workflow. Published v* tags are immutable and are never moved or reused.
| Command | Description | Example |
|---|---|---|
draforge version |
Print binary version and commit details | draforge version |
draforge discover |
Lists active DRA pools, devices, and resource claims | draforge discover -o json |
draforge claims |
Summarizes claims status in a formatted table | draforge claims |
draforge graph |
Generates relationship graph in DOT or Mermaid formats | draforge graph -o mermaid |
draforge explain |
Troubleshoots why a ResourceClaim is pending | draforge explain my-pending-claim |
draforge doctor |
Executes cluster and driver diagnostics checks | draforge doctor |
draforge tui |
Launches the terminal-based monitor console | draforge tui |
draforge serve |
Runs HTTP API server and Vite dashboard frontend | draforge serve |
| Resource | Description |
|---|---|
| Contributing Guide | Setup, testing, PR expectations, and what not to commit |
| Security Policy | Vulnerability reporting and security model |
| Installation Guide | Demo and production installation profiles |
| Operations Guide | Day-two operations, upgrades, metrics, logs, and cleanup |
| Troubleshooting Guide | Diagnostics for common issues and pending claims |
| Maintainer Checklist | Internal review and release processes |
| Release Process | Snapshot and tagged release workflow |
| Dashboard Guide | Web dashboard setup and usage |
| Simulator Scenarios | Scenario authoring and fault injection |
| Kubernetes DRA Compatibility | DRA API support matrix |
| Maintainers | Current project maintainers |
| Governance | Decision-making and roles |
| Support | How to get help |
DRAForge exposes a read-only dashboard API, but Helm does not expose it externally by default. Read endpoints can reveal operational cluster metadata, so production public access must use TLS and an operator-managed identity-aware proxy. Cluster modifications remain CLI-only and authenticate with the administrator's local kubeconfig (see ADR-0009).
For Kubernetes DRA API support and known limitations, see Kubernetes DRA Compatibility.
Project-authored source is licensed under GNU AGPL v3.0 (AGPL-3.0-only).