aether.registrar.v1 — The gRPC contract between a node agent and its cluster's registrar — the versioned endpoint snapshot, the watch stream that fans changes out to agents, and the cross-cluster configuration listing.
Rendered by protoc from api/aether/registrar/v1/ when this site was built, so it
cannot drift from the compiled schema — there is no committed copy of this page.
Field constraints are carried as buf.validate options and are not shown here;
read the .proto for those.
projections is the clusterset-wide set of service config projections, one per (service, origin cluster). origin_cluster is set authoritatively by the registry.
When set, the watch is scoped to filter.services: the initial snapshot and incremental events are limited to those services (demand-scoped distribution -- fan-out per endpoint change scales with the service's consumer count, not the node count). An explicitly set but empty filter watches nothing (a node with no mesh pods). Unset = full watch. Agents re-assert their filter on every reconnect; the registrar never serves less than asked.
instance
string
instance distinguishes two agents watching for the same node at once: a surge roll runs the new agent as a standby beside the old one (proposal 041), and keyed by cluster and node alone each one's watch would replace the other's — closing it with DataLoss, forcing a full resync, and ping-ponging for the whole overlap. The agent sends its pod name, so a container restart in the same pod still replaces its own stale watch. Empty keeps the cluster/node key (an agent that predates this field).
partial_resume lets a client whose watch filter GREW resume without a full resend (#1239). It is sent INSTEAD of last_version, which stays empty: a registrar that predates this field sees no token and resends in full, which is always safe. A registrar that knows it answers as for last_version = partial_resume.version, except that when the token names the current contents it sends, as ENDPOINT_ADDED events before SNAPSHOT_COMPLETE, only the endpoints of the filter's services that are NOT in partial_resume.services, and marks the SNAPSHOT_COMPLETE with extended = true. A token that does not name the current contents is answered with the full (filtered) snapshot as usual.
extended is set on the SNAPSHOT_COMPLETE of a watch start that honoured the request's partial_resume (#1239): the events before it were the missing services' endpoints, not a full snapshot. A client that sent a partial_resume and gets a marker without it was resent in full.
Sent by the server once the initial full snapshot has been fully streamed (or immediately when the client was already up-to-date). Carries the snapshot version; has no service_name/endpoint. Clients use it to know their cache is complete before deriving config from it. Also sent after the initial exchange, as a version-only marker (#1241): the registrar's version moved with nothing for this watcher (a store revision that changed no contents, or a change outside its filter), and the watcher's cache holds that version. The client adopts the version as its resume token; there is nothing to apply.
EVENT_TYPE_SERVICE_ADDED
6
Service-catalog events: a service exists while it has at least one endpoint in the registrar snapshot. Unlike endpoint events, these BYPASS the watch filter and reach every watcher (they are rare -- deploy-time transitions, not pod churn), giving each agent a full local index of service names: the on-demand (ODCDS) cold path answers existence locally instead of stalling on nonexistent services. The full catalog is replayed as SERVICE_ADDED events on every (re)connect before SNAPSHOT_COMPLETE. Carries service_name only.
ListAllConfig returns the clusterset-wide config projections (multi-cluster config propagation, proposal 026 Option E/C). Agents do NOT read the registry directly; the spoke registrar surfaces imported projections through this pull. A push stream (WatchConfig) is a later optimization; the pull is correct and eventually-consistent (AP), matching the import posture.