Docs
Launch GraphOS Studio

Configuring the Apollo Router

Command arguments and YAML config


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

Environment variables

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

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

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

Required when using managed federation, except when using an offline license to run the .

APOLLO_KEY

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

Required when using managed federation, except when using an offline license to run the .

Command-line options

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

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

Option / Environment VariableDescription
-s / --supergraph

APOLLO_ROUTER_SUPERGRAPH_PATH, APOLLO_ROUTER_SUPERGRAPH_URLS

The 's supergraph schema. Specified by absolute or relative path (-s / --supergraph <supergraph_path>, or APOLLO_ROUTER_SUPERGRAPH_PATH), or a comma-separated list of URLs (APOLLO_ROUTER_SUPERGRAPH_URLS).

💡 Avoid embedding tokens in APOLLO_ROUTER_SUPERGRAPH_URLS because the URLs may appear in log messages.

Setting this option disables polling from Apollo Uplink to fetch the latest .

To learn how to compose your with the , see the Federation quickstart.

Required if you are not using . If you are using , you may need to set this option when following advanced deployment workflows.

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

--license

APOLLO_ROUTER_LICENSE_PATH, APOLLO_ROUTER_LICENSE

An offline . Enables Enterprise features when disconnected from GraphOS.

An offline license is specified either as an absolute or relative path to a license file (--license <license_path> or APOLLO_ROUTER_LICENSE_PATH), or as the stringified contents of a license (APOLLO_ROUTER_LICENSE).

When not set, the retrieves an from GraphOS via Apollo Uplink.

For information about fetching an offline license and configuring the , see Offline Enterprise license.

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 schema representation of its full supported configuration format, then exits.

Dev mode defaults

⚠️ CAUTION

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 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 schema representation of the 's full supported configuration format.

Use this schema to enable configuration awareness in your text editor.

upgrade

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

For details, see Upgrading your router configuration.

YAML config file

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

💡 TIP

Enable your text editor to validate the format and content of your YAML configuration file by configuring it with the router's configuration schema.

Listen address

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

ⓘ NOTE

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, /gateway and /graphql/api.

ⓘ 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

Debugging

Landing pages

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

  • A basic landing page that displays an example 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 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

    ⚠️ CAUTION

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

Subgraph routing URLs

By default, the obtains the routing URL for each of your 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 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 stores the following data in its in-memory cache to improve performance:

  • Generated s
  • ()
  • responses

You can configure certain caching behaviors for generated and (but not responses). For details, see In-memory caching in the Apollo Router.

If you have a GraphOS Enterprise plan:

Safelisting with persisted queries

You can enhance your 's security by maintaining a (), an safelist made by your first-party apps. As opposed to () 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.

Traffic shaping

To configure the shape of traffic between clients, , and , see Traffic shaping in the Apollo Router.

Cross-Origin Resource Sharing (CORS)

See Configuring CORS in the Apollo Router.

Defer support

See Apollo Router support for @defer.

Query batching support

See Apollo Router's experimental support for query batching.

Subscription support

See GraphQL subscriptions in the Apollo Router.

Authorization support

JWT authentication

To enable and configure JWT authentication, see JWT authentication in the Apollo Router.

Cross-site request forgery (CSRF) prevention

To configure CSRF prevention, see CSRF prevention in the Apollo Router.

Subgraph authentication

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

External coprocessing

See External coprocessing in the Apollo Router.

Telemetry and monitoring

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

TLS

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

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

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

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

ⓘ NOTE

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

The 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
http_max_request_bytes: 2000000 # Default value: 2 MB
# Parser-based limits
parser_max_tokens: 15000 # Default value
parser_max_recursion: 500 # 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

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 and associated 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 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 parser to prevent stack overflows. This corresponds to the deepest nesting level of any single GraphQL or defined in a .

The default value is 500.

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

ⓘ NOTE

In versions of the 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 validation implementation written in Rust. The legacy implementation is part of the JavaScript . 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 '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 directly in your YAML config file. This is useful for referencing secrets without including them in the file.

Currently, the supports expansion of environment variables 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 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.

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

© 2024 Apollo Graph Inc.

Privacy Policy

Company