feat(global-router): add GET /pools and a pool cache to the Global Discovery client

Cargo.toml

@@ -68,6 +68,7 @@ aisimulate-core = { version = "=0.13.0-dev.202610290000000087" }
 
 # Local crates
 dynamo-runtime = { path = "lib/runtime", version = "1.7.0" }
+dynamo-global-discovery-client = { path = "lib/global-discovery-client", version = "1.7.0" }
 dynamo-llm = { path = "lib/llm", version = "1.7.0", default-features = false }
 dynamo-sglang-generate = { path = "lib/generate-formats/sglang", version = "1.7.0" }
 dynamo-vllm-generate = { path = "lib/generate-formats/vllm", version = "1.7.0" }

components/src/dynamo/pool_relay/__main__.py

@@ -81,6 +81,7 @@ async def worker(runtime: DistributedRuntime) -> None:
         tuning=dict(args.tuning) or None,
         sources_file=args.sources_file,
         connection_revision=args.connection_revision,
+        global_discovery_url=args.global_discovery_url,
     )
     await relay.start()
     diagnostics = PoolRelayDiagnostics(relay)
@@ -89,12 +90,13 @@ async def worker(runtime: DistributedRuntime) -> None:
 
     logger.info(
         "Pool Relay started for cluster_id=%s namespaces=%s watch_all=%s "
-        "endpoint_prefixes=%s wan_bind=%s",
+        "endpoint_prefixes=%s wan_bind=%s global_discovery_url=%s",
         args.cluster_id,
         args.namespaces,
         args.watch_all,
         args.endpoint_prefixes,
         args.bind,
+        args.global_discovery_url,
     )
     endpoint_tasks: list[asyncio.Future[object]] = []
     # A terminal host failure only resolves wait_for_shutdown(); the diagnostics

components/src/dynamo/pool_relay/cli.py

@@ -53,6 +53,7 @@ class PoolRelayCliConfig:
     tuning: tuple[tuple[str, int], ...]
     sources_file: str | None = None
     connection_revision: str | None = None
+    global_discovery_url: str | None = None
 
 
 class RelayShutdownWaiter(Protocol):
@@ -163,6 +164,10 @@ def parse_args(
     parser.add_argument("--expected-unique-blocks", type=_positive_int)
 
     parser.add_argument("--bind", help="Plaintext WAN gRPC listen address")
+    parser.add_argument(
+        "--global-discovery-url",
+        help="Global Discovery Service root to read Global Router replicas from",
+    )
 
     parsed = parser.parse_args(argv)
     cluster_id = _string_value(parsed.cluster_id, environment, "DYN_CLUSTER_ID")
@@ -275,6 +280,12 @@ def parse_args(
     if bind is not None and not bind.strip():
         parser.error("--bind must not be empty")
 
+    global_discovery_url = _string_value(
+        parsed.global_discovery_url, environment, "DYN_RELAY_GLOBAL_DISCOVERY_URL"
+    )
+    if global_discovery_url is not None and not global_discovery_url.strip():
+        parser.error("--global-discovery-url must not be empty")
+
     tuning: list[tuple[str, int]] = []
     for key in TUNING_KEYS:
         environment_name = f"DYN_RELAY_{key.upper()}"
@@ -304,6 +315,7 @@ def parse_args(
         tuning=tuple(tuning),
         sources_file=sources_file,
         connection_revision=connection_revision,
+        global_discovery_url=global_discovery_url,
     )
 
 

components/src/dynamo/pool_relay/tests/test_cli.py

@@ -29,6 +29,7 @@ def test_default_config() -> None:
     assert config.namespaces == ()
     assert config.endpoint_prefixes == ()
     assert config.bind is None
+    assert config.global_discovery_url is None
     assert config.tuning == ()
 
 
@@ -56,13 +57,16 @@ def test_cli_overrides_environment() -> None:
             "[::1]:0",
             "--expected-unique-blocks",
             "128",
+            "--global-discovery-url",
+            "http://cli-discovery:8080/",
         ],
         {
             "DYN_CLUSTER_ID": "environment-dc",
             "DYN_RELAY_NAMESPACES": "environment-a, environment-b",
             "DYN_RELAY_ENDPOINT_PREFIXES": "environment-a.backend",
             "DYN_RELAY_BIND": "127.0.0.1:0",
             "DYN_RELAY_EXPECTED_UNIQUE_BLOCKS": "64",
+            "DYN_RELAY_GLOBAL_DISCOVERY_URL": "http://environment-discovery:8080/",
         },
     )
 
