Docs
Try Apollo Studio

Configuring the Apollo Router

Command arguments and YAML config


For router installation instructions, see the quickstart.

You run the Apollo Router with the following command (assuming you're in the same directory as the router executable):

./router --config router.yaml --supergraph supergraph-schema.graphql

Arguments for this command are described below.

Environment variables

If you're using the Apollo Router with managed federation, set these environment variables in its startup command:

APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router
Environment VariableDescription
APOLLO_GRAPH_REF

The graph ref of the registered Apollo graph and variant that the router fetches its supergraph schema from.

Required if using managed federation.

APOLLO_KEY

The graph API key that the Apollo Router should use to authenticate with Apollo Studio when fetching its supergraph schema.

Required if using managed federation.

Command arguments

The router command supports the arguments listed in the table below.

Where indicated, some of these arguments can also be set via an environment variable. If you specify a configuration value using both mechanisms, the command-line argument's value takes precedence.

Argument / Environment VariableDescription
-s / --supergraph

APOLLO_ROUTER_SUPERGRAPH_PATH

The absolute or relative path to the Apollo Router's supergraph schema.

To learn how to compose your supergraph schema with the Rover CLI, see the Federation quickstart.

Required if you are not using managed federation. If you are using managed federation, do not provide this value.

-c / --config

APOLLO_ROUTER_CONFIG_PATH

The absolute or relative path to the router's optional YAML configuration file.

--log

APOLLO_ROUTER_LOG

The log level, indicating the most severe log message type to include. In ascending order of verbosity, can be one of: off, error, warn, info, debug, or trace.

The default value is info.

--hr / --hot-reload

APOLLO_ROUTER_HOT_RELOAD

If provided, the router watches for changes to its schema and configuration files and reloads them automatically without downtime.

APOLLO_UPLINK_ENDPOINTS

The Apollo Uplink URL(s) that the Apollo Router should poll to fetch its latest supergraph schema.

This argument supports providing a comma-separated list of URLs.

For default behavior and possible values, see Apollo Uplink.

APOLLO_UPLINK_POLL_INTERVAL

The amount of time between polls to Apollo Uplink.

The default value is 10s (ten seconds), which is also the minimum allowed value.

APOLLO_UPLINK_TIMEOUT

The request timeout for each poll sent to Apollo Uplink.

The default value is 30s (thirty seconds).

--anonymous-telemetry-disabled

APOLLO_TELEMETRY_DISABLED

Disable sending anonymous usage information to Apollo.

--schema

Prints out a JSON schema of the router's configuration file, including plugin configuration.

-V / --version

Prints out the Apollo Router's version.

Config subcommand

Argument / Environment VariableDescription
schema

Prints out a JSON schema of the Router's configuration file, including plugin configuration.

upgrade

Print configuration that has been upgraded to the current Router version.

YAML config file

The Apollo Router takes an optional YAML configuration file as input via the --config option:

./router --config router.yaml

This file enables you to customize various aspects of your router's behavior, covered in the subsections below.

If you pass the --hot-reload flag to the router command, your router automatically restarts whenever changes are made to its configuration file.

Listen address

By default, the Apollo Router starts an HTTP server that listens on 127.0.0.1:4000. You can specify a different address by setting supergraph.listen:

IPv4

router.yaml
supergraph:
# The socket address and port to listen on
listen: 127.0.0.1:4000

IPv6

router.yaml
supergraph:
# The socket address and port to listen on.
# Note that this must be quoted to avoid interpretation as an array in YAML.
listen: '[::1]:4000'

Unix socket

Listening on a Unix socket is not supported on Windows.

router_unix.yaml
supergraph:
# Absolute path to a Unix socket
listen: /tmp/router.sock

Endpoint path

By default, the router starts an HTTP server that exposes a POST/GET endpoint at path /.

You can specify a different path by setting supergraph.path:

router.yaml
supergraph:
# The path for GraphQL execution
# (Defaults to /)
path: /graphql

The path must start with /.

Path parameters and wildcards are supported. For example:

  • /:my_dynamic_prefix/graphql matches both /my_project_a/graphql and /my_project_b/graphql.
  • /graphql/* matches /graphql/my_project_a and /graphql/my_project_b.
  • /g* matches /graphql and /gateway.

Note: The router does not support wildcards in the middle of a path (e.g., /*/graphql). Instead, use a path parameter (e.g., /:parameter/graphql).

Introspection

By default, the router does not resolve introspection queries. You can enable introspection like so:

router.yaml
# Do not enable introspection in production!
supergraph:
introspection: true

Landing pages

The Apollo Router can serve any of the following landing pages to browsers that visit its endpoint path:

  • A basic landing page that displays an example query curl command (default)

    router.yaml
    # This is the default behavior. You don't need to include this config.
    homepage:
    enabled: true
  • No landing page

    router.yaml
    homepage:
    enabled: false
  • Apollo Sandbox, which enables you to explore your schema and compose operations against it using the Explorer

    Note the additional configuration required to use Sandbox:

    router.yaml
    sandbox:
    enabled: true
    # Sandbox uses introspection to obtain your router's schema.
    supergraph:
    introspection: true
    # Sandbox requires the default landing page to be disabled.
    homepage:
    enabled: false

    ⚠️ Do not enable Sandbox in production! Sandbox requires enabling introspection, which is strongly discouraged in production environments.

