Scaling Model¶
How a region grows — when a new cluster is added, what bounds the count, and how the load balancer resizes. Placement is per service-per-environment (FR-077); the thresholds below govern when Starbase opens a new cluster for new placements. On the self-managed Talos substrate, nodes are added manually (MVP) or by Shipyard (post-MVP) — there is no DOKS cluster-autoscaler; the scaling knob is the DO droplet quota.
| Customer Count | Clusters per Region | Trigger |
|---|---|---|
| 0–250 | 1 | Launch |
| 250–500 | 2 | 800 pod threshold |
| 500–750 | 3 | Continued growth |
| 750–1,000 | 4 | Continued growth |
Based on ~3.25 pods per customer average (1 web service + 1 DB + occasional worker/cache). Cluster soft limit is 1,000 pods; new cluster triggered at 800 for headroom.
Each cluster has: 1 Gateway, 1 DO LB, ~250 HTTPRoutes max. Routes distribute naturally across clusters so no single cluster hits Envoy Gateway's scaling limits.
Networking & quotas as a region scales: a region's clusters share one /16 VPC
(§4.4), so adding clusters/customers to a region adds
zero peerings — the control-plane VPC peers each regional VPC once (~12 at 12 regions, ≪ 50).
Cluster count is bounded by this table's route/blast-radius limits, not DO networking; the knobs
you actually turn are DO account soft-quotas (Droplets, Managed DB clusters, K8s clusters),
raised via support ahead of growth (§39.3 #47).
DO Load Balancer scaling: LB size units (1–200) controlled by Starbase via desired state — the
region adapter renders the cloud-specific annotation
(cluster_config.gateway_service_annotations, §25.1);
Shuttle applies it opaquely to the Envoy Gateway Service. DO CCM handles the actual resize API call.
Cross-references
The per-region VPC and IP plan → §4.4 · cluster topology → Cluster Topology · the load-balancer lifecycle → §34 · HTTPRoute naming (per-cluster route count) → §20.2 · DO account-quota work → §39.3. Canonical map: Canonical Sources.