Gateway migration guide
Migrating to the Apollo Router from @apollo/gateway
Learn how to migrate a federated supergraph using the @apollo/gateway
library to the Apollo Router and gain significant performance improvements while making zero changes to your subgraphs.
What's different?
Whereas @apollo/gateway
is an npm package, the Apollo Router is packaged as a static, standalone binary.
The Apollo Router exposes the most common critical features via declarative configuration. You customize the router with a --hot-reload
flag or set the APOLLO_ROUTER_HOT_RELOAD
environment variable to true
.
Although you can download the Apollo Router source and use it as a library in a larger project, you may not need to because the features that were implemented by custom code with @apollo/gateway
may be standard, supported features of the router.
Take inventory of your gateway configuration
The @apollo/gateway
library is an extension to the
Because the Apollo Router uses an entirely 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 tonew 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
- This argument supports providing a comma-separated list of URLs.
ApolloGateway
constructor options
ApolloGateway
constructor optionsThe number of options you currently provide to your ApolloGateway
constructor varies depending on whether you're using
supergraphSdl
supergraphSdl
The supergraphSdl
option
You can achieve this option's effect with the Apollo Router in one of the following ways:
- Move to managed federationwith your move to the Apollo Router.
Provide the
--supergraph
command-line argument to the Apollo Router on startup:./router --supergraph supergraph-schema.graphqlThe router watches this schema file and hot-reloads it whenever it changes.
serviceList
/ IntrospectAndCompose
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
buildService
buildService
The buildService
function
Common use cases include:
- Overriding subgraph URLs at runtime
- In the Apollo Router, you can use the .
override_subgraph_urls
option
- In the Apollo Router, you can use the
- Propagating headers to subgraphs via
RemoteGraphQLDataSource
- In the Apollo Router, you can use the .
headers
option
- In the Apollo Router, you can use the
logger
logger
The logger
constructor optionApolloGateway
. 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
For more information, see
ApolloServer
constructor options
ApolloServer
constructor optionsThe 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
For the full list of options, see ApolloServer
options
context
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
plugins
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.
Before you attempt to replicate a plugin's functionality via an Apollo Router
If one of your @apollo/gateway
plugins does require a corresponding router customization, we encourage you to describe your use case in the Router repo's
For less common use cases, we also want to help build an ecosystem of shared customizations for the Apollo Router, enabling teams to more quickly add the functionality they need before native support is available.
Supported customizations
The Apollo Router currently supports two types of customizations that hook into the request-handling pipeline:
- Rhai scripts
- Rhai is a scripting language designed for use with Rust applications.
- External coprocessing
Examples for each are provided in their respective documentation, and in the
Kubernetes deployment
For migrating to the Apollo Router deployed on Kubernetes, see some tips for
Reporting migration issues
If you encounter a migration issue that isn't resolved by this article, please search for existing