Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ with the [system overview](overview.md) for components and ownership, or
| Inspect metrics and alerts | [Observability](observability/README.md) |
| Look up API resources | [API reference index](api/README.md) |
| Evaluate a proposal or remaining implementation work | [Designs](designs/README.md) |
| Follow the Galactic Worker integration branch | [Worker contract](worker/README.md) |
| Find a dated review or test result | [Archive](archive/README.md) |
| Change this documentation | [Documentation maintenance](development/documentation.md) |

Expand Down
1 change: 1 addition & 0 deletions docs/designs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ These documents explain decisions and planned work. Their status describes imple
| [Interface traffic policy](interface-traffic-policy.md) | Implemented design; rollout remains explicit | [Rollout](../traffic-policy/rollout.md) and [node behavior](../traffic-policy/node.md) |
| [Galactic Edge](galactic-edge.md) | Partially implemented and subject to qualification | [Provider contract](../edge/provider-contract.md) and its open items |
| [Private Service Connect](private-service-connect.md) | Partially implemented; qualification gaps remain | [Private-service routes](../private-services/README.md) |
| [Galactic Worker](../worker/README.md) | Proposed; built on `integration/galactic-worker` | [Branch workflow](../worker/branch-workflow.md) |
| [Looking Glass backend service](looking-glass-service.md) | Proposed implementation contract; authentication scaffolding does not enable service execution | [Current fabric-api](../fabric-api/README.md) |
| [Shared DNS64](dns64/README.md) | Proposed; end-to-end validation outstanding | [NAT configuration](../nat/configuration.md) for implemented translation |
| [Latency-aware routing](latency-aware-routing.md) | Exploratory proposal | [Router configuration](../router/configuration.md) for available settings |
Expand Down
44 changes: 44 additions & 0 deletions docs/worker/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Galactic Worker