@@ -72,6 +76,7 @@ def test_cli_overrides_environment() -> None:
     assert config.endpoint_prefixes == ("cli-a.backend", "cli-b.backend")
     assert config.bind == "[::1]:0"
     assert config.expected_unique_blocks == 128
+    assert config.global_discovery_url == "http://cli-discovery:8080/"
 
 
 def test_config_from_environment() -> None:
@@ -83,6 +88,7 @@ def test_config_from_environment() -> None:
             "DYN_RELAY_ENDPOINT_PREFIXES": "prod-a.backend, prod-b.backend",
             "DYN_RELAY_BIND": "127.0.0.1:0",
             "DYN_RELAY_EXPECTED_UNIQUE_BLOCKS": "64",
+            "DYN_RELAY_GLOBAL_DISCOVERY_URL": "http://discovery:8080/",
         },
     )
 
@@ -92,6 +98,7 @@ def test_config_from_environment() -> None:
     assert config.watch_all is False
     assert config.bind == "127.0.0.1:0"
     assert config.expected_unique_blocks == 64
+    assert config.global_discovery_url == "http://discovery:8080/"
 
 
 @pytest.mark.parametrize(
@@ -364,6 +371,24 @@ def test_expected_unique_blocks_rejects_invalid_numbers(
     )
 
 
+@pytest.mark.parametrize("source", ["cli", "environment"])
+def test_global_discovery_url_rejects_empty(
+    source: str, capsys: pytest.CaptureFixture[str]
+) -> None:
+    if source == "cli":
+        argv = ["--global-discovery-url", " "]
+        environment = {}
+    else:
+        argv = []
+        environment = {"DYN_RELAY_GLOBAL_DISCOVERY_URL": " "}
+    assert_cli_error(
+        ["--cluster-id", "dc-a", *argv],
+        environment,
+        capsys,
+        "--global-discovery-url must not be empty",
+    )
+
+
 def test_sources_file_is_explicitly_empty_until_runtime_loads_sources() -> None:
     config = parse_args(
         ["--cluster-id", "dc", "--sources-file", "/etc/relay/sources.json"],

docs/fern/pages/reference/components/pool-relay-configuration.md

@@ -23,6 +23,7 @@ see [Pool Relay Concepts](../../developer-guide/knowledge-base/modular-component
 | `--endpoint-prefix` | `DYN_RELAY_ENDPOINT_PREFIXES` | No prefix filter | Repeat the CLI option, or use a comma-separated environment value. Match namespace/component/endpoint segments. |
 | `--expected-unique-blocks` | `DYN_RELAY_EXPECTED_UNIQUE_BLOCKS` | `1048576` | Positive expected number of unique blocks per pool; sizes the CKF, not a global Relay memory limit. |
 | `--bind` | `DYN_RELAY_BIND` | No listener | Plaintext gRPC socket address, such as `127.0.0.1:5561` or `[::1]:5561`. Requires a numeric IP and port. |
+| `--global-discovery-url` | `DYN_RELAY_GLOBAL_DISCOVERY_URL` | Unset | Root of the Global Discovery Service, such as `http://global-discovery:8080/`. The Relay reads the Global Router replica list from it every 5 seconds. When a read fails, it keeps the last list and reports why in the health field `global_routers_stale_reason`. When unset, the Relay reads no list. |
 | `--help` | None | — | Print CLI usage and exit. |
 
 The protocol and gRPC server are included in the standard build. Omitting `--bind` disables only
@@ -163,7 +164,7 @@ of SHA-256 over the UTF-8 cluster ID. These are not HTTP paths or WAN RPCs.
 
 | Endpoint | Availability | Request and response |
 | --- | --- | --- |
-| `health` | Always | Empty request; reports `healthy`, shutdown state, endpoint counts, and WAN state/errors. |
+| `health` | Always | Empty request; reports `healthy`, shutdown state, endpoint counts, WAN state/errors, `global_discovery_enabled`, and `global_routers_stale_reason`. |
 | `stats` | `ckf-diagnostics` build feature | Empty request; returns detailed endpoint/pool statistics. |
 | `snapshot` | `ckf-diagnostics` build feature | Requires `serving_endpoint`; returns that endpoint's diagnostic snapshot. |
 

lib/bindings/python/rust/llm/pool_relay.rs

@@ -39,6 +39,7 @@ impl PoolRelay {
         tuning=None,
         sources_file=None,
         connection_revision=None,
+        global_discovery_url=None,
     ))]
     #[allow(clippy::too_many_arguments)]
     fn new(
@@ -57,6 +58,7 @@ impl PoolRelay {
         tuning: Option<std::collections::HashMap<String, u64>>,
         sources_file: Option<String>,
         connection_revision: Option<String>,
+        global_discovery_url: Option<String>,
     ) -> PyResult<Self> {
         if namespace_filter.is_some() && namespaces.is_some() {
             return Err(PyValueError::new_err(
@@ -231,6 +233,12 @@ impl PoolRelay {
                 },
                 producer,
                 transport,
+                global_discovery_url: global_discovery_url
+                    .map(|url| url.parse())
+                    .transpose()
+                    .map_err(|error| {
+                        PyValueError::new_err(format!("invalid global_discovery_url: {error}"))
+                    })?,
             },
             inner: Arc::new(OnceCell::new()),
         })

lib/bindings/python/src/dynamo/_core.pyi

@@ -2828,6 +2828,7 @@ class PoolRelay:
         tuning: Optional[Dict[str, int]] = None,
         sources_file: Optional[str] = None,
         connection_revision: Optional[str] = None,
+        global_discovery_url: Optional[str] = None,
     ) -> None:
         ...
 

lib/global-common/src/pool.rs

@@ -76,6 +76,18 @@ pub enum PoolKeyError {
     InvalidField { field: &'static str },
 }
 
+/// The pool's name for people, `<cluster_id>/<namespace>/<dgd_name>`, as logs
+/// and metrics show it. A pool's identity is its [`PoolId`].
+impl fmt::Display for PoolKey {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{}/{}/{}",
+            self.cluster_id, self.namespace, self.dgd_name
+        )
+    }
+}
+
 impl PoolKey {
     pub fn new(
         cluster_id: impl Into<String>,
@@ -212,6 +224,14 @@ mod tests {
         assert_eq!(serde_json::to_string(&id).unwrap(), format!("\"{id}\""));
     }
 
+    #[test]
+    fn a_key_displays_as_its_name_for_people() {
+        assert_eq!(
+            key("ohio", "dynamo", "mocker-1").to_string(),
+            "ohio/dynamo/mocker-1"
+        );
+    }
+
     #[test]
     fn key_json_is_checked_when_read() {
         let pool = key("ohio", "dynamo", "mocker-1");

lib/global-common/src/replicas.rs

@@ -14,7 +14,7 @@ use crate::watch::WatchEvent;
 pub struct RouterReplicaId(pub String);
 
 /// A Global Router replica and the address workload clusters reach it at.
-#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct RouterReplica {
     pub replica: RouterReplicaId,
     pub url: Url,

lib/global-discovery-client/Cargo.toml

@@ -17,8 +17,11 @@ reqwest = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
+tokio = { workspace = true }
+tokio-util = { workspace = true }
+tracing = { workspace = true }
 url = { workspace = true }
 
 [dev-dependencies]
 axum = { workspace = true }
-tokio = { workspace = true }
+tokio = { workspace = true, features = ["test-util"] }