Configuring the Apollo Router

Learn how to customize the behavior of your Apollo Router with environment variables, command-line commands and options, and YAML file configuration.

Environment variables

If you're using the Apollo Router with

1
APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router

Command-line options

After

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

This reference lists and describes the options supported by the router binary. Where indicated, some of these options can also be provided via an environment variable. If an option is provided both ways, the command-line value takes precedence.

Dev mode defaults

Setting the

1
sandbox:
2
  enabled: true
3
homepage:
4
  enabled: false
5
supergraph:
6
  introspection: true
7
include_subgraph_errors:
8
  all: true
9
plugins:
10
  # Enable with the header, Apollo-Expose-Query-Plan: true
11
  experimental.expose_query_plan: true

config subcommands

The Apollo Router provides a set of subcommands for interacting with its configuration. You run these subcommands with the following syntax:

1
./router config schema
2
./router config upgrade <path-to-config-file.yaml>

YAML config file

The Apollo Router takes an optional YAML configuration file as input via the

1
./router --config router.yaml

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

If you pass the

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

1
supergraph:
2
  # The socket address and port to listen on
3
  listen: 127.0.0.1:4000

IPv6

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

Unix socket

1
supergraph:
2
  # Absolute path to a Unix socket
3
  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:

1
supergraph:
2
  # The path for GraphQL execution
3
  # (Defaults to /)
4
  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, /gateway and /graphql/api.

Introspection

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

1
# Do not enable introspection in production!
2
supergraph:
3
  introspection: true

Debugging

• To configure logging, see

  Logging in the Apollo Router
  .

• To configure the inclusion of subgraph errors, see

  Subgraph error inclusion
  .

Landing pages

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

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

  YAML

  router.yaml

  1
  # This is the default behavior. You don't need to include this config.
  2
  homepage:
  3
    enabled: true

  Copy

• No landing page

  YAML

  router.yaml

  1
  homepage:
  2
    enabled: false

  Copy

• 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:

  YAML

  router.yaml

  1
  sandbox:
  2
    enabled: true
  3
  
  4
  # Sandbox uses introspection to obtain your router's schema.
  5
  supergraph:
  6
    introspection: true
  7
  
  8
  # Sandbox requires the default landing page to be disabled.
  9
  homepage:
  10
    enabled: false

  Copy

  ⚠️ CAUTION

  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. The URL can use HTTP and HTTPS for network access to subgraph, or have the following shape for Unix sockets usage: unix:///path/to/subgraph.sock

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:

1
override_subgraph_url:
2
  organizations: http://localhost:8080
3
  accounts: "${env.ACCOUNTS_SUBGRAPH_HOST_URL}"

In this example, the organizations subgraph URL is overridden to point to http://localhost:8080, and the accounts subgraph URL is overridden to point to a new URL using

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

If you need to override the subgraph URL at runtime on a per-request basis, you can use

Caching

By default, the Apollo Router stores the following data in its in-memory cache to improve performance:

• Generated query plans
• Automatic persisted queries (APQ)
• Introspection responses

You can configure certain caching behaviors for generated query plans and APQ (but not introspection responses). For details, see

If you have a GraphOS Enterprise plan:

• You can configure a Redis-backed distributed cache that enables multiple router instances to share cached values. For details, see
  Distributed caching in the Apollo Router
  .
• You can configure a Redis-backed entity cache that enables a client query to retrieve cached entity data split between subgraph reponses. For details, see
  Subgraph entity caching in the Apollo Router
  .

Safelisting with persisted queries

You can enhance your graph's security by maintaining a persisted query list (PQL), an operation safelist made by your first-party apps. As opposed to automatic persisted queries (APQ) where operations are automatically cached, operations must be preregistered to the PQL. Once configured, the router checks incoming requests against the PQL.

See

HTTP header rules

See

Traffic shaping

To configure the shape of traffic between clients, routers, and subgraphs, see

Cross-Origin Resource Sharing (CORS)

See

Defer support

See

Query batching support

See

Subscription support

See

Authorization support

• To configure authorization directives, see

  Authorization directives
  .

• To configure the authorization plugin, see

  Configuration options
  .

JWT authentication

To enable and configure JWT authentication, see