Galactic Worker is a proposed node-local service. Service agents use it to
deliver tenant traffic locally or across the fabric, and it becomes the single
writer of shared host state. These pages are the contract for
[epic #1430](https://github.com/datum-cloud/galactic/issues/1430). Every Task of
the epic implements against them on the `integration/galactic-worker` branch.

Status: proposed. Nothing described here is implemented at the branch start.

| Page | Contents |
| -------------------------------------- | ----------------------------------------------------------------------------------------- |
| [Service contract](contract.md) | Claims, operations, state model, errors, versions, trusted sources and worked transitions |
| [Host state ownership](ownership.md) | Writer inventory, one authority per resource class, bootstrap, adoption and transfer |
| [Connector decision](connector.md) | Which component is the provider connector, and its entry point |
| [Branch workflow](branch-workflow.md) | Base and start SHAs, PR target, CI, artifact tags and how Tasks close |
| [Qualification plan](qualification.md) | Platform, handoffs, workload, comparison method and limits |

## Decision log

"Accepted" means the epic coordinator approved the decision. "Proposed" means
the decision was set while writing this contract and is open to review on its
PR. "Confirmed" means the product owner approved the decision on the date given.

| ID | Decision | Status | Page |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------- |
| D1 | A claim is keyed by caller, node, VPC and attachment UID, and versioned by a client-assigned generation | Proposed | [Contract](contract.md#claims) |
| D2 | Desired, programmed and observed state are kept and reported separately | Proposed | [Contract](contract.md#state-model) |
| D3 | Every mutating call is idempotent per generation; retries use bounded backoff | Proposed | [Contract](contract.md#errors-and-retry) |
| D4 | Only the owner releases a claim, and only at its current generation | Proposed | [Contract](contract.md#operations) |
| D5 | Session lease of 120 s renewed every 10 s, the XDP dispatcher's values | Proposed | [Contract](contract.md#sessions-restart-and-stale-deletion) |
| D6 | gRPC status codes with machine reasons | Proposed | [Contract](contract.md#errors-and-retry) |
| D7 | Protobuf package `galactic.worker.v1alpha1`, negotiated through `GetCapabilities` | Accepted | [Contract](contract.md#version-negotiation) |
| D8 | gRPC over a host unix socket; projected ServiceAccount token with TokenReview, `SO_PEERCRED`, and a static ServiceAccount-to-capability allowlist | Confirmed 2026-11-18 | [Contract](contract.md#transport-identity-and-access) |
| D9 | `hostPath` socket mount, including for the galactic-vrf sidecar, which does not use the host network | Confirmed 2026-11-18 | [Contract](contract.md#transport-identity-and-access) |
| D10 | Trusted sources for locator, VPC, owner, backend SID and policy | Accepted | [Contract](contract.md#trusted-sources) |
| D11 | Own locator resolves to Local, any other to Fabric, with no fallback from Local to Fabric | Proposed | [Contract](contract.md#resolution) |
| D12 | One mutation authority means owning the scope's fence, or being a class's only writer; CNI writes with `Exclusive` | Accepted | [Ownership](ownership.md#what-one-mutation-authority-means) |
| D13 | Bootstrap, adoption and transfer use the `internal/edge/ownership` fence, generalized | Accepted | [Ownership](ownership.md#bootstrap-adoption-and-transfer) |
| D14 | The connector is `cmd/galactic-edge` with a Worker-backed `agent.Datapath` | Accepted | [Connector](connector.md) |
| D15 | Branch workflow with start commit `451eb40` | Accepted | [Branch workflow](branch-workflow.md) |
| D16 | NIC: Broadcom NetXtreme-C/E (`bnxt_en`) in generic mode; native mode on lab veth devices | Confirmed 2026-11-18 | [Qualification](qualification.md#platform) |
| D17 | Comparison against the main base on the same host, using the MASQUE benchmark method | Proposed | [Qualification](qualification.md#comparison-method) |
| D18 | Numeric limits | Confirmed 2026-11-18 | [Qualification](qualification.md#limits) |
74 changes: 74 additions & 0 deletions docs/worker/branch-workflow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Integration branch workflow

Status: in use (D15). Every Task of
[epic #1430](https://github.com/datum-cloud/galactic/issues/1430) follows it.

## Branch and base

| Item | Value |
| ------------ | ------------------------------------------------------------------------------------------------------------ |
| Branch | `integration/galactic-worker` |
| Main base | `11323a99642aecb0e53220c1dbc49f61652f0b52`, the planning baseline and the comparison point for qualification |
| Branch start | `451eb40ec1ee6238f1e59dfeda8d69e594a4d8a8`, a signed empty commit whose parent is the main base |
| PR target | `integration/galactic-worker`, for every implementation and evidence PR |

### Why the start commit exists

`publish.yaml` tags images and the bundle with the short commit SHA,
`v0.0.0-<sha>`. If the branch started at the main base, its first push would
publish `v0.0.0-11323a9` again. A branch build is amd64 only, so that push
would replace the multi-architecture images main already published under the
same tag. The empty start commit gives the branch its own SHA, and every later
commit on the branch has a SHA that main does not.

### Upstream changes

The branch takes changes from `main` only on purpose. Record each one here,
with the main commit and the reason, in the PR that brings it in.

| Main commit | Brought in by | Reason |
| ----------- | ------------- | ------ |
| None yet | | |

## CI

`ci.yaml` and `required-ci.yaml` run on `pull_request` without a base-branch
filter, so they run on every PR to `integration/galactic-worker`. Each PR runs
`task ci` locally before review and reports the CI runs against its base.

## Artifacts

`publish.yaml` runs on every branch push. The reusable workflows in
`datum-cloud/actions` (pinned at `v1.27.1`) tag a push to
`integration/galactic-worker` as follows:

| Tag | Meaning |
| ---------------------------------------------------- | ----------------------------------------------------------------- |
| `v0.0.0-integration-galactic-worker` | Moves with every push to the branch |
| `v0.0.0-integration-galactic-worker-YYYYMMDD-HHmmss` | One per push, from the commit date |
| `v0.0.0-<short-sha>` | One per commit, for example `v0.0.0-451eb40` for the start commit |

Branch images are amd64 only. The workflow publishes images for every
component except `galactic-debug`, which publishes only from `main` and release
tags, and a `galactic-kustomize` bundle. A branch push never moves
`v0.0.0-main`, which the staging labs follow, and never creates a `v*` release.
Qualification ([#1442](https://github.com/datum-cloud/galactic/issues/1442))
pins artifacts by `v0.0.0-<short-sha>`.

Pushing a Task's own branch (for example `docs/issue-1431`) also runs
`publish.yaml` and tags `v0.0.0-<that-branch>`. Those artifacts are for review
only and are never used for qualification.

The [publish run for the push of the start commit](https://github.com/datum-cloud/galactic/actions/runs/44399031276)
is the evidence that branch pushes publish only the tags above.

## Closing a Task

1. The PR targets `integration/galactic-worker`, carries the Task's acceptance
evidence, and says `Fixes datum-cloud/galactic#<task>`.
2. GitHub closes issues only from merges to the default branch, so after the
merge, check the PR's base and merged SHA.
3. Close the Task by hand with a comment naming the PR and the merged SHA.
4. Keep the epic open until the integrated evidence of #1442 is reviewed.
Merging the branch into `main`, publishing a release and rolling out to the
fleet each need a separate decision.
44 changes: 44 additions & 0 deletions docs/worker/connector.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Connector decision

Status: decided (D14). [#1440](https://github.com/datum-cloud/galactic/issues/1440)
implements it.

## Decision

The provider connector is the existing `galactic-edge`. No `galactic-connector`
binary is created.

| Item | Value |
| ----------- | --------------------------------------------------------------------------------------------- |
| Name | `galactic-edge` |
| Entry point | `cmd/galactic-edge` |
| Seam | `internal/edge/agent.Datapath` (`internal/edge/agent/agent.go:75`) |
| Change | A Worker-backed `Datapath` replaces `agent.PinnedDatapath` (`cmd/galactic-edge/main.go:197`). |
| Conformance | `tests/edgeconformance`, plus the independent provider in `examples/edge-provider` |

## How it works

`agent.Datapath` has four methods: `Register`, `Unregister`, `Forget` and
`SyncRoutes`. Today `PinnedDatapath` implements them by writing the pinned maps
directly through `attachreg`. The Worker-backed implementation turns them into
Worker calls instead:

- `Register` becomes a `Request` (or an `Update` with a new generation) for a
`routed_link` claim on the EdgeAttachment, carrying the host link.
- `SyncRoutes` becomes an `Update` that replaces the claim's destinations.
- `Unregister` and `Forget` become a `Release`.

galactic-edge keeps everything specific to providers: admission of the
EdgeAttachment, the gates, provider status and the contract with provider pods.
Worker admits a connector claim only while its EdgeAttachment is `Admitted`, and
withdraws it when admission is revoked.

## Why not a new component

- galactic-edge already registers host links through `attachreg`, takes the
per-VPC ownership fence that [ownership](ownership.md) generalizes, and is
covered by `tests/edgeconformance`. A new binary would duplicate all three.
- The `Datapath` interface is already the boundary between provider handling
and host programming, so the change stays inside one implementation of it.
- Providers that already ship, including the MASQUE provider, keep their
contract with galactic-edge unchanged.
Loading
Loading