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 and GraphOS, set these environment variables in the startup command:
APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router
Environment Variable | Description |
---|---|
| The graph ref for the GraphOS graph and variant that the router fetches its supergraph schema from (e.g., Required if using managed federation. |
| The graph API key that the router should use to authenticate with GraphOS when fetching its supergraph schema. Required if using managed federation. |
Command-line options
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.
Option / Environment Variable | Description |
---|---|
| 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. |
| The absolute or relative path to the router's optional YAML configuration file. |
| ⚠️ Do not set this option in production! If set, the Apollo Router runs in dev mode to help with local development. |
| If set, the router watches for changes to its configuration file and any supergraph file passed with |
| The log level, indicating the most severe log message type to include. In ascending order of verbosity, can be one of: The default value is |
| If using managed federation, the Apollo Uplink URL(s) that the router should poll to fetch its latest configuration. Almost all managed router instances should omit this option to use the default set of Uplink URLs. If you specify multiple URLs, separate them with commas (no whitespace). For default behavior and possible values, see Apollo Uplink. |
| The amount of time between polls to Apollo Uplink. The default value is |
| The request timeout for each poll sent to Apollo Uplink. The default value is |
| If set, disables sending anonymous usage information to Apollo. |
| If set, the listen address of the router. |
| If set, the router prints its version number, then exits. |
| Deprecated—use If set, the router prints a JSON schema representation of its full supported configuration format, then exits. |
Dev mode defaults
⚠️ Do not set the --dev
option in production! If you want to replicate any specific dev mode functionality in production, instead make the corresponding modifications to your YAML config file.
Setting the --dev
flag is equivalent to running ./router --hot-reload
with the following configuration options:
sandbox:enabled: truehomepage:enabled: falsesupergraph:introspection: trueinclude_subgraph_errors:all: trueplugins:# Enable with the header, Apollo-Expose-Query-Plan: trueexperimental.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:
./router config schema./router config upgrade <path-to-config-file.yaml>
Subcommand | Description |
---|---|
| Prints a JSON schema representation of the router's full supported configuration format. Use this schema to enable configuration awareness in your text editor. |
| Takes a config file created for a previous version of the Apollo Router and outputs the corresponding configuration for the current version. For details, see Upgrading your router configuration. |
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 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 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
supergraph:# The socket address and port to listen onlisten: 127.0.0.1:4000
IPv6
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.
supergraph:# Absolute path to a Unix socketlisten: /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
:
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:
# 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: trueNo landing page
router.yamlhomepage:enabled: falseApollo 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.yamlsandbox: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:
override_subgraph_url:organizations: http://localhost:8080accounts: "${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 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 In-memory caching in the Apollo Router.
If you have a GraphOS Enterprise plan, you can also configure a Redis-backed distributed cache that enables multiple router instances to share cached values. For details, see Distributed 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 Safelisting with persisted queries for more information.
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
.
Subscription support
See GraphQL subscriptions in the Apollo Router.
External coprocessing
See External coprocessing in the Apollo Router.
OpenTelemetry tracing
See Tracing in the Apollo Router.
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:
tls:supergraph:certificate: ${file./path/to/certificate.pem}certificate_chain: ${file./path/to/certificate_chain.pem}key: ${file./path/to/key.pem}
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:
tls:subgraph:# Use these certificate authorities unless overridden per-subgraphall:certificate_authorities: "${file./path/to/ca.crt}"# Override global setting for individual subgraphssubgraphs:products: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.
Note: 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
:
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:
subjectKeyIdentifier = hashauthorityKeyIdentifier = keyid:always,issuer:always# this has to be disabled# basicConstraints = CA:TRUEkeyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSignsubjectAltName = DNS:local.apollo.devissuerAltName = issuer:copy
Make sure to change the subjectAltName
field to the subgraph's name.
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:
tls:subgraph:# Use these certificates and key unless overridden per-subgraphall:client_authentication:certificate_chain: ${file./path/to/certificate_chain.pem}key: ${file./path/to/key.pem}# Override global setting for individual subgraphssubgraphs:products:client_authentication:certificate_chain: ${file./path/to/certificate_chain.pem}key: ${file./path/to/key.pem}
Request limits
Request limits are currently in preview.
To set request limits, you must run v1.17 or later of the Apollo Router. Download the latest version.
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.
limits:# Network-based limitsexperimental_http_max_request_bytes: 2000000 # Default value: 2 MB# Parser-based limitsparser_max_tokens: 15000 # Default valueparser_max_recursion: 4096 # Default value# Operation-based limits (Enterprise only)max_depth: 100max_height: 200max_aliases: 30max_root_fields: 20
Operation-based limits (Enterprise only)
See this article.
Network-based limits
http_max_request_bytes
This configuration is currently experimental.
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 4096
.
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.
query GetProducts {allProducts { #1...productVariationdelivery { #2fastestDelivery #3}}}fragment ProductVariation on Product {variation { #1name #2}}
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.
In versions of the Apollo Router prior to 1.17, this limit was defined via the config option experimental_parser_recursion_limit
.
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:
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 plugins. Each plugin can have its own section in the configuration file with arbitrary values:
plugins:example.plugin:var1: "hello"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 variableENV_VAR_NAME
.${env.ENV_VAR_NAME:-some_default}
expands to the value of environment variableENV_VAR_NAME
, or falls back to the valuesome_default
if the environment variable is not defined.${file.a.txt}
expands to the contents of the filea.txt
.${file.a.txt:-some_default}
expands to the contents of the filea.txt
, or falls back to the valuesome_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:
headers:subgraphs:products:request:- insert: &insert_custom_headername: "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:
- The router emits a warning on startup.
- 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_config.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_config.yaml>