Skip to content
oaslanankaPublic

About

Provider-neutral Kubernetes DRA observability, simulator, and diagnostics for GPU and accelerator workloads—model virtual device pools, inspect ResourceClaim/ResourceSlice state, and explain allocation outcomes without physical hardware.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

191 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

DRAForge

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.

Try it locally · Read the documentation · Download v0.4.0

CI Security Analysis Go Coverage Latest Release OpenSSF Scorecard OpenSSF Best Practices

AGPL-3.0-only license GitGem

GitHub Sponsors Buy Me a Coffee Stars

What can you do?

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

See the allocation path

Real DRAForge dashboard: a selected synthetic ResourceClaim, connected resources, and a diagnostics action in the interactive graph

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.

Quickstart

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:8080

The 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


Why DRAForge?

Kubernetes Dynamic Resource Allocation (DRA) offers fine-grained, driver-controlled accelerator sharing. However, developing and debugging DRA configurations presents a major challenge:

  1. Hardware Scarcity: Acquiring and configuring dedicated accelerator nodes (e.g., NVIDIA H100 GPUs) for test environments is costly and slow.
  2. 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.


Features

  • 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.

Architecture

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
Loading

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.


Install

From source (Go 1.26+)

go install github.com/oaslananka/draforge/cmd/draforge@latest

Or clone and build locally:

git clone https://github.com/oaslananka/draforge.git
cd draforge
task build          # Builds all three binaries into bin/
./bin/draforge version

Binaries are also available as pre-built archives from the GitHub Releases page.

Detailed installation recipes

Local kind cluster (expanded)

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-request

If 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:8080

Open 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 tui

Destroy the disposable cluster when finished:

kind delete cluster --name draforge-install-e2e

Optional DigitalOcean Kubernetes (DOKS) showcase

This 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 run task demo:down when finished to destroy all billable resources.

To deploy the short-lived DOKS showcase:

task demo:up

This 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

Testing

# 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 test

The 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/... -v

Release

See docs/release.md for the full release process.

Local snapshot build (no publishing)

task release:local
# or: goreleaser release --snapshot --clean --skip=docker,sbom,sign

Tagged release

NEXT_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.


CLI Command Reference

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

Documentation

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

Security Model

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.


License

Project-authored source is licensed under GNU AGPL v3.0 (AGPL-3.0-only).


About

Provider-neutral Kubernetes DRA observability, simulator, and diagnostics for GPU and accelerator workloads—model virtual device pools, inspect ResourceClaim/ResourceSlice state, and explain allocation outcomes without physical hardware.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages