Draforge

---

为什么选择 DRAForge？

Kubernetes 动态资源分配（DRA）支持由驱动程序控制的精细化加速器共享。不过，开发和调试 DRA 配置面临一项重大挑战：

1. 硬件短缺：为测试环境购置和配置专用加速器节点（例如 NVIDIA H100 GPU）既耗时又昂贵。
2. 可观测性不足：原生 Kubernetes 调度日志难以直观呈现资源声明无法绑定到 Pod 的原因。

DRAForge 通过提供基于证据的诊断工具包、动态虚拟设备模拟器、终端用户界面（TUI）以及实时交互式关系图仪表板，弥合这一差距。

---

功能

• 虚拟设备池：在工作节点上使用自定义属性和容量，模拟任意硬件配置（例如 GPU、FPGA、高速 NIC）。
• 诊断医生：对配置进行真实、非模拟的分析（例如 API 可用性、版本兼容性、ResourceSlice 一致性检查）。
• 解释引擎：实时评估选择器、容量限制和节点亲和性，精准定位资源声明处于待处理状态的原因。
• Bubble Tea TUI：通过专业的终端监控界面查看动态池容量。
• 交互式图表仪表板：实时以 SVG 可视化 Pod、声明、设备和池之间的关系。

---

架构

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 组件使用 Kubernetes API 和 Helm 契约，而非特定于提供商的服务。它们可在兼容的托管 Kubernetes 服务、自托管集群、本地部署环境和本地测试集群上运行。本仓库中针对特定提供商的 Terraform 或注册表资源均为可选示例。

---

安装

从源代码安装（Go 1.26+）

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

或者克隆并在本地构建：

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

你也可以从 GitHub Releases 页面获取预构建的二进制压缩包。

快速入门

快速入门 A：已验证的本地 kind 集群

安装 Docker、kubectl、Helm、jq、curl、Go、Node.js、pnpm、Task，以及 tests/install-e2e/kubernetes-versions.json 中指定版本的 kind。然后创建与拉取请求安装门禁所用的完整本地堆栈，并保留该环境以便探索：

DRAFORGE_INSTALL_E2E_KEEP_CLUSTER=1 task e2e:install-kind

访问仪表板：

kubectl port-forward svc/draforge-server -n draforge-system 8080:8080

需要时构建本地 CLI/TUI：

task build
./bin/draforge doctor
./bin/draforge tui

完成后销毁临时集群：

kind delete cluster --name draforge-install-e2e

快速入门 B：可选的 DigitalOcean Kubernetes (DOKS) 展示

此特定于提供商的流程是 DRAForge 在一种托管 Kubernetes 服务上的可选演示。安装、测试或发布均不需要此流程。

⚠️ 计费资源：此任务会在你的 DigitalOcean 账户中创建一个运行中的 DOKS 集群和 DOCR 注册表，并产生云服务费用。完成后请务必运行 task demo:down，销毁所有计费资源。

部署短期 DOKS 展示环境：

task demo:up

此任务会显式应用非生产环境配置 values-showcase-docr.yaml，该配置会启用未经身份验证的 HTTP 访问。任务会审核资源限制、创建基础设施、远程构建镜像、安装 Helm 版本并输出演示 URL。请勿将此配置用于敏感集群或生产部署。

常规 Helm 安装只会创建内部 ClusterIP 服务。生产环境中的公共访问需要 TLS 和由运维人员管理的 OIDC/身份感知代理；请参阅安装指南。 节点插件默认使用隔离的 demo CDI 输出。与主机集成的 kubelet CDI 输出需要显式选择 nodePlugin.outputMode=node，且在 Kubernetes 或主机 CDI 目录不可用时会安全失败。

拆除展示环境并清理所有计费资源：

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 test

带标签的冒烟测试可在任何提供所需 DRA API 的兼容 Kubernetes 集群上运行，并由 DRAFORGE_E2E=1 控制是否启用。Portable Kubernetes E2E 工作流会针对相关拉取请求，在无需凭证的 kind 环境中验证此流程，也可以使用受保护的短期 kubeconfig 连接外部集群：

DRAFORGE_E2E=1 go test -tags=e2e ./tests/e2e/... -v

发布

完整发布流程请参阅 docs/release.md。

本地快照构建（不发布）

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

带标签的发布

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"

推送带注释的标签会启动受保护的发布工作流。已发布的 v* 标签不可变，永远不会移动或重复使用。

---

CLI 命令参考

命令	描述	示例
draforge version	显示二进制版本和提交详细信息	draforge version
draforge discover	列出活跃的 DRA 池、设备和资源声明	draforge discover -o json
draforge claims	在格式化表格中汇总声明状态	draforge claims
draforge graph	以 DOT 或 Mermaid 格式生成关系图	draforge graph -o mermaid
draforge explain	排查 ResourceClaim 处于待处理状态的原因	draforge explain my-pending-claim
draforge doctor	执行集群和驱动程序诊断检查	draforge doctor
draforge tui	启动基于终端的监控控制台	draforge tui
draforge serve	运行 HTTP API 服务和 Vite 仪表板前端	draforge serve

---

文档

资源	说明
贡献指南	环境设置、测试、PR 要求，以及禁止提交的内容
安全策略	漏洞报告和安全模型
安装指南	演示和生产安装配置
运维指南	日常运维、升级、指标、日志和清理
故障排查指南	常见问题和待处理声明的诊断方法
维护者检查清单	内部审查和发布流程
发布流程	快照和带标签的发布工作流
仪表板指南	Web 仪表板的设置和使用
模拟器场景	场景编写和故障注入
Kubernetes DRA 兼容性	DRA API 支持矩阵
维护者	当前项目维护者
治理	决策机制和职责
支持	获取帮助的方式

---

安全模型

DRAForge 提供只读仪表板 API，但 Helm 默认不会将其对外公开。读取端点可能会泄露集群运行元数据，因此生产环境中的公开访问必须使用 TLS 和由运维人员管理的身份感知代理。集群修改仍仅限通过 CLI 进行，并使用管理员本地的 kubeconfig 进行身份验证（参见 ADR-0009）。

有关 Kubernetes DRA API 支持情况和已知限制，请参阅 Kubernetes DRA 兼容性。

---

许可证

本项目采用 Apache License 2.0 许可。完整许可证文本请参阅 LICENSE。