Federated Compute Resource Discovery Gateway

Federated Compute is a local-first Go gateway that discovers CPU, RAM, and GPU capacity from independent compute providers. It fans out requests concurrently, normalizes provider snapshots, filters them against a typed request, and ranks the surviving candidates with provenance and partial-failure details.

The local demonstration uses three logical providers and can optionally add a Kubernetes-backed provider that reads HAMi metadata. The normal development stack needs only Docker. The fake GPU path uses HAMi's documented nvml-mock lab and does not require a physical NVIDIA GPU.

Quick Start

Prerequisites: Go 1.25+, Docker with Compose, and curl. On Windows, use Docker Desktop and run the optional kind/HAMi scripts from WSL2.

make build
make test
docker compose up --build -d

Register the three providers from a shell with access to the compose network. For a host-side gateway registry, use the ready-to-run helper after changing the provider URLs to http://localhost:8081, http://localhost:8082, and http://localhost:8083, or register through the API. The compose services use internal DNS names, so the simplest path is:

curl -X POST http://localhost:8080/api/v1/providers -H 'Content-Type: application/json' -d '{"id":"provider-a","name":"Research Lab A","base_url":"http://provider-a:8081","enabled":true,"timeout_ms":1500}'
curl -X POST http://localhost:8080/api/v1/providers -H 'Content-Type: application/json' -d '{"id":"provider-b","name":"Research Lab B","base_url":"http://provider-b:8081","enabled":true,"timeout_ms":1500}'
curl -X POST http://localhost:8080/api/v1/providers -H 'Content-Type: application/json' -d '{"id":"provider-c","name":"Research Lab C","base_url":"http://provider-c:8081","enabled":true,"timeout_ms":1500}'

Open http://localhost:3000 for the UI. The gateway is at http://localhost:8080, API documentation is at http://localhost:8080/docs, and Prometheus text metrics are at http://localhost:8080/metrics.

Search example:

curl -X POST http://localhost:8080/api/v1/resources/search \
  -H 'Content-Type: application/json' \
  -d '{"gpu":{"count":1,"minimum_memory_mib":30000,"minimum_compute_percent":50,"vendor":"NVIDIA"},"cpu":{"minimum_millicores":4000},"memory":{"minimum_bytes":17179869184},"strategy":"best-fit"}'

Architecture

flowchart LR
  UI[Web UI / REST client] --> G[Go federation gateway]
  G --> R[(Provider registry JSON repository)]
  G -->|concurrent HTTP fan-out| A[Provider A]
  G --> B[Provider B]
  G --> C[Provider C]
  A --> I[Typed inventory adapter]
  B --> I2[Typed inventory adapter]
  C --> I3[Typed inventory adapter]
  I --> K[Kubernetes / HAMi metadata]
  K --> H[nvml-mock fake GPU state]

Loading

HAMi handles GPU awareness and scheduling inside Kubernetes. The gateway handles discovery and ranking across provider boundaries; it does not reimplement the HAMi scheduler.

Repository Layout

• cmd/gateway: federation HTTP service.
• cmd/provider: normalized provider HTTP service with static and HAMi inventory modes.
• internal/resources: domain contracts and query validation.
• internal/discovery: concurrent fan-out, deadlines, filtering, and partial failure handling.
• internal/ranking: deterministic best-fit, most-available, binpack, and spread scoring.
• internal/storage: repository abstraction with atomic JSON persistence for local simplicity.
• internal/hami: Kubernetes API reader and HAMi annotation parser.
• internal/api: versioned gateway endpoints and machine-readable errors.
• web: lightweight responsive UI served by nginx in Compose.
• deploy, scripts: kind/HAMi manifests and reproducible local operations.
• docs: architecture, API, HAMi, testing, troubleshooting, and final user test guide.

Commands

Command	Purpose
make build	Build gateway and provider binaries
make test	Unit and package tests
make test-race	Race detector tests
make verify	Formatting, vet, tests, race tests, and builds
make dev	Start gateway, three providers, and UI with Compose
make stop	Stop the Compose stack
make bootstrap	Create kind cluster, install nvml-mock and HAMi, verify resources
make hami-verify	Inspect fake GPU and HAMi metadata
make logs	Collect Compose logs to stdout
make collect-debug	Write local and cluster diagnostics to artifacts/debug
make clean	Stop this project's Compose resources and remove build artifacts

HAMi Fake GPU Notice

The HAMi nvml-mock environment simulates GPU discovery and scheduling semantics. It does not provide a real CUDA runtime or real GPU compute. Actual memory/core enforcement, CUDA execution, DCGM telemetry, and hardware behavior require physical GPUs and are outside this local demonstration.

The static Compose providers intentionally model three logical provider inventories for federation testing. They are not three physically isolated GPU clusters. The INVENTORY_MODE=hami provider reads Kubernetes nodes and the HAMi hami.io/node-nvidia-register annotation when deployed in kind.

Testing

Run make verify for automated local validation. The integration path is separate because it requires running services. Final manual procedures, expected statuses, and evidence to inspect are in docs/USER_TESTING.md.

Limitations

• The registry is an atomic JSON repository rather than SQLite to keep the service CGO-free and easy to run on Windows, containers, and CI. The repository interface isolates this choice for a future SQL implementation.
• Reservations and workload execution are intentionally out of scope for V1.
• The kind/HAMi flow depends on Docker, kind, kubectl, Helm, and a Linux-compatible shell; Windows users should use WSL2.