Docs
Launch GraphOS Studio

Gateway migration guide

Migrating to the Apollo Router from @apollo/gateway


Learn how to migrate a federated using the @apollo/gateway library to the and gain significant performance improvements while making zero changes to your .

What's different?

Whereas @apollo/gateway is an npm package, the is packaged as a static, standalone binary.

The exposes the most common critical features via declarative configuration. You customize the router with a

that takes effect at startup. Configurations can be modified and take effect without restart if you either start the with the --hot-reload flag or set the APOLLO_ROUTER_HOT_RELOAD environment variable to true.

Although you can download the 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 .

Take inventory of your gateway configuration

The @apollo/gateway library is an extension to the

library, and you need to consider your existing configuration of both gateway and server libraries when moving to the . For example, you might need to consider your customizations for the HTTP headers your receive from client requests, or for passing specific headers back to the client from specific .

Because the 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 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 supports the following environment variables used by @apollo/gateway:

  • APOLLO_KEY
  • APOLLO_GRAPH_REF

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

ApolloGateway constructor options

The number of options you currently provide to your ApolloGateway constructor varies depending on whether you're using

. If you are using , you might even be providing zero options to this constructor!

supergraphSdl

The

is used in non- to provide a composed via a file or other string. Usually, that schema is composed using the
Rover CLI
.

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

  • with your move to the .

  • Provide the --supergraph command-line to the on startup:

    ./router --supergraph supergraph-schema.graphql

    The 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 on startup. The Apollo Router does not support this in-process composition.

Instead, you need to perform using

or the
Rover CLI
. With either of these methods, the can hot-reload its without restarting, and you avoid the possibility of a failure that results in downtime.

buildService

The

enables you to customize the HTTP requests that the gateway sends to your .

Common use cases include:

  • Overriding URLs at runtime
  • Propagating headers to via RemoteGraphQLDataSource

logger

The

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

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

  • context
  • plugins

For the full list of options, see

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

.

plugins

This constructor option is an array of built-in or custom plugins that extend '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

, check whether any
configuration options
provide that same functionality. For example, the supports options for propagating HTTP headers to and enabling OpenTelemetry instrumentation.

If one of your @apollo/gateway plugins does require a corresponding customization, we encourage you to describe your use case in the Router repo's

. It might represent core functionality that the 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 , enabling teams to more quickly add the functionality they need before native support is available.

Supported customizations

The currently supports two types of customizations that hook into the request-handling pipeline:

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

.

Kubernetes deployment

For migrating to the 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

and start a new discussion if you don't find what you're looking for.

Previous
Quickstart
Next
Federation version support
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company