Skip to content

docs: Define the Galactic Worker contract and host ownership - #1445

Merged
privateip merged 1 commit into
integration/galactic-workerfrom
docs/issue-1431
Nov 18, 2026
Merged

privateip merged 1 commit into
integration/galactic-workerfrom
docs/issue-1431

Conversation

@privateip

Copy link
Copy Markdown
Collaborator

Summary

Galactic has no node-local API for service agents, and shared host state is written by many processes with separate locks or none.

This adds the Worker design pages that every Task of epic #1430 implements against. They cover the claim API with five worked transitions, one mutation authority per class of host state, the connector decision, the branch workflow and the qualification plan.

Transport, socket access, NIC and numeric limits were confirmed on 2026-11-18, and the remaining contract details are open to review here.

Branch evidence

The integration branch starts from a signed empty commit on top of the planning baseline, so its image tags never collide with tags main already published.

The publish run for that push published only the two integration-branch tags and the start commit's own tag, with no release and nothing tagged for main: https://github.com/datum-cloud/galactic/actions/runs/44399031276

Test plan

  • Documentation link and anchor check, lint, build, unit and Kind e2e pass locally
  • Every cited writer, constant and fence behavior was checked against the source at the branch start
  • Required CI passes against the integration branch

Fixes #1431

Galactic has no node-local API for service agents, and many processes
write shared host state through their own locks, or none. Epic #1430
replaces that with one Worker per node, and every later Task builds
against a written contract.

The new docs/worker pages record:

- the claim API: request, observe, update and release, keyed by caller,
  node, VPC and attachment UID, with generations, separate desired,
  programmed and observed state, five worked transitions, and the
  approved transport, identity and access model
- one mutation authority per class of host state: the owner of the
  scope's fence in internal/edge/ownership where several processes
  write, or the only writer otherwise, with today's writers and the
  step that moves each one; CNI writes with Exclusive so workload
  attach still works while Worker is down
- galactic-edge as the provider connector, behind a Worker-backed
  agent.Datapath, instead of a new binary
- the integration branch workflow, including why the branch starts
  from an empty commit: a branch push at the main SHA would overwrite
  main's multi-architecture v0.0.0-<sha> images with amd64-only ones
- the qualification platform, comparison method and confirmed limits

Two existing writers bypass any shared lock: the galactic-vrf sidecar's
BGPVRFInstance write, and five processes writing egress_route_table.
Both are listed as transfer steps.

Fixes: #1431

Co-Authored-By: Claude <claude@anthropic.com>
@privateip privateip self-assigned this Nov 18, 2026
@privateip
privateip marked this pull request as ready for review November 18, 2026 21:48
@privateip
privateip requested a review from a team as a code owner November 18, 2026 21:48
@privateip
privateip merged commit 550da21 into integration/galactic-worker Nov 18, 2026
28 checks passed
@privateip
privateip deleted the docs/issue-1431 branch November 18, 2026 21:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant