feat(forge): composable multi-cluster Kubernetes development environment

[shaneutt]

Summary

Create praxis-forge, a general-purpose Rust CLI that orchestrates multi-cluster KIND environments from a single YAML config. Replaces both cargo xtask env and hack/setup-kind.sh with a unified tool supporting composable deployment stacks, cross-cluster networking, mTLS certificates, and MaaS + llm-d simulation.

Starts as a grid workspace crate at forge/. Designed for extraction to praxis-proxy/forge - zero grid-specific dependencies, no grid identity in code.

Motivation

The grid workspace has two disjoint, incomplete environment paths: xtask creates bare clusters with inference-sim and mock containers but no networking or CRDs; hack/setup-kind.sh installs MetalLB and Gateway API but only for a single cluster. Neither supports composable stacks, cross-cluster connectivity, or the MaaS + llm-d CRD surface needed for realistic AI inference simulation.

YAML Configuration

A single forge.yaml defines:

• Clusters - ordered list with node counts, arbitrary properties (e.g., models, region), and stack references
• Services - host-level Docker/Podman containers with port mappings and args
• Stacks - composable deployment profiles: ordered sequences of typed steps applied per-cluster
• Certificates - CA + per-cluster site certs with optional K8s Secret distribution
• Networking - cross-cluster MetalLB, Gateway API, CoreDNS patching

Step Types

url | manifest | kustomize | helm | deployment | service | wait | exec | for-each | metallb-auto-pool

Stacks reference cluster properties via {{ .Property.x }} templates and argsFromProperty for deployment args. for-each iterates over property arrays (e.g., generating one InferenceModel per model).

CLI

praxis-forge up [--clusters a,b --skip-stacks --parallel]
praxis-forge down [--clusters a,b --keep-services --force]
praxis-forge status [--json --watch]
praxis-forge apply [--stack <name> --clusters a,b]
praxis-forge cluster create|delete|list|kubeconfig|load-image|exec
praxis-forge service start|stop|list|logs|build
praxis-forge certs generate|distribute|rotate|status|clean
praxis-forge stack list|apply|status
praxis-forge config validate|show|init|schema

Env vars: FORGE_CONFIG, FORGE_STATE_DIR, FORGE_CONTAINER_RUNTIME, FORGE_LOG, FORGE_CLUSTER_PREFIX.

MaaS + llm-d Integration

Ship stack definitions that deploy the Kubernetes API surface for AI inference simulation:

Production Component	KIND Simulation
vLLM on GPUs	llm-d-inference-sim (no GPU)
llm-d Router/EPP	InferencePool CRD (passive)
KServe InferenceService	InferenceModel CRD
Gateway API	Standard CRDs
MaaS controller	CRDs only (optional, no controller)
Authorino / Limitador	Skipped

Default config ships stacks: gateway-api, metallb, inference (Inference Extension CRDs + llm-d-inference-sim + InferencePool/InferenceModel), and optional maas-crds.

Architecture

• Crate: forge/ as workspace member. Depends on clap, rcgen, serde, serde_yaml, serde_json, thiserror, tracing. No tokio, kube, or grid crates.
• Execution: Synchronous std::process::Command via a CommandRunner trait (mockable for unit tests).
• State: .forge/state.json tracks clusters, services, stacks, certs for idempotent operations.
• Extraction path: Inline workspace dep versions, copy crate to praxis-proxy/forge, publish. No code changes.

Implementation Phases

1. Core CLI + Clusters - clap CLI, YAML schema, KIND cluster lifecycle, state store
2. Services + Certificates - Docker/Podman container management, rcgen cert generation, K8s Secret distribution
3. Stack Engine - step types, executor, template substitution, for-each
4. Networking - MetalLB auto-pool, Gateway API CRDs, CoreDNS cross-cluster patching
5. Default Stacks - forge.yaml for grid, documentation
6. Migration - update Makefile, deprecate xtask env, remove hack scripts

Verification

• Unit tests with CommandRunner mock (no Docker/KIND needed)
• config validate on default YAML
• Full up/status/down cycle: 3 clusters, stacks applied, services running, certs distributed, cross-cluster DNS

References

• models-as-a-service
• llm-d
• Gateway API Inference Extension