Cross-site request forgery (CSRF) prevention

To configure CSRF prevention, see

Subgraph authentication

To configure subgraph authentication with AWS SigV4, see a

External coprocessing

See

Telemetry and monitoring

The Apollo Router supports standard and custom instrumentation to collect telemetry data from its request and response processing pipeline to produce logs, metrics and traces to export.

See the

TLS

The Apollo Router supports TLS to authenticate and encrypt communications, both on the client side and the subgraph side. It works automatically on the subgraph side if the subgraph URL starts with https://.

TLS support is configured in the tls section, under the supergraph key for the client side, and the subgraph key for the subgraph side, with configuration possible for all subgraphs and overriding per subgraph.

The list of supported TLS versions and algorithms is static, it cannot be configured.

Supported TLS versions:

• TLS 1.2
• TLS 1.3

Supported cipher suites:

• TLS13_AES_256_GCM_SHA384
• TLS13_AES_128_GCM_SHA256
• TLS13_CHACHA20_POLY1305_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

Supported key exchange groups:

• X25519
• SECP256R1
• SECP384R1

TLS termination

Clients can connect to the router directly over HTTPS, without terminating TLS in an intermediary. You can configure this in the tls configuration section:

1
tls:
2
  supergraph:
3
    certificate: ${file./path/to/certificate.pem}
4
    certificate_chain: ${file./path/to/certificate_chain.pem}
5
    key: ${file./path/to/key.pem}

To set the file paths in your configuration with Unix-style expansion, you can follow the examples in the

The router expects the file referenced in the certificate_chain value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).

Overriding certificate authorities for subgraphs

The router verifies TLS connections to subgraphs using the list of certificate authorities the system provides. You can override this list with a combination of global and per-subgraph settings:

1
tls:
2
  subgraph:
3
    # Use these certificate authorities unless overridden per-subgraph
4
    all:
5
      certificate_authorities: "${file./path/to/ca.crt}"
6
    # Override global setting for individual subgraphs
7
    subgraphs:
8
      products:
9
        certificate_authorities: "${file./path/to/product_ca.crt}"

The router expects the file referenced in the certificate_chain value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).

You can only configure these certificates via the router's configuration since using SSL_CERT_FILE also overrides certificates for sending telemetry and communicating with Apollo Uplink.

If the subgraph is presenting a self-signed certificate, it must be generated with the proper file extension and with basicConstraints disabled. You can generate it with the following command line command from a certificate signing request, in this example, server.csr:

1
openssl x509 -req -in server.csr -signkey server.key -out server.crt -extfile v3.ext

You can generate a v3.ext extension file like so:

1
subjectKeyIdentifier   = hash
2
authorityKeyIdentifier = keyid:always,issuer:always
3
# this has to be disabled
4
# basicConstraints       = CA:TRUE
5
keyUsage               = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign
6
subjectAltName         = DNS:local.apollo.dev
7
issuerAltName          = issuer:copy

This produces the file as server.crt which can be used in certificate_authorities.

TLS client authentication for subgraph requests

The router supports mutual TLS authentication (mTLS) with the subgraphs. This means that it can authenticate itself to the subgraph using a certificate chain and a cryptographic key. It can be configured as follows:

1
tls:
2
  subgraph:
3
    # Use these certificates and key unless overridden per-subgraph
4
    all:
5
      client_authentication:
6
        certificate_chain: ${file./path/to/certificate_chain.pem}
7
        key: ${file./path/to/key.pem}
8
    # Override global setting for individual subgraphs
9
    subgraphs:
10
      products:
11
        client_authentication:
12
          certificate_chain: ${file./path/to/certificate_chain.pem}
13
          key: ${file./path/to/key.pem}

Redis TLS configuration

For Redis TLS connections, you can set up a client certificate or override the root certificate authority by configuring tls in your router's

1
apq:
2
  router:
3
    cache:
4
      redis:
5
        urls: [ "rediss://redis.example.com:6379" ]
6
        tls:
7
          certificate_authorities: ${file./path/to/ca.crt}
8
          client_authentication:
9
            certificate_chain: ${file./path/to/certificate_chain.pem}
10
            key: ${file./path/to/key.pem}

Request limits

