Router Configuration

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

Environment variables

If you're using the GraphOS Router with managed federation and GraphOS Studio, set these environment variables in the startup command:

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

Command-line options

After installing the Apollo Router Core in your current working directory, you can run the router with the following example command:

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 --dev flag is equivalent to running ./router --hot-reload with the following configuration options:

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

config subcommands

GraphOS Router and Apollo Router Core provide 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

GraphOS Router and Apollo Router Core take an optional YAML configuration file as input via the --config option:

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 --hot-reload flag to the router command, your router automatically restarts whenever changes are made to its configuration file.

Listen address

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

IPv4

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

IPv6

1supergraph:
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

1supergraph:
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:

1supergraph:
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!
2supergraph:
3  introspection: true

Debugging

• To configure logging, see Logging in the router.

• To configure the inclusion of subgraph errors, see Subgraph error inclusion.

Landing pages

The 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)

  YAML

  router.yaml

  copy

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

• No landing page

  YAML

  router.yaml

  copy

  1homepage:
  2  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:

  YAML

  router.yaml

  copy

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

  ⚠️ caution

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

Subgraph routing URLs

By default, the 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:

1override_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 variable expansion. 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.

If you need to override the subgraph URL at runtime on a per-request basis, you can use request customizations in the SubgraphService layer.

Caching

By default, the 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 In-Memory Caching in the router.

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 GraphOS 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 GraphOS Router.

Native query plannerSince 1.49.0

Starting with v1.49.0, the router can run a Rust-native query planner. This native query planner can be run by itself to plan all queries, replacing the legacy JavaScript implementation.

1experimental_query_planner_mode: new

1supergraph:
2  generate_query_fragments: true

Learn more in Native Query Planner docs.

Query planner poolsSince 1.44.0

You can improve the performance of the router's query planner by configuring parallelized query planning.

By default, the query planner plans one operation at a time. It plans one operation to completion before planning the next one. This serial planning can be problematic when an operation takes a long time to plan and consequently blocks the query planner from working on other operations.

To resolve such blocking scenarios, you can enable parallel query planning. Configure it in router.yaml with supergraph.query_planning.experimental_parallelism:

1supergraph:
2  query_planning:
3    experimental_parallelism: auto # number of available cpus 

The value of experimental_parallelism is the number of query planners in the router's query planner pool. A query planner pool is a preallocated set of query planners from which the router can use to plan operations. The total number of pools is the maximum number of query planners that can run in parallel and therefore the maximum number of operations that can be worked on simultaneously.

Valid values of experimental_parallelism:

• Any integer starting from 1

• The special value auto, which sets the number of query planners equal to the number of available CPUs on the router's host machine

The default value of experimental_parallelism is 1.

In practice, you should tune experimental_parallelism based on metrics and benchmarks gathered from your router.

Enhanced operation signature normalizationSince 1.49.0

Apollo's legacy operation signature algorithm removes information about certain fields, such as input objects and aliases. This removal means some operations may have the same normalized signature though they are distinct operations.

Enhanced normalization incorporates input types and aliases in signature generation. It also includes other improvements that make it more likely that two operations that only vary slightly have the same signature.

Configure enhanced operation signature normalization in router.yaml with the telemetry.apollo.signature_normalization_algorithm option:

1telemetry: 
2  apollo:
3    signature_normalization_algorithm: enhanced # Default is legacy

Once you enable this configuration, operations with enhanced signatures might appear with different operation IDs than they did previously in GraphOS Studio.

Input types

Enhanced signatures include input object type shapes, while still redacting any actual values. Legacy signatures replace input object type with {}.

Given the following example operation:

query InlineInputTypeQuery {
  inputTypeQuery(
    input: { 
      inputString: "foo", 
      inputInt: 42, 
      inputBoolean: null, 
      nestedType: { someFloat: 4.2 }, 
      enumInput: SOME_VALUE_1, 
      nestedTypeList: [ { someFloat: 4.2, someNullableFloat: null } ], 
      listInput: [1, 2, 3] 
    }
  ) {
    enumResponse
  }
}

The legacy normalization algorithm generates the following signature:

query InlineInputTypeQuery {
  inputTypeQuery(input: {}) {
    enumResponse
  }
}

The enhanced normalization algorithm generates the following signature:

query InlineInputTypeQuery {
  inputTypeQuery(
    input: {
      inputString: "", 
      inputInt: 0, 
      inputBoolean: null, 
      nestedType: {someFloat: 0}, 
      enumInput: SOME_VALUE_1, 
      nestedTypeList: [{someFloat: 0, someNullableFloat: null}], 
      listInput: []
    }
  ) {
      enumResponse
  }
}

Aliases

Enhanced signatures include any field aliases used in an operation. Legacy signatures remove aliases completely, meaning the signature may be invalid if the same field was used with multiple aliases.

Given the following example operation:

