Apollo Router

Apollo Router Config Generator

Apollo Router is a high-performance graph router written in Rust for running Apollo Federation 2 supergraphs. It sits in front of your subgraphs and handles query planning, execution, and response composition.

This skill generates version-correct configuration. Router v1 and v2 have incompatible config schemas in several critical sections (CORS, JWT auth, connectors). Always determine the target version before generating any config.

Step 1: Version Selection

Ask the user before generating any config:

Which Apollo Router version are you targeting?

  [1] Router v2.x (recommended — current LTS, required for Connectors)
  [2] Router v1.x (legacy — end-of-support announced, security patches only)
  [3] Not sure — help me decide

If the user picks [3], display:

Quick guide:

  • Pick v2 if: you're starting fresh, using Apollo Connectors for REST APIs,
    or want backpressure-based overload protection.
  • Pick v1 if: you have an existing deployment and haven't migrated yet.
    Note: Apollo ended active support for v1.x. The v2.10 LTS (Dec 2025)
    is the current baseline. Migration is strongly recommended.

  Tip: If you have an existing router.yaml, you can auto-migrate it:
    router config upgrade router.yaml

Store the selection as ROUTER_VERSION=v1|v2 to gate all subsequent template generation.

Step 2: Environment Selection

Ask: Production or Development?

• Production: security-hardened defaults (introspection off, sandbox off, homepage off, subgraph errors hidden, auth required, health check on)
• Development: open defaults (introspection on, sandbox on, errors exposed, text logging)

Load the appropriate base template from:

• templates/{version}/production.yaml
• templates/{version}/development.yaml

Step 3: Feature Selection

Ask which features to include:

• JWT Authentication
• Declarative Authorization (field-level @authenticated / @requiresScopes / @policy directives — requires GraphOS + request claims)
• CORS (almost always yes for browser clients)
• Operation Limits
• Traffic Shaping / Rate Limiting
• Telemetry (Prometheus, OTLP tracing, JSON logging)
• APQ (Automatic Persisted Queries — performance/bandwidth only, NOT a security control)
• Persisted Query Safelisting (GraphOS PQL operation allowlist — a security control; distinct from APQ)
• Connectors (REST API integration — Router v2 only; GA key is connectors, early v2 preview key was preview_connectors)
• Subscriptions
• Header Propagation
• Response Caching (entity + root field caching with Redis — Router v2 only, v2.6.0+)

Step 4: Gather Parameters

For each selected feature, collect required values.

• Use section templates from templates/{version}/sections/ for auth, cors, headers, limits, telemetry, and traffic-shaping.
• For Connectors in v2, use templates/v2/sections/connectors.yaml as the source.
• For APQ and subscriptions, copy the snippet from the selected base template (templates/{version}/production.yaml or templates/{version}/development.yaml) or from references.
• Only offer Connectors when ROUTER_VERSION=v2.

CORS

• List of allowed origins (never use "*" for production)

JWT Authentication

• JWKS URL
• Issuer(s) — note: v1 uses singular issuer, v2 uses plural issuers array

Declarative Authorization (field-level)

Field- and type-level access control enforced in the router, via the @authenticated, @requiresScopes, and @policy directives applied in subgraph schemas. This is the layer that the global authorization.require_authentication gate cannot express. It is a GraphOS feature (Enterprise; Developer/Standard plans require Router v2.6.0+) and requires a router connected to GraphOS. Directives are enabled by default — config only turns them off.

Confirm prerequisites before recommending these:

• Router connected to GraphOS (Router v1.29.1+; Developer/Standard plans need v2.6.0+).
• A claims source. Directives evaluate the claims at the apollo::authentication::jwt_claims context key. Populate it via JWT authentication (configure that feature too) or a coprocessor that injects claims.
• @policy additionally requires a Supergraph plugin (Rhai script or coprocessor) to evaluate each policy — the router extracts required policies into apollo::authorization::required_policies but does not decide them itself.

Ask:

• Which fields/types need protection, and at what level? (@authenticated = any valid identity; @requiresScopes = specific scopes; @policy = custom logic.)
• Where do scopes/claims come from? (JWT claims vs. coprocessor-injected.)

The directives live in the subgraph schemas, not in router.yaml. The router config only enables/disables the feature and (for @policy) wires the evaluating plugin. See references/configuration.md → Authorization.

Persisted Query Safelisting (GraphOS PQL)

Not the same as APQ. APQ (apq) is a runtime bandwidth optimization that caches any operation a client sends — it provides no security. Safelisting uses a GraphOS-managed Persisted Query List (PQL) that clients register at build time; the router then rejects operations not on the list. This is the "persisted query safelisting" security control. It is a GraphOS feature requiring a router connected to GraphOS (APOLLO_KEY + APOLLO_GRAPH_REF).

Pick a security level (increasing restrictiveness):

Then gather:

• Is the router GraphOS-connected? Safelisting needs the PQL fetched from GraphOS (or local_manifests for offline licenses).
• Have clients published their operations to the PQL (via rover persisted-queries publish in their CI/CD)? If not, start in audit mode.
• When enabling safelist, APQ must be disabled (apq.enabled: false) — they are mutually exclusive.

