Repository navigation
Closed
Description
Parent: Deliver Galactic Worker with Local and Fabric delivery for tenant services
Deliverable
A versioned Worker contract, a single-writer ownership table, the integration-branch workflow and the qualification plan, checked in under docs/worker/ on integration/galactic-worker. It satisfies the contract half of the "Establish contract and baseline" phase exit, and every later Task implements against it.
No Worker or node-local service API exists at the baseline. Today several processes write shared host state through pinned BPF maps, CRDs and file locks. The ownership table starts from these writers:
- Host VRFs and table IDs:
internal/plumbing/vrf(EnsureAndEnslave,Locked,DeleteIfUnused, ranges invrf.goandreservation.go). - Per-node VPC state and arguments:
internal/nodevpc(Ensure,ClaimArgument,AllocateArgument), called frominternal/cnibgp,internal/edge/agent/vpcstate.go,internal/edge/hostattach,cmd/galactic-edgeandinternal/gc. - Datapath registration:
internal/plumbing/ebpf/attachreg(RegisterDatapath,RegisterTenantGateway,RegisterHostLink,SyncHostLinkRoutes,UnregisterInterface). - Sidecar host return:
internal/installer/sidecarreturn.goandsidecarreap.go. - Garbage collection:
internal/gc(RunGC,SweepEBPFVRFTable). - XDP dispatcher slots and leases:
internal/plumbing/ebpf/xdpdispatch. - Pin directories
/sys/fs/bpf/galactic,galactic-nat,galactic-edgeandgalactic-xdp.
Work items
- Define request, observe, update and release semantics keyed by caller, physical node, VPC, attachment UID and generation. Specify capability discovery, errors, retry, idempotency, restart and stale deletion. Choose transport, client identity, version negotiation and the host and pod access model. Name the trusted source for physical locator, authorized VPC, owner and backend SID. Model desired, programmed and observed state separately.
- Inventory every writer of VRF, table ID, argument, route, BGP advertisement, BPF attachment, pinned map and dispatcher slot, starting from the list above. Define bootstrap with Worker down, adoption of preexisting state, ownership transfer and cleanup after partial application. Service-specific state stays in its service agent.
- Decide whether "galactic-connector" is a new component or the existing
cmd/galactic-edgeadapted behindinternal/edge/agent.Datapath, and record the name and entry point T10 uses. - Record the branch workflow: base SHA, PR target, CI invocation, artifact tags and how Tasks close.
- Agree the qualification platform: target kernel, NIC, XDP attach modes (
internal/plumbing/ebpf/xdpmode), handoffs for Prove the Local kernel handoffs on the agreed platform #1444 to prove, workload, comparison method and numeric performance limits.
Dependencies
None. Can start now.
Acceptance
- The contract carries a worked state transition for each of these cases: a duplicate request, a stale release, an unauthorized cross-VPC claim, a local locator with a missing TAP, and a withdrawal during repair.
- The ownership table assigns each resource class exactly one mutation authority and names today's writer and the transfer step for each.
- Every contract case names its design decision and the Task that owns its test.
- The connector decision, the platform and numeric limits are recorded. No limit is left as "to be decided".
- The PR shows
ci.yamlandrequired-ci.yamlrunning against baseintegration/galactic-worker. It also links apublish.yamlrun for the branch push that published onlyv0.0.0-integration-galactic-worker*andv0.0.0-<sha>tags, with nov*release and nov0.0.0-mainbundle. - The delivering PR targets
integration/galactic-worker, carries this evidence and saysFixes datum-cloud/galactic#1431. GitHub does not auto-close from a non-default base, so close this issue explicitly when the PR merges and record the PR and merged SHA.
Metadata
Metadata
Assignees
Labels
No labels
Type
Fields
Priority
None yet
Activity
privateip commentedon Nov 18, 2026
Verdict: valid. At
11323a99642aecb0e53220c1dbc49f61652f0b52there is no Worker or node-local mutation API. The only node-local listeners are read-only: fabric-api queries over mTLS, the GoBGP socket behind a method allowlist, and gRPC health. Shared host state has many writers, each with its own coordination:tables.jsonreservationsinternal/edge/ownership, which only galactic-edge and its maintenance path use todayTwo writers have no cross-process coordination:
internal/ingresssidecar/gateway.go:273writesBGPVRFInstancewithout the Argument lock.internal/nodevpc/argument.go:91acknowledges that collision.egress_route_tablerows come from five processes with no shared lock: galactic-router, galactic-bgp, the galactic-vrf sidecar, galactic-cni (installer, repair and sweeps) and galactic-edge.Approved plan
The design docs go under
docs/worker/onintegration/galactic-worker, starting from branch commit451eb40ec1ee6238f1e59dfeda8d69e594a4d8a8.README.mdcontract.mdownership.mdconnector.mdbranch-workflow.mdqualification.mdDecisions grounded in the current code:
internal/edge/ownership(Fence, Adopt, CommitSnapshot, resync-required after a failed commit, Exclusive for GC). While Worker is down, CNI writes under a ticket, so workload attach never depends on Worker being available.galactic.worker.v1alpha1. A Capabilities RPC negotiates the version and features.galactic-connectorbinary.cmd/galactic-edgestays the connector, with a Worker-backedinternal/edge/agent.Datapath.These are proposals pending confirmation:
Each of the five worked transitions names its design decision and the Task that owns its test.
Validation:
task docs:check,task lintandtask ci.privateip commentedon Nov 18, 2026
Delivered by #1445, merged into
integration/galactic-workeras 550da21. The contract, ownership table, connector decision, branch workflow and qualification plan are indocs/worker/on that branch.