Global Discovery Service Configuration

Experimental. The Global Discovery Service serves the pool and router lists that Global Routers and Pool Relays read over HTTP. This reference describes the global-discovery-service binary. For choosing and setting up a registration store, see Global Discovery Service Registration Storage.

Flags

--help groups the flags under four headings. A flag under the heading of another --pool-discovery value fails at startup when you set it, and so does a DynamoDB flag without --registration-storage dynamodb. A flag left at its default is never refused.

All modes

With --pool-discovery registrations

With --pool-discovery karmada or mcs

These modes join EndpointSlices that MCS imports with registrations from POST /pools. A pool is listed while MCS imports a Ready Pool Relay endpoint for it and its registration lease lasts. While a DynamoDB table cannot be read, leases lapse on the service’s clock, since no Pool Relay can renew. The registration’s cluster_id must match the MCS cluster ID or Karmada member cluster name. MCS supplies relay identities and frontend addresses; the registration supplies the model, capabilities, capacity, and location. Export each pool’s frontend Service to supply its addresses. The service needs read access to endpointslices. karmada reads slices named the Karmada way, and mcs reads slices with the standard multicluster.kubernetes.io labels.

With --registration-storage dynamodb

These flags work with every --pool-discovery value: in each mode the service keeps registrations.

The --dynamodb-* flags and --lease-skew-secs apply only with --registration-storage dynamodb; giving one with the memory store is a startup error.

Environment

HTTP endpoints

Successful responses carry JSON bodies, and a reader ignores fields it does not know. Errors carry a short plain-text reason, and GET /healthz answers with a status and an empty body.

POST /pools

Request:

{
  "key": {"cluster_id": "aws-west", "namespace": "dynamo", "dgd_name": "mocker-west-1"},
  "location": {"region": "us-west-2", "availability_zone": null, "datacenter": null},
  "model": "Qwen/Qwen3-0.6B",
  "capabilities": ["aggregated"],
  "frontends": ["http://10.43.1.2:8000/"],
  "capacity": [{"sku": "H100", "workers": 8}]
}

capabilities, frontends, and capacity default to empty lists. model must not be blank. Reply:

{"heartbeat_interval_s": 5, "lease_duration_s": 15}

Register again within heartbeat_interval_s. If lease_duration_s passes with no successful registration, the pool drops out of GET /pools. The heartbeat interval is above zero and below the lease. Any caller may overwrite any pool: the last registration for a key wins. So the Pool Relays of one pool must send the same registration, though lists may come in any order. If they differ, the pool’s listing switches between their versions at every heartbeat, and the service logs a warning that names the pool. In karmada and mcs modes, the listed frontend addresses come from MCS; the registration’s frontends are not used.

GET /pools

{
  "pools": [
    {
      "key": {"cluster_id": "aws-west", "namespace": "dynamo", "dgd_name": "mocker-west-1"},
      "location": {"region": "us-west-2", "availability_zone": null, "datacenter": null},
      "model": "Qwen/Qwen3-0.6B",
      "capabilities": ["aggregated"],
      "frontends": ["http://10.43.1.2:8000/"],
      "capacity": [{"sku": "H100", "workers": 8}],
      "relay_identities": []
    }
  ],
  "complete": true
}

GET /routers

{"routers": [{"replica": "aws-ohio/global-router-0", "url": "http://10.42.0.5:50051/"}]}

DynamoDB item layout

With --registration-storage dynamodb, the table has one item per pool. The partition key is pk (string), the sort key is sk (string), and TTL is enabled on expires_at.

A pool is live when renewed_at + lease_s * 1000 + skew >= now on the reading replica’s clock, where skew is --lease-skew-secs. A pool whose written_in is another region than the reader’s stays listed for --dynamodb-replication-grace-secs more, and complete is false while any pool is listed that way. The store never expires a pool itself. A registration is one UpdateItem without a condition. Each replica reads the table with one strongly consistent, paginated Query on pk = "pool" every --dynamodb-poll-interval-secs, and GET /pools answers from the last read, leaving out at once a pool whose lease has lapsed since.

IAM actions

Grant them on the table ARN, in each region where the service runs a replica of a Global Table.

Errors