The Apollo Router supports enforcing three types of request limits for enhanced security:

• Network-based limits
• Lexical, parser-based limits
• Semantic, operation-based limits (this is an
  Enterprise feature
  )

The router rejects any request that violates at least one of these limits.

1
limits:
2
  # Network-based limits
3
  http_max_request_bytes: 2000000 # Default value: 2 MB
4

5
  # Parser-based limits
6
  parser_max_tokens: 15000 # Default value
7
  parser_max_recursion: 500 # Default value
8

9
  # Operation-based limits (Enterprise only)
10
  max_depth: 100
11
  max_height: 200
12
  max_aliases: 30
13
  max_root_fields: 20

Operation-based limits (Enterprise only)

See

Network-based limits

http_max_request_bytes

Limits the amount of data read from the network for the body of HTTP requests, to protect against unbounded memory consumption. This limit is checked before JSON parsing. Both the GraphQL document and associated variables count toward it.

The default value is 2000000 bytes, 2 MB.

Before increasing this limit significantly consider testing performance in an environment similar to your production, especially if some clients are untrusted. Many concurrent large requests could cause the Router to run out of memory.

Parser-based limits

parser_max_tokens

Limits the number of tokens a query document can include. This counts all tokens, including both

The default value is 15000.

parser_max_recursion

Limits the deepest level of recursion allowed by the router's GraphQL parser to prevent stack overflows. This corresponds to the deepest nesting level of any single GraphQL operation or fragment defined in a query document.

The default value is 500.

In the example below, the GetProducts operation has a recursion of three, and the ProductVariation fragment has a recursion of two. Therefore, the max recursion of the query document is three.

1
query GetProducts {
2
  allProducts { #1
3
    ...productVariation
4
    delivery { #2
5
      fastestDelivery #3
6
    }
7
  }
8
}
9

10
fragment ProductVariation on Product {
11
  variation { #1
12
    name #2
13
  }
14
}

Note that the router calculates the recursion depth for each operation and fragment separately. Even if a fragment is included in an operation, that fragment's recursion depth does not contribute to the operation's recursion depth.

GraphQL Validation Mode

We are experimenting with a new GraphQL validation implementation written in Rust. The legacy implementation is part of the JavaScript query planner. This is part of a project to remove JavaScript from the Router to improve performance and memory behavior.

To opt in to the new validation implementation, set:

1
experimental_graphql_validation_mode: new

This is an experimental option while we are still finding edge cases in the new implementation, but it will become the default in the future.

Plugins

You can customize the Apollo Router's behavior with

1
plugins:
2
  example.plugin:
3
    var1: "hello"
4
    var2: 1

Variable expansion

You can reference variables directly in your YAML config 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 are prefixed with env. and file., respectively.

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:

1
supergraph:
2
  listen: "${env.MY_LISTEN_ADDRESS}" 
3
example:
4
  password: "${env.MY_PASSWORD}" 

Fragment reuse and generation

By default, the Apollo Router will attempt to reuse fragments from the original query while forming subgraph requests. This behavior can be disabled by setting the option to false:

1
supergraph:
2
  experimental_reuse_query_fragments: false

Alternatively, the Apollo Router can be configured to generate fragments for subgraph requests. When set to true, the Apollo Router will extract inline fragments only into fragment definitions before sending queries to subgraphs. This can significantly reduce the size of the query sent to subgraphs, but may increase the time it takes for planning. Note that this option and experimental_reuse_query_fragments are mutually exclusive; if both are explicitly set to true, generate_query_fragments will take precedence.

1
supergraph:
2
  generate_query_fragments: true

Reusing configuration

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

1
headers:
2
  subgraphs:
3
    products:
4
      request:
5
        - insert: &insert_custom_header
6
            name: "custom-header"
7
            value: "something"
8
    reviews:
9
      request:
10
        - 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:

1
./router config schema > configuration_schema.json

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

• Visual Studio Code
• Emacs
• IntelliJ
• Sublime
• Vim

Upgrading your router configuration

New releases of the Apollo Router might introduce breaking changes to the

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:

1
./router config upgrade <path_to_config.yaml>

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

1
./router config upgrade --diff <path_to_config.yaml>

Related topics

• Checklist for configuring the router for production