Shuttle¶
Shuttle is a single Go binary deployed inside every customer DOKS cluster (or any Kubernetes cluster — the agent is cloud-agnostic). It is the only Starform component that interacts with the Kubernetes API in customer clusters. It deploys customer workloads, reports cluster capacity, and collects billing metering data — all driven by desired state pulled from Starbase. This is the "applies" half of "Starbase decides, Shuttle applies."
Shuttle is cloud-agnostic. It talks only to the Kubernetes API and the Starbase HTTP API. It works on DOKS, EKS, GKE, or bare metal without code changes. This property is what would enable Starform-operated multi-cloud regions for geographic expansion (§12); it also would permit BYOC, but BYOC is not a current offering (out of scope, §37).
Goals:
- Deploy customer workloads to Kubernetes based on desired state pulled from Starbase
- Manage project namespace lifecycle including per-project isolation resources (RBAC, NetworkPolicy, ResourceQuota, LimitRange)
- Apply correct labels to all customer resources so Fluent Bit and vmagent can attribute logs and metrics to the right customer
- Report cluster capacity (pod count) so Starbase can make placement decisions and trigger cluster provisioning at the 800-pod threshold
- Meter billing by periodically snapshotting pod state and streaming to Starbase
- Apply cluster infrastructure config (LB scaling, future SecurityPolicies) from desired state
- Reconcile drift between desired state and actual cluster state
- Survive disconnections from Starbase without losing customer workloads
- Run lean — single binary, minimal resource footprint, no external dependencies beyond Kubernetes
§18 Shuttle Non-Goals (MVP)¶
In MVP
The following are explicitly out of scope for the MVP release and are added in later phases once the MVP is shipping to paying customers.
- High availability via leader election (1 replica is acceptable for MVP)
- Write-ahead log (WAL) for fault-tolerant snapshot buffering
- mTLS authentication (bearer token over TLS is sufficient for MVP)
- gRPC streams (HTTP polling is simpler and sufficient)
- Custom domain / TLS certificate lifecycle management
- Database provisioning (Starbase responsibility)
- Build job triggering (Starbase responsibility)
- Support for custom metrics or user-provided telemetry
Use the left sidebar for the full Shuttle reference — architecture, per-project resources, labels, annotations, the API contract, observability, failure modes, scaffolding, and more.