feat(global-router): add the Global Discovery Service library (contract and backends)

lib/global-common/src/discovery.rs

@@ -134,10 +134,12 @@ pub struct PoolListing {
     pub frontends: Vec<Url>,
     #[serde(default)]
     pub capacity: Vec<Capacity>,
-    /// The only PoolRelay allowed to stream this pool's state, by each
-    /// identity it can connect with. On a trusted network these are its pod's
-    /// addresses, as [`address_identity`] writes them: two on a dual-stack
-    /// cluster. Empty when the service does not know the PoolRelay.
+    /// The PoolRelays allowed to stream this pool's state, by each identity
+    /// they can connect with. A pool runs active-active PoolRelay replicas,
+    /// each reporting to every router, and routers dedupe the overlapping
+    /// reports. On a trusted network these are the addresses of every Ready
+    /// replica's pod, as [`address_identity`] writes them: two per pod on a
+    /// dual-stack cluster. Empty when the service does not know the PoolRelays.
     #[serde(default)]
     pub relay_identities: Vec<String>,
 }

lib/global-discovery-service/Cargo.toml

@@ -9,3 +9,21 @@ edition.workspace = true
 authors.workspace = true
 license.workspace = true
 repository.workspace = true
+
+[dependencies]
+dynamo-global-common = { workspace = true }
+
+anyhow = { workspace = true }
+async-stream = { workspace = true }
+async-trait = { workspace = true }
+futures = { workspace = true }
+k8s-openapi = { workspace = true }
+kube = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true }
+tokio-util = { workspace = true }
+tracing = { workspace = true }
+url = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["test-util"] }

lib/global-discovery-service/src/backends.rs

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Implementations of [`crate::pool_discovery`], one module per
+//! backend.
+
+pub mod kubernetes;
+pub mod memory;
+mod stream;

lib/global-discovery-service/src/backends/kubernetes.rs

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! The MCS backend, using SIG Multicluster: pools ([`McsPoolDirectory`]) and
+//! Global Router replicas ([`McsReplicaDirectory`]) from the EndpointSlices
+//! that MCS imports, named as [`McsImplementation`] describes.
+//!
+//! It assumes a trusted network where pod addresses are reachable between
+//! clusters (for example Azure CNI with peered VNets, or the AWS VPC CNI with
+//! peered VPCs), and an MCS implementation, Karmada first.
+//!
+//! Each pool's PoolRelay Service, named `<DGD name>-pool-relay` by default,
+//! needs a `ServiceExport`, and so does the router's Service in the hub, so
+//! its replicas appear in every importing cluster. A pool is live while a
+//! PoolRelay endpoint is Ready. Its `relay_identities` are the addresses of
+//! every Ready PoolRelay pod, for routers on a trusted network to admit each
+//! of the pool's active-active replicas.
+//!
+//! With Karmada, a Service name may have at most 55 characters: DGD names up
+//! to 44 with the default `-pool-relay` suffix. Karmada imports a Service as
+//! `derived-<name>`, and that name may have at most 63 characters, so
+//! Karmada imports nothing for a longer name, and the backend never sees that
+//! Service's endpoints. [`McsReplicaDirectory::new`] logs an error for a
+//! Service whose name is too long.
+//!
+//! Create the PoolRelay Service and its `ServiceExport` in the workload
+//! cluster, not through Karmada propagation. Kubernetes copies a Service's
+//! labels onto its EndpointSlices, so a Karmada-propagated Service gives its
+//! slices Karmada's labels. In a test with Karmada v1.19, deleting such a
+//! `ServiceExport` made karmada-agent delete the Service's EndpointSlice
+//! too. Exporting the Service again then found no slice until the Service
+//! changed.
+
+mod cache;
+mod endpoints;
+mod hub;
+mod mcs;
+
+pub use endpoints::{ExportedService, McsReplicaDirectory};
+pub use hub::McsPoolDirectory;
+pub use mcs::McsImplementation;