Launch Apollo Studio

Setting up managed federation

This article describes how to set up Apollo Studio for a data graph that uses Apollo Federation.

As with all changes, you should first set up managed federation in a non-production environment, such as staging. To support this, you can use variants, which are distinct versions of the same data graph for different environments.

1. Get started

If you haven't yet, complete the first two steps from the Apollo Studio getting started guide:

  1. Create your account
  2. Create your first graph

In the Register your schema step, make sure you follow the instructions for a GraphQL server that uses Apollo Federation.

2. Register all implementing service schemas

In a federated architecture, each of your graph's implementing services uses the Apollo CLI to register its schema as a separate service of the same graph:

Products service
Reviews service
Inventory service
Apollo Schema Registry

First, install the Apollo CLI if you haven't yet.

Then, do the following for each of your implementing services:

  1. Obtain the following values, which are required for the apollo service:push command:

    • The URL that your federated gateway will use to communicate with the service (e.g., http://products-graphql.svc.cluster.local:4001/).
    • The name that uniquely identifies the service within your graph (e.g., products).
    • The service's schema. The Apollo CLI can either:
      • Use a .gql or .graphql file saved on your local machine, or
      • Perform an introspection query on the running service to fetch the schema
  2. Run the apollo service:push command, providing the following options (documented below):

    apollo service:push \
      --localSchemaFile=./schema.gql \ # (or --endpoint)
      --graph=docs-example-graph \
      --variant=local-development \
      --serviceName=products \

The URL of the running service to perform an introspection query on.

Provide this only if the CLI should obtain your schema via introspection.


The path of the schema file to register.

Provide this only if the CLI should obtain your schema via a local file.


The graph API key that the CLI should use to authenticate with the schema registry.

By default, the CLI uses the value of the APOLLO_KEY environment variable.

--graphThe name of your graph in Apollo Studio (e.g., docs-example-graph)

The variant of your graph to register the schema with.

The default value is current.

--serviceNameThe service's unique name in your federated graph (e.g., products).
--serviceURLThe URL that your federated gateway will use to communicate with the service.

As you register your service schemas, the schema registry attempts to compose their latest versions into a single federated schema. Whenever composition succeeds, your gateway can fetch the latest federated schema from the registry.

3. Modify the gateway (if necessary)

This section assumes you are using Apollo Server with the @apollo/gateway library as your gateway.

If you've already set up Apollo Federation without Apollo Studio, the constructor of your ApolloGateway instance probably includes a serviceList option, like this:

const gateway = new ApolloGateway({
  serviceList: [
    { name: 'Products', url: 'http://products-graphql.svc.cluster.local:4001/' },
    // Additional services defined here

This option specifies the name and URL for each of your graph's implementing services. With managed federation, this information is no longer hardcoded in the gateway's constructor! Instead, the gateway regularly polls Apollo for this information. This enables you to add and remove implementing services from your graph without needing to restart your gateway.

Remove the serviceList argument from your ApolloGateway constructor entirely:

const gateway = new ApolloGateway();

4. Connect the gateway to Studio

Like your implementing services, your gateway uses an API key to identify itself to Studio.

Provide your API key to your gateway by setting it as the value of the APOLLO_KEY environment variable (ENGINE_API_KEY in apollo-server pre-2.13.0) in your gateway's environment. Apollo Server will automatically read this environment variable on startup.

Note that if you specify the API key in a .env file, the gateway does not automatically read this file. Use a library such as dotenv.

When running your gateway in an environment where outbound traffic to the internet is restricted, consult the directions for configuring a proxy within Apollo Server.

5. Deploy the modified gateway

You can now deploy your modified gateway to begin fetching your federated schema from Studio instead of directly from your services.

On startup, your gateway will use its API key to access its federation config from Google Cloud Storage. After it completes schema composition based on the config, the gateway can begin executing operations across your implementing services.

Edit on GitHub