Kubernetes Runtime & Isolation Model¶
The self-hosted Kubernetes layer. Starform's own platform runs on managed DOKS; customer workloads run on
self-managed Talos Linux + gVisor. (Design record:
specs/2026-07-05-compute-substrate-and-isolation-design.md.)
The split¶
- Starform platform (Starbase, Stardeck) → managed DOKS.
- Customer workload clusters → self-managed Talos Linux + gVisor on DO droplets, in the DO VPC.
- Managed databases (Micronova+) → DO Managed Postgres/Valkey — resold, unchanged.
DOKS cannot expose a custom RuntimeClass, so untrusted customer code runs on Talos, where gVisor sandboxing is available.
Talos stack¶
Each customer cluster is self-installed at bootstrap (§26.3):
- Talos Linux — immutable, API-driven OS; gVisor system extension baked into the machine config.
- Cilium (CNI, self-installed) — overlay/VXLAN + masquerade; kube-proxy replacement (
SYS_MODULEdropped, KubePrism:7445). - DO CCM —
Service type=LoadBalancer→ DO Load Balancer; requiresDO_CLUSTER_VPC_IDin a custom VPC. - DO CSI — block-storage volumes (
do-block-storage). - gVisor RuntimeClass (
gvisor/runsc) — customer web/worker pods; runc for everything else. - Disk encryption — Talos LUKS2 on the STATE + EPHEMERAL partitions (EPHEMERAL holds etcd data on
control-plane nodes; STATE holds node secrets/certs), AES-XTS-256, key sealed to the node
(
nodeID, TPM-upgradeable). Encrypts customer-cluster secrets at rest — closes stolen-disk / DO-volume-snapshot / offline-etcd exposure (FR-060).
Workload isolation¶
Customer code is untrusted, so two layers contain it — gVisor RuntimeClass on web/worker pods (FR-082) + a hardened PodSpec on every customer pod (FR-083), with dedicated Talos node groups as the Enterprise tier. The full pillar (hardening YAML, gVisor scope, shared-kernel risk register) lives on Shuttle › Security & Isolation.
Control-plane HA¶
3 control-plane nodes per cluster (etcd quorum). DO list cost ≈ $54–72/mo/cluster (3 × 2–4 GB droplets) — a vendor constraint, not a sell price.
This is HA against node failure, not datacenter failure: DO has no AZ concept, so a DO region is a single failure domain. A DC-level event takes the region; recovery is etcd DR (#59) + rebuild-from-desired-state, and customer resilience is multi-region placement (§39.3 #74). Never imply AZ redundancy in the SLA.
Machine lifecycle¶
MVP: clusters are provisioned and managed by hand with talosctl. Post-MVP: automated by
Shipyard.
Where talosctl runs from: the Talos API (:50000, mTLS) stays VPC-private,
never public. Each region gets a hardened jump droplet at onboarding — the operator SSHes in
and runs talosctl there; the regional talosconfig lives only on that droplet (per-region
blast radius). Post-MVP, Shipyard installs onto the same droplet — it is proto-Shipyard
(Region Onboarding).
- Node create/delete / scale — Starbase via the DO API; Talos machine config delivered as cloud-init user-data (no inbound reach needed).
- Worker upgrades — rolling replacement: Starbase creates new-version nodes, Shuttle drains the old (K8s API, its existing job), Starbase deletes the old.
- Control-plane upgrades — in-place via the Talos machine API (Shipyard; Talos self-cordons/drains and refuses quorum-breaking upgrades). gVisor updates ride the OS upgrade (machine-config extension). The manual runbook is pre-launch (§39.2 #66).
- etcd backup — an in-cluster CronJob → DO Spaces (the platform object store; not Tigris, which is the customer-facing primitive).
Operations that touch the Talos machine API (:50000, mTLS; endpoints proxy, so only the 3 control-plane
nodes need reach):
| Activity | Frequency | Talos API |
|---|---|---|
| Add/remove node (scale) | as needed | no — DO API + cloud-init |
| Cluster bootstrap (etcd init) | per new cluster | yes |
| etcd snapshot scheduling | scheduled | in-cluster CronJob; Shipyard owns the schedule |
| OS upgrade | ~quarterly | yes |
| Kubernetes upgrade | ~3×/yr | yes |
| CA rotation | ~yearly | yes |
| DR restore | rare | yes |
| Leaf cert rotation | automatic | no |
| Diagnostics | continuous | platform monitoring, §35.5 |
The recurring control-plane ops (the yes rows plus etcd-snapshot scheduling — bootstrap, OS/K8s upgrade, CA rotation, DR restore, snapshots) are run by Shipyard.
etcd disaster recovery¶
Pre-launch-blocking (§39.2). Scheduled in-cluster etcd snapshots →
DO Spaces (platform object storage); a rehearsed talosctl bootstrap --recover-from restore. A customer cluster's etcd is not the
source of truth — Starbase's DO-Managed Postgres is — so a lost cluster is rebuilt and re-reconciled from
desired state.
License¶
Talos Linux is MPL-2.0 (commercial and SaaS use permitted).
Networking¶
Cilium overlay masquerades pod egress to the node IP, so a customer pod reaches its Managed DB as the node
IP; DB Trusted Sources scope to the cluster/node tag and per-tenant isolation is the Cilium egress allowlist
(§4.4,
FR-075). Pod/service CIDRs are cluster-local overlays —
not VPC-routable, reusable across clusters — so the regional /16 VPC holds only nodes, DBs, LBs, telemetry,
and the ops/jump (later Shipyard) droplet.
Cross-references
Machine-lifecycle agent → Shipyard · workload/kernel isolation → Security & Isolation · component names → §1 · bootstrap sequence → §26.3 · SNAT / IP plan → §4.4 · ports & provisioning → Starbase › Ports · managed DBs → Managed Databases. Canonical map: Canonical Sources.