Skip to main content

Operating the router — the new tier-0 service

The day you adopt federation, your router becomes the single most critical service you run: 100% of API traffic, every page, every client. Operate it like it.

Deployment​

  • The router ships like code, not like config. Router version bumps, config changes and supergraph schema updates each get their own rollout with canary + automatic rollback. A bad supergraph publish is a full outage; treat schema rollout with the same ceremony as a binary rollout.
  • Pin and stage supergraph versions. The router should pull a specific supergraph artifact (not "latest") per environment, promoted dev → staging → prod like any build artifact.
  • Run at least N+2 regionally. The router is stateless — there is no excuse for it being less available than the subgraphs behind it.

Timeouts, retries and traffic protection​

  • Per-subgraph timeout budgets, not one global number. search at p99 800ms and identity at p99 30ms should not share a timeout.
  • Retries only on idempotent fetches (queries, entity resolution) and with a retry budget — a slow subgraph plus naive retries is how you turn a brownout into a blackout.
  • Circuit-break per subgraph so one failing domain degrades its fields to null (nullable boundaries — this is why) instead of consuming the connection pool for everyone.
  • Depth/complexity limits and per-client complexity rate limits live here (security baseline).

Observability — the router is your source of truth​

Field-level and plan-level telemetry from the router beats anything the subgraphs can tell you individually:

  • Federated traces (waterfall per query plan) for the top operations — this is where gateway N+1s become visible.
  • Per-subgraph SLIs as seen from the router: latency, error rate, timeout rate. Subgraph teams' own dashboards measure their service; the router measures the customer experience of their service. When they disagree, the router is right.
  • Field usage stats feeding deprecation decisions (versioning).
  • Alert on the errors array and field error rates — a federated graph returns HTTP 200 while a whole domain is down.

Schema-update runbook (have one before you need it)​

  1. Composition check passed and published — registry shows new supergraph version.
  2. Canary router instances pick it up; automated diff of error/latency metrics vs baseline for M minutes.
  3. Fleet-wide rollout; previous supergraph version kept hot for instant rollback.
  4. Rollback = repoint to previous artifact — seconds, not a redeploy. If your schema rollback requires redeploying subgraphs, you don't have rollback.