Config key history: GA persisted_queries since v1.32.0 (was preview_persisted_queries in v1.25.0–v1.32.0); GA in all v2. See references/configuration.md → Persisted Query Safelisting.

Connectors (v2 only)

• Subgraph name and source name (used as connectors.sources.<subgraph>.<source>)
• Optional $config values for connector runtime configuration
• If migrating old v2 preview config, rename preview_connectors to connectors

Operation Limits

Present the tuning guidance:

Operation depth limit controls how deeply nested a query can be.

  Router default: 100 (permissive — allows very deep queries)
  Recommended starting point: 50

  Lower values (15–25) are more secure but will reject legitimate queries
  in schemas with deep entity relationships or nested fragments.
  Higher values (75–100) are safer for compatibility but offer less
  protection against depth-based abuse.

  Tip: Run your router in warn_only mode first to see what depths your
  real traffic actually uses, then tighten:
    limits:
      warn_only: true

What max_depth would you like? [default: 50]

The same principle applies to max_height, max_aliases, and max_root_fields.

Telemetry

• OTEL collector endpoint (default: http://otel-collector:4317)
• Prometheus listen port (default: 9090)
• Trace sampling rate (default: 0.1 = 10%)

Traffic Shaping

• Client-facing rate limit capacity (default: 1000 req/s)
• Router timeout (default: 60s)
• Subgraph timeout (default: 30s)

Response Caching (v2 only, v2.6.0+)

Security: data leakage risk. Before generating any response cache config, you MUST ask the user which types and fields return user-specific data. Cached data defaults to shared — subgraph responses without Cache-Control: private are visible to all users. User-specific subgraphs must return Cache-Control: private and have private_id configured on the router.

• Ask: Which subgraphs serve user-specific data? (e.g., accounts, profiles, carts)
• Ask: How do you identify users? (JWT sub claim, session token, API key)
• Redis URL (default: redis://localhost:6379)
• Default TTL (default: 5m)
• Enable active invalidation? If yes: invalidation listen address and shared key
• Use section template: templates/v2/sections/response-caching.yaml
• For security requirements, schema directives, and advanced config: references/response-caching.md (start with the Security section)

Step 5: Generate Config

1. Load the correct version template from templates/{version}/
2. Assemble section templates for supported sectioned features, then merge base-template snippets for APQ/subscriptions as needed
3. Inject user-provided parameters
4. Add a comment block at the top stating the target version

Step 6: Validate

Run the post-generation checklist:

• All env vars referenced in config are documented
• CORS origins don't include wildcards (production)
• Rate limiting is on router: (client-facing), not only all: (subgraph)
• JWT uses issuers (v2) not issuer (v1), or vice versa
• If production: introspection=false, sandbox=false, subgraph_errors=false
• Health check is enabled
• Homepage is disabled (production)
• Run: router config validate <file> if Router binary is available

Required Validation Gate (always run)

After generating or editing any router.yaml, you MUST:

1. Run validation/checklist.md and report pass/fail for each checklist item.
2. Run router config validate <path-to-router.yaml> if Router CLI is available.
3. If Router CLI is unavailable, state that explicitly and still complete the checklist.
4. Do not present the configuration as final until validation is completed.

Configuration as Code (git + CI/CD)

router.yaml is the router's contract with every request — treat it like application code, not an ops afterthought. Whenever you generate or edit config, steer the user toward this workflow:

• Commit router.yaml to version control. It should live in git alongside the service, with changes reviewed via pull request. This gives you history, blame, and rollback for the most safety-critical file in the API layer.
• Never commit secrets. Keep APOLLO_KEY, JWKS URLs, Redis URLs, and invalidation keys out of the file — reference them with ${env.*} expansion and inject at deploy time. The committed file should be safe to read by anyone with repo access.
• Validate in CI. Run router config validate router.yaml on every PR so a malformed or version-mismatched config fails the build before it ships. Pin the Router version used in CI to the version you deploy.
• Pair config changes with schema checks. Schema changes flow through rover subgraph check / rover subgraph publish (the rover skill); config changes flow through this validate-in-CI gate. Both gate the same deploy.
• Promote the same file across environments. Differences between dev and prod should be expressed through env vars, not divergent committed files, so what you reviewed is what runs.

A minimal CI step (provide actual commands only if asked):

# Validate router config on every pull request
- run: router config validate router.yaml

Step 7: Conditional Next Steps Handoff

After answering any Apollo Router request (config generation, edits, validation, or general Router guidance), decide whether the user already has runnable prerequisites:

• GraphOS-managed path: APOLLO_KEY + APOLLO_GRAPH_REF, or
• Local path: a composed supergraph.graphql plus reachable subgraphs

If prerequisites are already present, do not add extra handoff text.

If prerequisites are missing or unknown, end with a concise Next steps handoff (1-3 lines max) that is skill-first and command-free:

1. Suggest the rover skill to compose or fetch the supergraph schema.
2. Suggest continuing with apollo-router once the supergraph is ready to validate and run with the generated config.
3. If subgraphs are missing, suggest apollo-server, graphql-schema, and graphql-operations skills to scaffold and test.

Do not include raw shell commands in this handoff unless the user explicitly asks for commands.