Shipyard¶
Shipyard is the per-region machine-lifecycle agent for the customer Talos fleet — it provisions, upgrades, and repairs the clusters that Shuttle runs workloads on. It completes the spine:
Starbase decides · Shuttle applies workloads · Shipyard applies machine lifecycle · Mass Relay carries the queries home (post-MVP, §39.3 #43).
Both Shuttle and Shipyard are distributed agents that pull desired state outbound from Starbase and apply
it locally — Shuttle at the Kubernetes-workload layer (inside each cluster), Shipyard at the machine/OS layer
(per region). (Post-MVP; at MVP the machine layer is operated by hand with talosctl. Kubernetes Runtime:
Machine lifecycle. Design record:
specs/2026-07-05-compute-substrate-and-isolation-design.md.)
Placement & reachability¶
One Shipyard per region — a dedicated, hardened DO droplet inside the regional VPC, managing every customer
cluster in that region. The droplet itself exists from region onboarding (MVP: the operator's
SSH jump host for talosctl, holding the regional talosconfig —
Region Onboarding); Shipyard is the software that
later lands on it.
- Outbound-pull. Shipyard pulls fleet desired state from Starbase over HTTPS; Starbase never dials customer nodes (FR-085) — the same inversion as Shuttle, one layer down.
- In-VPC reach, bounded. It holds the region's
talosconfig(mTLS) and reaches the Talos machine API (:50000) on the control-plane nodes only — Talos endpoints proxy to workers, so 3 nodes per cluster cover the whole cluster. - Not Shuttle, by design. The Talos machine API controls the OS (reboot, wipe, upgrade), a different trust domain from Shuttle's Kubernetes RBAC; and a machine agent must survive the node reboots it triggers, which an in-cluster Shuttle cannot. So Shipyard runs off-cluster and holds no Kubernetes credentials; Shuttle holds no Talos credentials.
What Shipyard runs¶
The recurring control-plane day-2 operations. Node create/delete and scaling stay with Starbase (DO API + cloud-init); worker upgrades are rolling replacement (Shuttle drains); etcd backup is an in-cluster CronJob. Shipyard owns the operations that must touch the Talos machine API:
| Operation | Frequency |
|---|---|
| Talos OS upgrade (control-plane) | ~quarterly |
| Kubernetes upgrade | ~3×/yr |
| CA rotation | ~yearly |
| etcd-snapshot scheduling | recurring |
| Cluster bootstrap (one-time etcd init) | per new cluster |
DR restore (bootstrap --recover-from) |
rare |
Talos self-protects the dangerous parts — it refuses a control-plane upgrade that would break etcd quorum and self-cordons/drains during upgrades.
Repo & code¶
Ships from starform/shipyard as its own Go binary. It shares the DO-adapter and desired-state code with
Starbase via a common library (§9) but is deployed separately, to
regional droplets, in its own trust domain.
Cross-references
The substrate it manages → Kubernetes Runtime · the workload agent it's siblings with → Shuttle · never-dial-nodes rule → FR-085 · component names → §1 · open-work item → §39.3. Canonical map: Canonical Sources.