etcd

Documentation

Overview

Package etcd implements the Registry interface using etcd as the backend.

Keys are region-scoped and origin-first (proposal 006): each region owns a contiguous authoritative subtree, so a cross-region replicator mirrors one deterministic prefix and partitions stay disjoint regardless of pod-CIDR overlap across clusters. Full key layout:

<root>/<region>/clusters/<cluster>/ns/<namespace>/services/<service>/protocols/<protocol>/endpoints/<ip>

A registry instance OWNS one (region, cluster): it writes/deletes only under its own partition, but reads (List*, watch) range the whole root so consumers see the union of every region's local-authoritative and mirrored-in endpoints.

Index

• Constants
• type Config
• type EtcdRegistry
  • func NewEtcdRegistry(log *slog.Logger, cfg Config) *EtcdRegistry
  • func (r *EtcdRegistry) Changes() <-chan struct{}
  • func (r *EtcdRegistry) Client() *clientv3.Client
  • func (r *EtcdRegistry) Close() error
  • func (r *EtcdRegistry) Initialize(ctx context.Context) error
  • func (r *EtcdRegistry) ListAllEndpoints(ctx context.Context, protocol registryv1.Service_Protocol) (map[string][]*registryv1.ServiceEndpoint, error)
  • func (r *EtcdRegistry) ListConfig(ctx context.Context) ([]*registryv1.ServiceConfigProjection, error)
  • func (r *EtcdRegistry) ListEndpoints(ctx context.Context, service string, protocol registryv1.Service_Protocol) ([]*registryv1.ServiceEndpoint, error)
  • func (r *EtcdRegistry) ListExports(ctx context.Context) ([]export.ServiceExport, error)
  • func (r *EtcdRegistry) OwnPrefix() string
  • func (r *EtcdRegistry) RegisterEndpoint(ctx context.Context, serviceName string, protocol registryv1.Service_Protocol, ...) error
  • func (r *EtcdRegistry) SetConfig(ctx context.Context, projection *registryv1.ServiceConfigProjection) error
  • func (r *EtcdRegistry) SetExport(ctx context.Context, service, namespace string) error
  • func (r *EtcdRegistry) UnregisterEndpoint(ctx context.Context, serviceName string, ip string) error
  • func (r *EtcdRegistry) UnregisterEndpoints(ctx context.Context, serviceName string, ips []string) error
  • func (r *EtcdRegistry) UnsetConfig(ctx context.Context, service string) error
  • func (r *EtcdRegistry) UnsetExport(ctx context.Context, service string) error

Constants

const (
	// DefaultKeyPrefix is the default root prefix for all registry keys in etcd.
	// Every region's subtree hangs off this root; see the package doc for the
	// full key layout.
	DefaultKeyPrefix = "/aether/v1/regions"

	// DefaultRegion and DefaultCluster scope a registry's OWN authoritative
	// partition when the caller leaves them unset (single-region/single-cluster).
	DefaultRegion  = "local"
	DefaultCluster = "local"

	// DefaultDialTimeout is the default timeout for connecting to etcd.
	DefaultDialTimeout = 5 * time.Second
)

Types

type Config

type Config struct {
	// Endpoints is the list of etcd endpoints to connect to.
	Endpoints []string
	// DialTimeout is the timeout for establishing a connection.
	DialTimeout time.Duration
	// KeyPrefix is the root prefix for all registry keys. Defaults to DefaultKeyPrefix.
	KeyPrefix string
	// Region and Cluster identify this registry's OWN authoritative partition
	// (proposal 006). Writes/deletes go under <KeyPrefix>/<Region>/clusters/<Cluster>/;
	// reads range the whole root. One registry instance owns one (region, cluster):
	// Region is shared by every registrar on the same regional etcd, Cluster is the
	// per-cluster name. Default to DefaultRegion/DefaultCluster when unset.
	Region  string
	Cluster string
}

Config holds the configuration for connecting to etcd.

type EtcdRegistry

type EtcdRegistry struct {
	// contains filtered or unexported fields
}

EtcdRegistry is a Registry implementation backed by etcd. See the package doc for the region-scoped, origin-first key layout.

func NewEtcdRegistry

func NewEtcdRegistry(log *slog.Logger, cfg Config) *EtcdRegistry

NewEtcdRegistry creates a new etcd-backed Registry. Call Initialize before using the registry to establish the etcd client connection.

func (*EtcdRegistry) Changes

func (r *EtcdRegistry) Changes() <-chan struct{}

Changes returns a channel that receives a (coalesced) signal whenever any key under the registry prefix changes. Consumers treat each receive as "something changed, re-read the registry". Satisfies registry.ChangeNotifier.

func (*EtcdRegistry) Client

func (r *EtcdRegistry) Client() *clientv3.Client

Client exposes the underlying etcd client for components that mirror this registry's authoritative partition verbatim (the cross-region replicator, proposal 006 Phase 2). Nil until Initialize succeeds.

func (*EtcdRegistry) Close

func (r *EtcdRegistry) Close() error

Close closes the etcd client connection.