Subgraph routing URLs

By default, the Apollo Router obtains the routing URL for each of your subgraphs from the composed supergraph schema you provide it. In most cases, no additional configuration is required.

However, if you do need to override a particular subgraph's routing URL (for example, to handle changing network topography), you can do so with the override_subgraph_url option:

router.yaml
override_subgraph_url:
accounts: http://localhost:8080

In this example, the accounts subgraph URL is overridden to point to http://localhost:8080. The URL specified in the supergraph schema is ignored.

Any subgraphs that are omitted from override_subgraph_url continue to use the routing URL specified in the supergraph schema.

HTTP header rules

See Sending HTTP headers to subgraphs.

Cross-Origin Resource Sharing (CORS)

See Configuring CORS in the Apollo Router.

Defer support

See Apollo Router support for @defer.

External extensibility

See External extensibility in the Apollo Router.

OpenTelemetry tracing

See Tracing in the Apollo Router.

Automatic persisted queries (APQ)

Automatic Persisted Queries (APQ) enable GraphQL clients to send a server the hash of their query string, instead of sending the query string itself. When query strings are very large, this can significantly reduce network usage.

The Apollo Router supports using APQ in its communications with both clients and subgraphs:

  • In its communications with clients, the router acts as a GraphQL server, because it receives queries from clients.
  • In its communications with subgraphs, the router acts as a GraphQL client, because it sends queries to subgraphs.

Because the router's role differs between these two interactions, you configure these APQ settings separately.

APQ with clients

The Apollo Router automatically supports APQ with clients via its in-memory cache. See the caching documentation for related options.

You can disable this APQ support like so:

supergraph:
apq:
enabled: false

APQ with subgraphs

By default, the Apollo Router does not use APQ when sending queries to its subgraphs.

You can configure this APQ support with a combination of global and per-subgraph settings:

router.yaml
supergraph:
apq:
subgraph:
# Disable subgraph APQ globally unless overridden per-subgraph
all:
enabled: false
# Override global APQ setting for individual subgraphs
subgraphs:
products:
enabled: true

In the example above, subgraph APQ is disabled except for the products subgraph.

For more information on APQ, including client configuration, see this article.

TLS

TLS connections to subgraphs are verified using the list of certificate authorities provided by the system. You can override this list with a combination of global and per-subgraph settings:

router.yaml
tls:
subgraph:
# Use these certificate authorities unless overridden per-subgraph
all:
certificate_authorities: "${file./path/to/ca.crt}"
# Override global setting for individual subgraphs
subgraphs:
products:
certificate_authorities: "${file./path/to/product_ca.crt}"

Plugins

You can customize the Apollo Router's behavior with plugins. Each plugin can have its own section in the configuration file with arbitrary values:

example-plugin-router.yaml
plugins:
example.plugin:
var1: "hello"
var2: 1

Variable expansion

You can reference variables directly in your YAML file. This is useful for referencing secrets without including them in the file.

Currently, the Apollo Router supports expansion of environment variables and file paths. Corresponding variables must be prefixed with env. or file.

The router uses Unix-style expansion. Here are some examples:

  • ${env.ENV_VAR_NAME} expands to the value of environment variable ENV_VAR_NAME.
  • ${env.ENV_VAR_NAME:-some_default} expands to the value of environment variable ENV_VAR_NAME, or falls back to the value some_default if the environment variable is not defined.
  • ${file.a.txt} expands to the contents of the file a.txt.
  • ${file.a.txt:-some_default} expands to the contents of the file a.txt, or falls back to the value some_default if the file does not exist.

Variable expansions are valid only for YAML values, not keys:

supergraph:
listen: "${env.MY_LISTEN_ADDRESS}"
example:
password: "${env.MY_PASSWORD}"

Reusing configuration

You can reuse parts of your configuration file in multiple places using standard YAML aliasing syntax:

router.yaml
headers:
subgraphs:
products:
request:
- insert: &insert_custom_header
name: "custom-header"
value: "something"
reviews:
request:
- insert: *insert_custom_header

Here, the name and value entries under &insert_custom_header are reused under *insert_custom_header.

Configuration awareness in your text editor

The Apollo Router can generate a JSON schema for config validation in your text editor. This schema helps you format the YAML file correctly and also provides content assist.

Generate the schema with the following command:

./router config schema > configuration_schema.json

After you generate the schema, configure your text editor. Here are the instructions for some commonly used editors:

Upgrading your router configuration

New releases of the Apollo Router might introduce breaking changes to the YAML config file's expected format, usually to extend existing functionality or improve usability.

If you run a new version of your router with a configuration file that it no longer supports:

  1. The router emits a warning on startup.
  2. The router attempts to translate your provided configuration to the new expected format.
    • If the translation succeeds without errors, the router starts up as usual.
    • If the translation fails, the router terminates.

If you encounter this warning, you can use the router config upgrade command to see the new expected format for your existing configuration file:

./router config upgrade <path_to_router.yaml>

You can also view a diff of exactly which changes are necessary to upgrade your existing configuration file:

./router config upgrade --diff <path_to_router.yaml>
Edit on GitHub
Previous
Federation version support
Next
Caching