checkId: check.servicegraph.gateway-router plugin: stellaops.doctor.servicegraph severity: fail tags: [servicegraph, gateway, router, connectivity]

Gateway / Router Liveness

This Doctor check confirms that the router/gateway fronting every platform RPC is reachable AND serving — including the documented metadata-replay outage where the gateway answers but cannot route.

What It Checks

Resolves the router host from the canonical platform key Router:Gateways:0:Host (compose Router__Gateways__0__Host, e.g. router.stella-ops.local:9100), composes a base URL (a value that already carries a scheme is used verbatim; a bare host defaults to https://), and GETs the gateway readiness endpoint (/healthz, falling back to /readyz).

It specifically detects the metadata-replay / HELLO outage: when the gateway returns HTTP 503 with a body containing no instances available, the gateway is up but its in-memory route table is empty (“HELLO landed but metadata replay didn’t”). A bare “did it answer” probe misses this because the gateway does answer — with a 503.

ConditionResult
No router/gateway host configuredskip
/healthz or /readyz returns 2xxpass
503 with no instances available bodyfail (metadata-replay-specific cause)
Any other non-2xx, or connection failurefail

Why It Matters

Every inter-service call flows through the router/gateway. A gateway that is up but has lost its route table silently fails all routed traffic with a 503; without this check that outage is invisible to Doctor. The metadata-replay flake is known to occur after a gateway restart when downstream services have not yet re-announced their routes.

Common Causes

How to Fix

Docker Compose

# A single restart re-triggers HELLO + metadata replay and clears the 503 'no instances available'.
docker compose -f devops/compose/docker-compose.stella-ops.yml restart router-gateway

# Confirm the gateway is ready and instances re-registered:
docker compose -f devops/compose/docker-compose.stella-ops.yml ps router-gateway
curl -fsS http://router.stella-ops.local:9100/healthz

Bare Metal / systemd

# Restart the router/gateway service, then probe readiness.
systemctl restart stellaops-router-gateway
curl -fsS http://<gateway-host>:9100/readyz

Kubernetes / Helm

# Rollout-restart the gateway deployment so it re-announces; verify the readiness probe recovers.
kubectl rollout restart deployment/router-gateway -n stellaops
kubectl get pods -n stellaops -l app=router-gateway

Verification

stella doctor run --check check.servicegraph.gateway-router