query AliasedQuery {
  noInputQuery {
    interfaceAlias1: interfaceResponse {
      sharedField
    }
    interfaceAlias2: interfaceResponse {
      ... on InterfaceImplementation1 {
        implementation1Field
      }
      ... on InterfaceImplementation2 {
        implementation2Field
      }
    }
    inputFieldAlias1: objectTypeWithInputField(boolInput: true) {
      stringField
    }
    inputFieldAlias2: objectTypeWithInputField(boolInput: false) {
      intField
    }
  }
}

The legacy normalization algorithm generates the following signature:

query AliasedQuery {
  noInputQuery {
    interfaceResponse {
      sharedField
    }
    interfaceResponse {
      ... on InterfaceImplementation1 {
        implementation1Field
      }
      ... on InterfaceImplementation2 {
        implementation2Field
      }
    }
    objectTypeWithInputField(boolInput: true) {
      stringField
    }
    objectTypeWithInputField(boolInput: false) {
      intField
    }
  }
}

The enhanced normalization algorithm generates the following signature:

query AliasedQuery {
  noInputQuery {
    interfaceAlias1: interfaceResponse {
      sharedField
    }
    interfaceAlias2: interfaceResponse {
      ... on InterfaceImplementation1 {
        implementation1Field
      }
      ... on InterfaceImplementation2 {
        implementation2Field
      }
    }
    inputFieldAlias1: objectTypeWithInputField(boolInput: true) {
      stringField
    }
    inputFieldAlias2: objectTypeWithInputField(boolInput: false) {
      intField
    }
  }
}

Extended reference reportingSince 1.50.0

You can configure the router to report enum and input object references for enhanced insights and operation checks. Apollo's legacy reference reporting doesn't include data about enum values and input object fields, meaning you can't view enum and input object field usage in GraphOS Studio. Legacy reporting can also cause inaccurate operation checks.

Configure extended reference reporting in router.yaml with the telemetry.apollo.metrics_reference_mode option like so:

1telemetry: 
2  apollo:
3    metrics_reference_mode: extended # Default is legacy

Configuration effect timing

Once you configure extended reference reporting, you can view enum value and input field usage alongside object field usage in GraphOS Studio for all subsequent operations.

Configuring extended reference reporting automatically turns on enhanced operation checks, though you won't see an immediate change in your operations check behavior.

This delay is because operation checks rely on historical operation data. To ensure sufficient data to distinguish between genuinely unused values and those simply not reported in legacy data, enhanced checks require some operations with extended reference reporting turned on.

Enhanced operation checks

Thanks to extended reference reporting, operation checks can more accurately flag issues for changes to enum values and input object fields. See the comparison table below for differences between standard operation checks based on legacy reference reporting and enhanced checks based on extended reference reporting.

Safelisting with persisted queries

You can enhance your graph's security with GraphOS Router 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 Safelisting with persisted queries for more information.

HTTP header rules

See Sending HTTP headers to subgraphs.

Traffic shaping

To configure the shape of traffic between clients, routers, and subgraphs, see Traffic shaping in the router.

Cross-Origin Resource Sharing (CORS)

See Configuring CORS in the router.

Defer support

See router support for @defer.

Query batching support

See GraphOS Router's support for query batching.

Subscription support

See GraphQL subscriptions in the GraphOS Router.

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 JWT authentication in the GraphOS Router.

Cross-site request forgery (CSRF) prevention

To configure CSRF prevention, see CSRF prevention in the router.

Subgraph authentication

To configure subgraph authentication with AWS SigV4, see a configuration example.

External coprocessing

See External coprocessing in the GraphOS Router.

Telemetry and monitoring

The 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 router telemetry overview.

TLS

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

1tls:
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 variable expansion guide.

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:

1tls:
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:

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

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

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

1tls:
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 YAML config file. For example:

1apq:
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 GraphOS 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.

1limits:
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 this article.

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 lexical and ignored tokens.

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.

1query GetProducts {
2  allProducts { #1
3    ...productVariation
4    delivery { #2
5      fastestDelivery #3
6    }
7  }
8}
9
10fragment 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.

Demand control

See Demand Control to learn how to analyze the cost of operations and to reject requests with operations that exceed customizable cost limits.

Early cancel

Up until Apollo Router Core v1.43.1, when the client closed the connection without waiting for the response, the entire request was cancelled and did not go through the entire pipeline. Since this causes issues with request monitoring, the router introduced a new behavior in 1.43.1. Now, the entire pipeline is executed if the request is detected as cancelled, but subgraph requests are not actually done. The response will be reported with the 499 status code, but not actually sent to the client. To go back to the previous behavior of immediately cancelling the request, the following configuration can be used:

1supergraph:
2  early_cancel: true

Additionally, since v1.43.1, the router can show a log when it detects that the client canceled the request. This log can be activated with:

1supergraph:
2  experimental_log_on_broken_pipe: true

Plugins

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

1plugins:
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 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:

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

Fragment reuse and generation

By default, the 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:

1supergraph:
2  experimental_reuse_query_fragments: false

Alternatively, the router can be configured to generate fragments for subgraph requests. When set to true, the 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.

1supergraph:
2  generate_query_fragments: true

Reusing configuration

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

1headers:
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 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 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:

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