func (*EtcdRegistry) Initialize

func (r *EtcdRegistry) Initialize(ctx context.Context) error

Initialize creates the etcd client connection and verifies connectivity. It must be called before any registry operations.

func (*EtcdRegistry) ListAllEndpoints

func (r *EtcdRegistry) ListAllEndpoints(ctx context.Context, protocol registryv1.Service_Protocol) (map[string][]*registryv1.ServiceEndpoint, error)

ListAllEndpoints retrieves all endpoints for the given protocol across all services from etcd. Endpoints are organized by service name in the returned map.

func (*EtcdRegistry) ListConfig

func (r *EtcdRegistry) ListConfig(ctx context.Context) ([]*registryv1.ServiceConfigProjection, error)

ListConfig returns every config projection across all origins (clusterset-wide). It ranges the whole root and unmarshals each /config/ value, setting origin_cluster authoritatively from the key path (defending against a forged origin in the value). Satisfies registry.ConfigExporter.

func (*EtcdRegistry) ListEndpoints

func (r *EtcdRegistry) ListEndpoints(ctx context.Context, service string, protocol registryv1.Service_Protocol) ([]*registryv1.ServiceEndpoint, error)

ListEndpoints retrieves all endpoints for a specific service and protocol, ACROSS every origin (region/cluster) — a consumer wants every endpoint of the service, not just this instance's own partition.

Cost: because origin precedes service in the key (proposal 006, origin-first so the replicator mirrors one contiguous prefix), a single service's endpoints are NOT a contiguous range — this ranges the whole root and filters in memory, i.e. O(all endpoints) per call. That is acceptable and NOT worth a per-service secondary index: the only caller is the agent's COLD path (an ODCDS-observed service the re-filtered watch hasn't delivered yet, agent/internal/xds/cache/ cluster.go), gated by the service catalog (nonexistent services cost nothing), hit at most once per service, and failure-tolerant (the watch catch-up repairs). In the deployed topology the agent uses the registrar backend (an in-memory per-service cache), so this etcd path runs only with --registry-backend=etcd directly. An index would add write-amplification to every register for a rarely taken read; revisit only if a hot direct-to-etcd consumer appears.

func (*EtcdRegistry) ListExports

func (r *EtcdRegistry) ListExports(ctx context.Context) ([]export.ServiceExport, error)

ListExports returns every export mark across all origins (clusters) — the clusterset-wide export view. It ranges the whole root and parses each key's origin cluster and service. Satisfies registry.ServiceExporter.

func (*EtcdRegistry) OwnPrefix

func (r *EtcdRegistry) OwnPrefix() string

OwnPrefix returns this instance's authoritative partition root (<keyPrefix>/<region>/clusters/<cluster>) — the subtree the cross-region replicator mirrors to peer regions.

func (*EtcdRegistry) RegisterEndpoint

func (r *EtcdRegistry) RegisterEndpoint(ctx context.Context, serviceName string, protocol registryv1.Service_Protocol, endpoint *registryv1.ServiceEndpoint) error

RegisterEndpoint registers an endpoint to a service and protocol in etcd, under THIS registry's own authoritative partition. The endpoint is serialized using protobuf and stored at: <ownPrefix>/services/<serviceName>/protocols/<protocol>/endpoints/<ip>

func (*EtcdRegistry) SetConfig

func (r *EtcdRegistry) SetConfig(ctx context.Context, projection *registryv1.ServiceConfigProjection) error

SetConfig records this cluster's projected GAMMA config for a service under its own authoritative partition (proposal 026). origin_cluster is stamped to this instance's cluster so the stored value matches the key path. Satisfies registry.ConfigExporter.

func (*EtcdRegistry) SetExport

func (r *EtcdRegistry) SetExport(ctx context.Context, service, namespace string) error

SetExport records that the local cluster exports the named mesh service from the given namespace (Kubernetes MCS-API ServiceExport). The mark lives under THIS instance's own authoritative partition; the namespace is the value so a remote importer can materialize the ServiceImport into the right namespace. Satisfies registry.ServiceExporter.

func (*EtcdRegistry) UnregisterEndpoint

func (r *EtcdRegistry) UnregisterEndpoint(ctx context.Context, serviceName string, ip string) error

UnregisterEndpoint removes a single endpoint from the registry for all protocols.

func (*EtcdRegistry) UnregisterEndpoints

func (r *EtcdRegistry) UnregisterEndpoints(ctx context.Context, serviceName string, ips []string) error

UnregisterEndpoints removes multiple endpoints from the registry for all protocols. It queries all protocol directories for the service and removes the specified IPs from each.

func (*EtcdRegistry) UnsetConfig

func (r *EtcdRegistry) UnsetConfig(ctx context.Context, service string) error

UnsetConfig removes the local cluster's config projection for the named service. Idempotent. Satisfies registry.ConfigExporter.

func (*EtcdRegistry) UnsetExport

func (r *EtcdRegistry) UnsetExport(ctx context.Context, service string) error

UnsetExport removes the local cluster's export mark for the named service. Idempotent. Satisfies registry.ServiceExporter.