Subgraph Overrides — One Router Config Across All

Register cluster-internal, localhost, and custom subgraph addresses once. The router uses the right address for each environment without separate config files.

No redeployment. No URL templating. One router config for every environment.

The problem

Canonical URLs are not always the right hop

Inside the cluster, through ingress, or on a laptop, routing should match the network, not duplicate configs.

Public URLs aren't the right routing target inside a cluster

A subgraph registered as https://products.example.com/graphql should not be called that way from inside the same Kubernetes cluster. Routing through the public ingress costs latency, egress fees, and sometimes fails when traffic leaves the cluster only to come back in (NAT hairpinning).

Separate router configs per environment fall out of sync

When dev, staging, and prod each carry their own YAML, it is easy to change one file and miss the others. Small mismatches add up until comparing configs is mostly churn—and real mistakes get harder to spot.

URL templating inside the config is a workaround, not a fix

${SUBGRAPH_URL_PRODUCTS} chained across a dozen services turns a federation config into a string-substitution exercise. The router can't tell you what URL it's actually using without you resolving the template by hand.

Our solution

One config file, different subgraph addresses per environment

Subgraph overrides live in router YAML: per subgraph, you swap the execution-config URL for the hop that actually works on that machine or cluster. The list below is the field reference; anything you omit keeps its value from the execution config.

Overrides cover

• routing_url replaces the query/mutation URL from the execution config
• subscription_url replaces the subscription URL independently
• subscription_protocol: ws, sse, or sse_post
• subscription_websocket_subprotocol: (graphql-ws, graphql-transport-ws, or auto)

Why it works

1. You publish one execution config; each router applies only the overrides it defines—cluster-internal DNS in Kubernetes, localhost on a laptop, and so on—without forking the whole file per environment.

2. Canonical URLs stay on the control plane for publishing and validation; overrides change only how that router instance reaches subgraphs at runtime.

Overrides

Before & After

Operations

Reload without drift

Overrides live in router config; when they change, the next reload applies new routing with the same graceful handoff as Config Hot Reload.

How subgraph overrides work

01

Canonical URLs preserved upstream.

Router loads the execution config

Execution config comes from the control plane with all registered subgraph URLs.

02

Apply local overrides

If an override exists for a subgraph, the router replaces the execution-config URL with the override value.

03

Route requests to the override target

Queries, mutations, and subscriptions go to the override URL.

04

Reload picks up changes

When the override config changes, the router applies the new routing on its next reload without dropping traffic.

Route subgraphs for the network you are in

One config file: local overrides for dev, staging, and production.

FAQ

Override subgraph config

• Does the override change what the control plane sees?
• Can I override just the subscription URL without touching the routing URL?
• What subscription protocols are supported?
• Do I need to redeploy when I change an override?
• What happens if a subgraph isn't in the overrides block?
• Does legacy override syntax still work?
• How does this compare to Custom Modules for routing logic?

More detail in the override subgraph config documentation.