Gateway Migration Guide
Migrating to the router from @apollo/gateway
Learn how to migrate a federated supergraph using the @apollo/gateway
library to the GraphOS Router or Apollo Router Core and gain significant performance improvements while making zero changes to your subgraphs.
What's different?
Whereas @apollo/gateway
is an npm package, the router is packaged as a static, standalone binary.
The router exposes the most common critical features via declarative configuration. You customize the router with a YAML configuration file that takes effect at startup. Configurations can be modified and take effect without restart if you either start the router with the --hot-reload
flag or set the APOLLO_ROUTER_HOT_RELOAD
environment variable to true
.
Although you can download the Apollo Router Core source and use it as a library in a larger project and as the basis for a self-hosted GraphOS Router, 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 Apollo Server library, and you need to consider your existing configuration of both gateway and server libraries when moving to the router. For example, you might need to consider your customizations for the HTTP headers your subgraphs receive from client requests, or for passing specific headers back to the client from specific subgraphs.
Because the 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 GraphOS Studio.
Make sure to note any environment variables you set in your existing gateway's environment, especially those prefixed with APOLLO_
The router supports the following environment variables used by @apollo/gateway
:
APOLLO_KEY
APOLLO_GRAPH_REF
The 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
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
The supergraphSdl
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 router in one of the following ways:
Move to managed federation with your move to the router.
Provide the
--supergraph
command-line argument to the router on startup:Text1./router --supergraph supergraph-schema.graphql
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 router doesn't support this in-process composition.
Instead, you need to perform composition using managed federation or the Rover CLI . With either of these methods, the 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 HTTP requests that the gateway sends to your subgraphs.
Common use cases include:
Overriding subgraph URLs at runtime
In the router, you can use the
override_subgraph_urls
option .
Propagating headers to subgraphs via
RemoteGraphQLDataSource
In the router, you can use the
headers
option .
logger
The logger
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 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 router .
ApolloServer
constructor options
The ApolloServer
constructor supports a large variety of options, but for the purposes of moving to the router, we'll focus on the following:
context
plugins
For the full list of options, see ApolloServer
options . If you're using other options, additional steps might be necessary to replicate the same behavior. Please open a discussion on our GitHub repository so we can understand your needs and help you with a solution.
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 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.
Before you attempt to replicate a plugin's functionality via a router customization , check whether any router configuration options provide that same functionality. For example, the router supports options for propagating HTTP headers to subgraphs and enabling OpenTelemetry instrumentation.
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 GitHub discussions . It might represent core functionality that the router should provide out of the box, and we can help discuss the design.
For less common use cases, we also want to help build an ecosystem of shared customizations for the router, enabling teams to more quickly add the functionality they need before native support is available.
Supported customizations
The router supports two types of customizations that hook into the request-handling pipeline:
Rhai is a scripting language designed for use with Rust applications.
Examples for each are provided in their respective documentation, and in the Router repo .
Kubernetes deployment
For migrating to the router deployed on Kubernetes, see some tips for configuring your router deployment .
Responses and errors
Apollo Gateway runs its core GraphQL server using Apollo Server and a user configured HTTP server. GraphOS Router is built as an all-in-one product with the GraphQL and HTTP server bundled together. With this change there may be some slight difference to the logic of HTTP status codes or GraphQL error extension codes.
Refer the full list of router error codes for any changes to your gateway implementation. If you need to customize the responses, refer to router customizations .
Reporting migration issues
If you encounter a migration issue that isn't resolved by this article, please search for existing GitHub discussions and start a new discussion if you don't find what you're looking for.