Shuttle¶
Shuttle is a single Go binary deployed inside every customer Talos 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 Talos, 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 the OTel Collector 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
- Report per-service rollout status (progressing / complete / failed, with failure reasons) so deploy state surfaces in the dashboard (§25.4)
- 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
The sidebar is ordered as a build sequence: Orientation (architecture, security & isolation) → Build in order (repo structure → scaffolding → configuration → API contract → per-project resources → cluster RBAC) → Conventions (labels, annotations) → Operate & Reference (observability, failure modes, resources, success criteria, future enhancements).