Moving to the Apollo Router from @apollo/gateway

The Apollo Router is a graph router for federated graphs that's written in the Rust programming language. It's a new, higher-performance alternative to the Node.js-based @apollo/gateway library.

If you're currently using the @apollo/gateway library in your federated graph, this article walks you through the steps to move over to the Apollo Router.

What's different?

Unlike @apollo/gateway, the Apollo Router is usually packaged as a static, standalone binary. You can pass this binary a YAML configuration file at startup to customize its behavior. Additionally, if you start your router with the --hot-reload flag, or set the APOLLO_ROUTER_HOT_RELOAD environment variable to true you can even modify that configuration and have changes picked up without restarting the router.

You can use the Apollo Router as a library in a larger project, but our goal is to remove the need to write custom code in your graph router (which is necessary with @apollo/gateway). Instead, the Apollo Router exposes the most common critical features via declarative configuration.

Take inventory of your gateway configuration

The @apollo/gateway library is an extension to the Apollo Server library, and you need to consider your existing configuration of both libraries when moving to the Apollo Router. For example, you might be customizing which HTTP headers your subgraphs receive from client requests, or passing specific headers back to the client from specific subgraphs.

Because the Apollo Router is an entirely new tool with a different configuration mechanism, you should make a checklist of your gateway's custom behaviors to make sure those behaviors all remain when your migration is complete.

Start by looking for configuration and customizations in these places:

• Environment variables
• Non-Apollo telemetry and instrumentation (e.g., OpenTelemetry or Datadog)
• Constructor options passed to new ApolloGateway({ ... })
• Constructor options passed to new ApolloServer({ ... })
• Specific plugins passed to new ApolloServer({ plugins: [ ... ] })
• Custom middleware (e.g., Express, Koa, Fastify)

The sections below provide more details on what to look for in each of these categories.

Environment variables

Many Apollo tools use environment variables prefixed with APOLLO_ to set certain values, such as an API key for communicating with Apollo Studio.

Make sure to note any environment variables you set in your existing gateway's environment, especially those prefixed with APOLLO_

The Apollo Router supports the following environment variables used by @apollo/gateway:

• APOLLO_KEY
• APOLLO_GRAPH_REF

The Apollo Router renames the following environment variables used by @apollo/gateway:

• APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT → APOLLO_UPLINK_ENDPOINTS
  • Currently, the Apollo Router supports providing only a single Uplink endpoint to this environment variable.

ApolloGateway constructor options

The number of options you currently provide to your ApolloGateway constructor varies depending on whether you're using managed federation. If you are using managed federation, you might even be providing zero options to this constructor!

supergraphSdl

This constructor option is used in non-managed federation to provide a composed supergraph schema via a file or other string. Usually, that schema is composed using the Rover CLI.

You can achieve this option's effect with the Apollo Router in one of the following ways:

• Move to managed federation with your move to the Apollo Router.

• Provide the --supergraph command-line argument to the Apollo Router on startup:

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

  Copy

  The router watches this schema file and hot-reloads it whenever it changes.

serviceList / IntrospectAndCompose

If you provide one of these constructor options, your gateway performs its own supergraph schema composition on startup. The Apollo Router does not support this in-process composition.

Instead, you need to perform composition using managed federation or the Rover CLI. With either of these methods, the Apollo Router can hot-reload its supergraph schema without restarting, and you avoid the possibility of a composition failure that results in downtime.

buildService

The buildService function enables you to customize the requests that the gateway sends to your subgraphs.

Common use cases include:

• Overriding subgraph URLs at runtime
  • In the Apollo Router, you can use the override_subgraph_urls option.
• Propagating headers to subgraphs via RemoteGraphQLDataSource
  • In the Apollo Router, you can use the headers option.

logger

This constructor option enables you to specify a different logger for messages that are produced by the ApolloGateway. By default, it inherits from the logger used by your ApolloServer instance. This option is also useful for changing logging verbosity.

In the Apollo Router, logging is JSON-structured in production environments by default, and you can adjust the verbosity. More advanced logging can be enabled through the use of plugins.

For more information, see Logging in the Apollo Router.

ApolloServer constructor options

The ApolloServer constructor supports a large variety of options, but for the purposes of moving to the Apollo Router, we'll focus on the following:

• context
• plugins

context

This constructor option is an object that enables you to propagate information across the request lifecycle. Use cases include:

• Authentication information
• Header propagation

The Apollo Router provides similar functionality.

plugins

This constructor option is an array of built-in or custom plugins that extend Apollo Server's functionality.

If you provide plugins to your ApolloServer instance, take note of each plugin's functionality and add it to your migration checklist. Then, before attempting to replicate a plugin's functionality via an Apollo Router plugin, check whether any router configuration options can achieve the same behavior. For example, the router supports options for propagating HTTP headers to subgraphs and enabling OpenTelemetry instrumentation.

For less common use cases, we also want to help build an ecosystem of plugins for the Apollo Router, allowing users to enable custom behaviors and ship the functionality they need before native support is available.

Supported customizations

The Apollo Router currently supports two types of customizations that hook into its request pipeline:

• Native Rust plugins
• Rhai scripts (experimental)

Examples for each are provided in their respective documentation, and in the Router repo.

In the future, we expect to offer the ability to enable functionality in other languages, in the supergraph itself, or by communicating with services alongside the Router (e.g., gRPC).

Reporting migration issues

If you don't find the migration answers you need in these docs, we'd love to know. Please search for existing GitHub discussions and start a new discussion if you don't find what you're looking for.