Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Docs
Launch GraphOS Studio

Configuring the Apollo Router

Command arguments and YAML config


For installation instructions, see the quickstart.

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

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

s for this command are described below.

Environment variables

If you're using the Apollo with managed federation and , set these environment s in the startup command:

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

The graph ref for the graph and that the fetches its from (e.g., docs-example-graph@staging).

Required if using managed federation.

APOLLO_KEY

The graph API key that the should use to authenticate with when fetching its .

Required if using managed federation.

Command-line options

Where indicated, some of these options can also be provided via an environment . If an option is provided both ways, the command-line value takes precedence.

Option / Environment VariableDescription
-s / --supergraph

APOLLO_ROUTER_SUPERGRAPH_PATH

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

To learn how to compose your with the 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 's optional YAML configuration file.

--dev

⚠️ Do not set this option in production!

If set, the Apollo runs in dev mode to help with local development.

Learn more about dev mode.

--hr / --hot-reload

APOLLO_ROUTER_HOT_RELOAD

If set, the watches for changes to its configuration file and any file passed with --supergraph and reloads them automatically without downtime. This setting only affects local files provided to the . The and configuration provided from via Launches (and delivered via Uplink) are always loaded automatically, regardless of this setting.

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

APOLLO_UPLINK_ENDPOINTS

If using managed federation, the Apollo Uplink URL(s) that the 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.

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

If set, disables sending anonymous usage information to Apollo.

--listen

APOLLO_ROUTER_LISTEN_ADDRESS

If set, the listen address of the .

-V / --version

If set, the prints its version number, then exits.

--schema

Deprecated—use ./router config schema instead.

If set, the prints a JSON 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: true
homepage:
enabled: false
supergraph:
introspection: true
include_subgraph_errors:
all: true
plugins:
# Enable with the header, Apollo-Expose-Query-Plan: true
experimental.expose_query_plan: true

config subcommands

The Apollo 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>
SubcommandDescription
schema

Prints a JSON representation of the 's full supported configuration format.

Use this to enable configuration awareness in your text editor.

upgrade

Takes a config file created for a previous version of the Apollo and outputs the corresponding configuration for the current version.

For details, see Upgrading your router configuration.

YAML config file

The Apollo 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 's behavior, covered in the subsections below.

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

Listen address

By default, the Apollo 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 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 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 does not resolve queries. You can enable introspection like so:

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

Landing pages

The Apollo 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 and compose s against it using the

    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 , which is strongly discouraged in production environments.

Subgraph routing URLs

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

However, if you do need to override a particular '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:8080
accounts: "${env.ACCOUNTS_SUBGRAPH_HOST_URL}"

In this example, the organizations URL is overridden to point to http://localhost:8080, and the accounts URL is overridden to point to a new URL using variable expansion. The URL specified in the is ignored.

Any s that are omitted from override_subgraph_url continue to use the routing URL specified in the .

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

Caching

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

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

You can configure certain caching behaviors for generated query plans and APQ (but not 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 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 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 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 supports TLS to authenticate and encrypt communications, both on the client side and the 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 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 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 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 verifies TLS connections to s 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-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}"

The 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 's configuration since using SSL_CERT_FILE also overrides certificates for sending telemetry and communicating with Apollo Uplink.

Note: If the 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 = hash
authorityKeyIdentifier = keyid:always,issuer:always
# this has to be disabled
# basicConstraints = CA:TRUE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign
subjectAltName = DNS:local.apollo.dev
issuerAltName = issuer:copy

Make sure to change the subjectAltName to the 's name. This produces the file as server.crt which can be used in certificate_authorities.

TLS client authentication for subgraph requests

The supports mutual TLS authentication (mTLS) with the s. 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-subgraph
all:
client_authentication:
certificate_chain: ${file./path/to/certificate_chain.pem}
key: ${file./path/to/key.pem}
# Override global setting for individual subgraphs
subgraphs:
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 . Download the latest version.

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

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

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

router.yaml
limits:
# Network-based limits
experimental_http_max_request_bytes: 2000000 # Default value: 2 MB
# Parser-based limits
parser_max_tokens: 15000 # Default value
parser_max_recursion: 4096 # Default value
# Operation-based limits (Enterprise only)
max_depth: 100
max_height: 200
max_aliases: 30
max_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 s 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 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 's GraphQL parser to prevent stack overflows. This corresponds to the deepest nesting level of any single GraphQL or defined in a query document.

The default value is 4096.

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

query GetProducts {
allProducts { #1
...productVariation
delivery { #2
fastestDelivery #3
}
}
}
fragment ProductVariation on Product {
variation { #1
name #2
}
}

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

In versions of the Apollo 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 to improve performance and memory behavior.

To opt in to the new validation implementation, set:

router.yaml
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 '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 s directly in your YAML config file. This is useful for referencing secrets without including them in the file.

Currently, the Apollo supports expansion of environment s and file paths. Corresponding variables are prefixed with env. and file., respectively.

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

  • ${env.ENV_VAR_NAME} expands to the value of environment ENV_VAR_NAME.
  • ${env.ENV_VAR_NAME:-some_default} expands to the value of environment ENV_VAR_NAME, or falls back to the value some_default if the environment 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.

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 ing 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 can generate a JSON for config validation in your text editor. This schema helps you format the YAML file correctly and also provides content assist.

Generate the with the following command:

./router config schema > configuration_schema.json

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

Upgrading your router configuration

New releases of the Apollo 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 emits a warning on startup.
  2. The attempts to translate your provided configuration to the new expected format.
    • If the translation succeeds without errors, the starts up as usual.
    • If the translation fails, the 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>
Previous
Enterprise features
Next
In-memory caching
Edit on GitHubEditForumsDiscord