Cluster Topology¶
The component inventory per plane: what lives in the control-plane region, what runs in each customer cluster, and what stays external. The same picture as a theme-aware diagram is in System Topology.
4.1 Control-Plane Region & Regional Telemetry (control plane: one region at MVP)¶
Substrate split (Kubernetes Runtime): the Starform platform (Starbase, Stardeck) runs on managed DOKS; customer workload clusters run on self-managed Talos + gVisor (§4.2).
- At MVP the whole platform runs in a single region — but the control plane runs in its own VPC, peered to that region's VPC. The two VPCs are always separate (§4.4); single-region MVP just means one peering.
- Shuttles pull desired state from the control plane, and Starbase reads that region's telemetry store over that private VPC peering to render dashboards.
- What's built but dormant until you add a 2nd region is the cross-region read — the query-broker fan-out and the additional per-region peerings (FR-071); it fans out per region once you expand (v2 Read & query).
- The telemetry store runs per region on a DO VM droplet (not in Kubernetes) — a single-node stateful store is simpler and cheaper on a dedicated droplet than as an in-cluster StatefulSet, and this matches DO Managed Postgres/Valkey already living off-cluster.
Single-region control plane — a SPOF by decision
The control plane is central at MVP. Running workloads survive an outage via Shuttle's level-driven loop, but new deploys and dashboards stop. Distributing it needs a distributed DB (Fly's path) and is out of near-term scope — seeded in §39.3.
Control-plane region — infra cluster + managed services:
| Component | Purpose |
|---|---|
| Starbase API | HTTP server for dashboard, Shuttle, webhooks; telemetry-query broker (injects the server-side tenant filter, v2 Read & query / FR-065; routes each query to the region(s) hosting the environment's services, FR-071) |
| Starbase Worker | Background jobs (builds, provisioning, billing) |
| Stardeck (Next.js) | Customer dashboard |
| DO Managed Postgres | Starbase database |
| DO Container Registry | Customer app images — one registry per region (DO multi-registry, regional placement); at single-region MVP that means one, co-located here. Builds push to the placement region's registry (§16.2) |
Regional telemetry — per region, one DO VM droplet (off-cluster), plus the ops/jump droplet:
| Component | Purpose |
|---|---|
| ClickHouse (VM droplet) | Customer logs and metrics — request rows (otel_http, the L7 metric source), app logs (otel_logs), cAdvisor meters (otel_metrics_*); per-plan TTL retention (v2 Store); read by Starbase through the read-only user + server-side tenant filter (FR-065); the billing audit trail joins post-MVP (§39.3 #71) |
| OTel Collector gateway | Regional ingest fan-in — validates the per-cluster tokens (FR-066), batches, and is the sole ClickHouse writer; a process on the telemetry droplet (v2 Collect) |
| Ops/jump droplet | Hardened in-VPC droplet, provisioned at region onboarding — MVP: operator SSH + talosctl (holds the only copy of the regional talosconfig); post-MVP: Shipyard installs onto this same droplet |
- One telemetry droplet per region — ClickHouse plus the OTel gateway process; sized for ClickHouse (disk/memory-heavy).
- The shared regional VPC keeps intra-region ingest at $0 — same-VPC traffic, no peering (§4.4); peering carries only cross-region reads (FR-071).
- Platform self-monitoring is offloaded to Grafana Cloud (§35.5) — there is no internal metrics store or Alertmanager at MVP.
4.2 Customer Cluster (one or more per region, lean)¶
Customer clusters run self-managed Talos Linux + gVisor on DO droplets — not DOKS (the Starform platform cluster is DOKS; see Kubernetes Runtime). On Talos the whole stack below is self-installed at bootstrap (§26.3); nothing is "bundled".
| Component | Type | Purpose |
|---|---|---|
| Talos Linux | Node OS | Immutable, API-driven; gVisor extension in the machine config |
| Cilium | CNI (self-installed) | Overlay/VXLAN networking + kube-proxy replacement |
| DO CCM | Deployment | Service type=LoadBalancer → DO LB (DO_CLUSTER_VPC_ID) |
| DO CSI | Deployment | Block-storage volumes (do-block-storage) |
| Shuttle | Deployment (1 replica) | Agent — applies desired state, reports snapshots/capacity |
| Envoy Gateway | Deployment (2+ replicas) | Traffic routing via HTTPRoute, future JWT/JWKS/ext_authz; also the source of the L7 metrics — its access logs become otel_http rows (latency, RPS, throughput, error rate) |
| OTel Collector | DaemonSet | The one telemetry agent — tails app logs, receives Envoy access logs (EG's OTel sink), scrapes kubelet/cAdvisor; stamps tenant identity (k8sattributes + route metadata) and ships to the regional OTel gateway → ClickHouse (v2 Collect). Light agent; batching lives at the gateway |
| metrics-server | Deployment | Resource metrics (CPU/mem) via the K8s Metrics API for HPA and kubectl top. Installed at bootstrap (Section 26.3) |
| kube-state-metrics | Deployment | Cluster object state — scraped by Grafana Alloy for the platform plane (§35.5); not on the customer attribution path |
| node-exporter | DaemonSet (bundled by the k8s-monitoring chart) |
Host metrics per node (disk, inodes, memory, load) — feeds the platform plane (§35.5) |
| Grafana Alloy | Deployment (k8s-monitoring Helm chart; its bundled KSM disabled) |
Platform self-monitoring agent — scrapes Starform-component series (Shuttle, Envoy gateway-self, node-exporter, KSM platform objects) and the Talos substrate (etcd, kube-apiserver, Cilium) and remote_writes a paging keep-list + per-cluster liveness series to Grafana Cloud (§35.5). A separate agent from the customer OTel Collector, so the platform-monitoring path is independent of the customer pipeline. The same agent also runs on the DOKS platform cluster |
No cert-manager, no Cilium Gateway, no Istio, no service mesh. Customer web/worker pods run under the gVisor RuntimeClass (Kubernetes Runtime).
4.3 External Services (not in any cluster)¶
| Service | Purpose |
|---|---|
| Cloudflare | CDN, DNS, WAF, DDoS protection, TLS termination (edge + origin cert) |
| Stripe | Payments, subscriptions, invoicing |
| Depot SaaS | Build execution (remote BuildKit; Railpack frontend + Dockerfile fallback) |
| Tigris | Customer object-storage primitive (Partner Integration API; isolated tenant per workspace; zero egress) — post-MVP (§39.3 #16). Platform object storage is DO Spaces (etcd snapshots, build-log archive) |
| GitHub / GitLab / Bitbucket | Source code, webhooks |
| Grafana Cloud | Platform self-monitoring — hosted metrics + Grafana Alerting + OnCall for Starform's own components (§35.5). MVP-only; revisit post-MVP |
VPC & IP topology → §4.4 (owned by Networking).
Cross-references
The topology diagram → System Topology · per-region VPC / IP plan → §4.4 · the telemetry transport (peering, $0 intra / $0.01-GiB cross-region) → FR-071 · platform self-monitoring → §35.5 · how it scales → Scaling Model. Canonical map: Canonical Sources.