Draforge

---

DRAForge を選ぶ理由

Kubernetes Dynamic Resource Allocation（DRA）は、ドライバーが制御するきめ細かなアクセラレーター共有を実現します。しかし、DRA の構成を開発・デバッグする際には、大きな課題があります。

1. ハードウェアの不足：テスト環境用に専用のアクセラレーターノード（例：NVIDIA H100 GPU）を調達して構成するには、コストと時間がかかります。
2. 可観測性のギャップ：Kubernetes 標準のスケジューリングログでは、リソース要求が Pod にバインドされなかった理由を視覚的に把握するのが困難です。

DRAForge は、根拠に基づく診断ツールキット、動的な仮想デバイスシミュレーター、ターミナルユーザーインターフェース（TUI）、リアルタイムで操作できるインタラクティブな関係グラフダッシュボードを提供し、このギャップを埋めます。

---

機能

• 仮想デバイスプール：カスタム属性と容量を使用して、ワーカーノード上で任意のハードウェアプロファイル（例：GPU、FPGA、高速 NIC）をシミュレートします。
• 診断ドクター：構成を誠実に分析します。モックは使用せず、API の利用可否、バージョン互換性、ResourceSlice の整合性チェックなどを行います。
• 説明エンジン：セレクター、容量の上限、ノードアフィニティをリアルタイムに評価し、要求が保留中である理由を特定します。
• Bubble Tea TUI：動的なプール容量を監視する、実用的なターミナルベースのモニターです。
• インタラクティブなグラフダッシュボード：Pod、Claim、Device、Pool 間の関係をリアルタイムの SVG で可視化します。

---

アーキテクチャ

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）ショーケース

このプロバイダー固有の手順は、1 つのマネージド Kubernetes サービス上で DRAForge を実演するための任意のデモです。インストール、テスト、リリースには必要ありません。

⚠️ 課金対象のリソース：このタスクは、DigitalOcean アカウントに稼働中の DOKS クラスターと DOCR レジストリーを作成し、クラウド料金が発生します。使い終わったら、必ず task demo:down を実行して、課金対象のリソースをすべて削除してください。

短期間の DOKS ショーケースをデプロイするには、次を実行します。

task demo:up

このタスクは、未認証の HTTP 公開を有効にする非本番環境向けの values-showcase-docr.yaml プロファイルを明示的に適用します。リソース制限を監査し、インフラストラクチャをプロビジョニングし、イメージをリモートでビルドし、Helm リリースをインストールして、デモ URL を出力します。このプロファイルを機密性の高いクラスターや本番デプロイで使用しないでください。

通常の Helm インストールで作成されるのは、内部 ClusterIP サービスのみです。本番環境でのパブリックアクセスには、TLS と、オペレーターが管理する OIDC／ID 対応プロキシが必要です。インストールガイドを参照してください。 ノードプラグインのデフォルトでは、分離された 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

---

ドキュメント

リソース	説明
コントリビューションガイド	セットアップ、テスト、プルリクエストに関する要件、コミットしてはいけないもの
セキュリティポリシー	脆弱性の報告方法とセキュリティモデル
インストールガイド	デモ用および本番用のインストールプロファイル
運用ガイド	日々の運用、アップグレード、メトリクス、ログ、クリーンアップ
トラブルシューティングガイド	よくある問題や保留中の要求に関する診断
メンテナーチェックリスト	内部レビューとリリースのプロセス
リリースプロセス	スナップショットおよびタグ付きリリースのワークフロー
ダッシュボードガイド	Web ダッシュボードのセットアップと使い方
シミュレーターのシナリオ	シナリオの作成と障害注入
Kubernetes DRA の互換性	DRA API のサポートマトリックス
メンテナー	現在のプロジェクトメンテナー
ガバナンス	意思決定と役割
サポート	サポートを受ける方法

---

セキュリティモデル

DRAForge は読み取り専用のダッシュボード API を公開しますが、Helm はデフォルトでは外部に公開しません。読み取りエンドポイントから運用上のクラスターのメタデータが漏れる可能性があるため、本番環境で一般公開する場合は、TLS と、オペレーターが管理する ID 認識型プロキシを使用する必要があります。クラスターの変更は引き続き CLI からのみ行え、管理者のローカルな kubeconfig で認証します（ADR-0009 を参照）。

Kubernetes DRA API のサポートと既知の制限については、Kubernetes DRA の互換性を参照してください。

---

ライセンス

このプロジェクトは Apache License, Version 2.0 の下でライセンスされています。ライセンスの全文は LICENSE を参照してください。