feat(global-router): add the Multi-Cluster Services registry API contract

.github/codeowners/areas.yaml

@@ -19,6 +19,7 @@ areas:
   - lib/llm/src/grpc/protos/
   - lib/llm/src/grpc/service.rs
   - lib/llm/src/grpc/service/
+  - lib/http-server/
   - lib/llm/src/http.rs
   - lib/llm/src/http/
   - lib/llm/src/http/service.rs
@@ -73,6 +74,7 @@ areas:
   path_globs:
   - lib/global-view-broadcaster/
   - components/src/dynamo/pool_relay/
+  - container/global-discovery-service.yaml
   - lib/global-view-receiver/
   - docs/fern/pages/developer-guide/knowledge-base/modular-components/router/multi-dc-kv-routing.md
   - lib/global-*/**
@@ -1085,6 +1087,10 @@ shared:
   owners:
   - frontend
   - observability
+- glob: lib/http-server/src/metrics.rs
+  owners:
+  - frontend
+  - observability
 - glob: lib/llm/src/kv_router/shared_cache.rs
   owners:
   - router
@@ -1284,6 +1290,10 @@ shared:
   owners:
   - operator
   - backend-vllm
+- glob: container/Dockerfile.global-discovery-service
+  owners:
+  - global-router
+  - ops
 - glob: deploy/operator/Dockerfile
   owners:
   - operator

CODEOWNERS

@@ -67,6 +67,7 @@
 *                                                                                                       @ai-dynamo/dynamo-runtime-codeowners
 
 # === frontend  (@ai-dynamo/dynamo-frontend-codeowners) ===
+/lib/http-server/                                                                                       @ai-dynamo/dynamo-frontend-codeowners
 /examples/chat_templates/                                                                               @ai-dynamo/dynamo-frontend-codeowners
 /components/src/dynamo/frontend/                                                                        @ai-dynamo/dynamo-frontend-codeowners
 /components/src/dynamo/frontend/tests/                                                                  @ai-dynamo/dynamo-frontend-codeowners
@@ -94,6 +95,7 @@
 /lib/global-view-receiver/                                                                              @ai-dynamo/dynamo-global-router-codeowners
 /lib/global-view-broadcaster/                                                                           @ai-dynamo/dynamo-global-router-codeowners
 /components/src/dynamo/pool_relay/                                                                      @ai-dynamo/dynamo-global-router-codeowners
+/container/global-discovery-service.yaml                                                                @ai-dynamo/dynamo-global-router-codeowners
 
 # === backend-vllm  (@ai-dynamo/dynamo-backend-vllm-codeowners) ===
 /lib/sidecar/vllm/                                                                                      @ai-dynamo/dynamo-backend-vllm-codeowners
@@ -663,6 +665,7 @@ requirements.txt
 /examples/diffusers/Dockerfile                                                                          @ai-dynamo/dynamo-diffusion-codeowners @ai-dynamo/dynamo-ops-codeowners
 /lib/kvbm-logical/src/metrics/                                                                          @ai-dynamo/dynamo-kv-memory-codeowners @ai-dynamo/dynamo-observability-codeowners
 /tests/serve/test_vllm_omni.py                                                                          @ai-dynamo/dynamo-runtime-codeowners @ai-dynamo/dynamo-backend-vllm-codeowners
+/lib/http-server/src/metrics.rs                                                                         @ai-dynamo/dynamo-frontend-codeowners @ai-dynamo/dynamo-observability-codeowners
 /tests/test_kustomize_matrix.py                                                                         @ai-dynamo/dynamo-runtime-codeowners @ai-dynamo/dynamo-ops-codeowners
 /.github/workflows/fern-docs.yml                                                                        @ai-dynamo/dynamo-ops-codeowners @ai-dynamo/dynamo-docs-codeowners
 /examples/deployments/**/vllm/**                                                                        @ai-dynamo/dynamo-operator-codeowners @ai-dynamo/dynamo-backend-vllm-codeowners
@@ -758,6 +761,7 @@ requirements.txt
 /components/src/dynamo/vllm/multimodal_utils/                                                           @ai-dynamo/dynamo-backend-vllm-codeowners @ai-dynamo/dynamo-multimodal-codeowners
 /deploy/inference-gateway/ext-proc/Dockerfile                                                           @ai-dynamo/dynamo-epp-codeowners @ai-dynamo/dynamo-router-codeowners @ai-dynamo/dynamo-ops-codeowners
 /components/src/dynamo/trtllm/encode_helper.py                                                          @ai-dynamo/dynamo-backend-trtllm-codeowners @ai-dynamo/dynamo-multimodal-codeowners
+/container/Dockerfile.global-discovery-service                                                          @ai-dynamo/dynamo-global-router-codeowners @ai-dynamo/dynamo-ops-codeowners
 /container/templates/sglang_runtime.Dockerfile                                                          @ai-dynamo/dynamo-ops-codeowners @ai-dynamo/dynamo-backend-sglang-codeowners
 /container/templates/trtllm_runtime.Dockerfile                                                          @ai-dynamo/dynamo-ops-codeowners @ai-dynamo/dynamo-backend-trtllm-codeowners
 /tests/router/test_router_e2e_with_vllm_xpu.py                                                          @ai-dynamo/dynamo-router-codeowners @ai-dynamo/dynamo-xpu-codeowners @ai-dynamo/dynamo-backend-vllm-codeowners

Cargo.toml

@@ -12,6 +12,7 @@ members = [
     "lib/kv-hashing",
     "lib/mocker",
     "lib/kv-router",
+    "lib/http-server",
     "lib/global-common",
     "lib/global-discovery-client",
     "lib/global-discovery-service",
@@ -73,6 +74,7 @@ dynamo-truthy = { path = "lib/truthy", version = "1.7.0" }
 dynamo-data-gen = { path = "lib/data-gen", version = "1.7.0" }
 dynamo-kv-hashing = { path = "lib/kv-hashing", version = "1.7.0" }
 dynamo-global-common = { path = "lib/global-common", version = "1.7.0" }
+dynamo-http-server = { path = "lib/http-server", version = "1.7.0" }
 dynamo-memory = { path = "lib/memory", version = "1.7.0" }
 dynamo-mocker = { path = "lib/mocker", version = "1.7.0" }
 dynamo-kv-router = { path = "lib/kv-router", version = "1.7.0" }

container/Dockerfile.global-discovery-service

@@ -0,0 +1,26 @@
+# syntax=docker/dockerfile:1.10.0
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# CPU-only image for the Global Discovery Service, which serves pool discovery
+# for the Global Router over HTTP; see global-discovery-service.yaml. Build it
+# from the repository root:
+#   docker build -f container/Dockerfile.global-discovery-service -t global-discovery-service .
+FROM rust:1.96.1-trixie AS builder
+RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    build-essential cmake pkg-config protobuf-compiler libclang-dev libssl-dev curl \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /workspace
+COPY . .
+RUN --mount=type=cache,target=/usr/local/cargo/registry,sharing=locked \
+    --mount=type=cache,target=/usr/local/cargo/git,sharing=locked \
+    cargo build --locked --release -p dynamo-global-discovery-service --bin global-discovery-service
+
+FROM debian:trixie-slim AS global-discovery-service
+RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    ca-certificates libstdc++6 \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /workspace/target/release/global-discovery-service /usr/local/bin/global-discovery-service
+USER 10001:0
+EXPOSE 8080
+ENTRYPOINT ["/usr/local/bin/global-discovery-service"]

container/global-discovery-service.yaml

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Global Discovery Service with pools from Karmada, applied directly to the hub
+# cluster (not through Karmada). Replace IMAGE with the pushed image, for example:
+#   sed "s#IMAGE#<registry>/global-discovery-service:<tag>#" global-discovery-service.yaml | kubectl apply -f -
+# It needs only read access to EndpointSlices. It lists the pools whose
+# `<DGD name>-pool-relay` Services Karmada imports, and the replicas of the
+# Global Router Service named by the --router-* arguments: set those to the
+# router's namespace, its Service and the port PoolRelays connect to.
+#
+# It reads the imported slices with the pod's credentials, so this cluster
+# needs a ServiceImport for each pool's PoolRelay Service and for the router
+# Service. To read the Karmada control plane instead, which holds every
+# exported Service's slices, mount its kubeconfig from a Secret, point
+# KUBECONFIG at it, and grant the same read access there.
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: global-discovery
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: global-discovery-service
+  namespace: global-discovery
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: global-discovery-service
+rules:
+  - apiGroups: ["discovery.k8s.io"]
+    resources: ["endpointslices"]
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: global-discovery-service
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: global-discovery-service
+subjects:
+  - kind: ServiceAccount
+    name: global-discovery-service
+    namespace: global-discovery
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: global-discovery-service
+  namespace: global-discovery
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: global-discovery-service
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: global-discovery-service
+    spec:
+      serviceAccountName: global-discovery-service
+      securityContext:
+        runAsNonRoot: true
+      containers:
+        - name: global-discovery
+          image: IMAGE
+          args:
+            - --listen=0.0.0.0:8080
+            - --pool-discovery=karmada
+            - --router-namespace=global-discovery
+            - --router-service=global-router
+            - --router-port-name=http
+          env:
+            - name: DYN_LOG
+              value: info
+          ports:
+            - name: http
+              containerPort: 8080
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            periodSeconds: 5
+          lifecycle:
+            # Keep serving while the Pod leaves the Service's endpoints.
+            preStop:
+              exec:
+                command: ["sleep", "5"]
+          resources:
+            requests:
+              cpu: 50m
+              memory: 64Mi
+            limits:
+              memory: 256Mi
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: global-discovery-service
+  namespace: global-discovery
+spec:
+  selector:
+    app.kubernetes.io/name: global-discovery-service
+  ports:
+    - name: http
+      port: 8080
+      targetPort: http

deploy/global-discovery-mcs/api/derived.go

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package api
+
+import (
+	"crypto/sha256"
+	"encoding/base32"
+	"strings"
+)
+
+// DerivedServicePrefix starts every derived Service name.
+const DerivedServicePrefix = "derived-"
+
+var base32HexNoPad = base32.HexEncoding.WithPadding(base32.NoPadding)
+
+// DerivedServiceName returns the name of the derived Service that an
+// importing cluster creates for the ServiceImport namespace/name:
+// "derived-" followed by the first ten characters of the lowercase,
+// unpadded base32hex encoding of the SHA-256 of "namespace/name".
+//
+// The algorithm is the derivedName function of sigs.k8s.io/mcs-api
+// controllers, so the name is the same in every cluster and in every MCS
+// implementation that follows mcs-api. Clients compute it locally to dial an
+// import, for example derived-<hash>.<namespace>.svc.cluster.local.
+func DerivedServiceName(namespace, name string) string {
+	sum := sha256.Sum256([]byte(namespace + "/" + name))
+	return DerivedServicePrefix + strings.ToLower(base32HexNoPad.EncodeToString(sum[:]))[:10]
+}

deploy/global-discovery-mcs/api/derived_test.go

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package api
+
+import (
+	"regexp"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// Golden values computed independently with Python
+// (base64.b32hexencode(hashlib.sha256(b"ns/name").digest())) and with the
+// derivedName function of sigs.k8s.io/mcs-api v0.5.x controllers/common.go.
+var derivedGolden = []struct {
+	namespace, name, want string
+}{
+	{"default", "nginx", "derived-iuq6ea9f4j"},
+	{"llm", "llm-request-router-backend", "derived-b756q8b74k"},
+	{"llm-stack", "backend-router", "derived-t1d4et30ia"},
+	{"dynamo", "pool-frontend", "derived-apb6bcevn9"},
+	{"a", "b", "derived-o56drg1jup"},
+	{"kube-system", "kube-dns", "derived-bnmpvejc1s"},
+	{"", "", "derived-h9fdlck2cc"},
+}
+
+func TestDerivedServiceNameGolden(t *testing.T) {
+	for _, tt := range derivedGolden {
+		assert.Equal(t, tt.want, DerivedServiceName(tt.namespace, tt.name), "%s/%s", tt.namespace, tt.name)
+	}
+}
+
+func TestDerivedServiceNameIsDNSLabel(t *testing.T) {
+	label := regexp.MustCompile(`^derived-[0-9a-v]{10}$`)
+	for _, tt := range derivedGolden {
+		got := DerivedServiceName(tt.namespace, tt.name)
+		assert.Regexp(t, label, got)
+		assert.Len(t, got, len(DerivedServicePrefix)+10)
+	}
+}
+
+// The separator is part of the hashed input, so moving characters between the
+// namespace and the name changes the result.
+func TestDerivedServiceNameSeparator(t *testing.T) {
+	assert.NotEqual(t, DerivedServiceName("ab", "c"), DerivedServiceName("a", "bc"))
+	assert.Equal(t, DerivedServiceName("ns", "svc"), DerivedServiceName("ns", "svc"))
+}