Join us on Nov 7 for GraphQL Summit Virtual

Setting up managed federation

This article describes how to set up Apollo Studio for a 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 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 subgraph schemas

In a federated architecture, each of your graph's subgraphs uses the Rover CLI to register its schema with Apollo:

If you haven't yet:

Then, do the following for each of your subgraphs:

  1. Obtain the following values, which are required for the rover subgraph publish command:

    • The name that uniquely identifies the subgraph within your graph (e.g., products).

    • The URL that your gateway will use to communicate with the subgraph (e.g., http://products-graphql.svc.cluster.local:4001/).

  2. Run the rover subgraph publish command, providing it your subgraph's schema in one of the ways shown:

    Bash
    1# Provide a local .graphql file path
2rover subgraph publish my-graph@my-variant --name products --routing-url http://products-graphql.svc.cluster.local:4001/ --schema ./schema.graphql 
3
4# Provide an introspection result via stdin
5rover subgraph introspect http://localhost:4000 | rover subgraph publish my-graph@my-variant --name products --routing-url http://products-graphql.svc.cluster.local:4001/ --schema -

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

You can also manually fetch your latest supergraph schema with the rover supergraph fetch command, or retrieve it from your graph's Schema > SDL tab in Apollo Studio.

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 supergraphSdl or serviceList option, like this:

JavaScript
1const gateway = new ApolloGateway({
2  supergraphSdl
3});

These two options are specific to non-managed federation, in which supergraph schema composition is performed via the Rover CLI (supergraphSdl), or in the gateway itself (serviceList).

With managed federation, composition is instead performed by Apollo, and the gateway regularly polls Apollo for an updated schema. This enables you to add, remove, and modify your subgraphs without needing to restart your gateway.

Remove the supergraphSdl or serviceList argument from your ApolloGateway constructor entirely:

JavaScript
1const gateway = new ApolloGateway();

Connecting to Apollo Uplink

Uplink is the Apollo-hosted endpoint that your gateway polls to fetch its latest supergraph schema. Beginning in @apollo/gateway v0.34, the gateway polls the correct Uplink URL by default.

In previous versions of @apollo/gateway, you need to provide the Uplink URL via an environment variable. We recommend updating to the latest version of the library, but if you can't, define the following in your gateway's environment:

Bash
1APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT=https://uplink.api.apollographql.com/

4. Connect the gateway to Studio

Like your subgraphs, your gateway uses an API key (Graph Admin role) to identify itself to Studio.

How to obtain a graph API key
API keys are secret credentials. Never share them outside your organization or commit them to version control. Delete and replace API keys that you believe are compromised.API keys are not available for development graphs.
  1. Go to studio.apollographql.com and click the graph you want to obtain an API key for.
  2. If a "Publish your Schema" dialog appears, select the From Apollo Server tab. Copy the value that appears after APOLLO_KEY= in the instructions (it begins with service:), and you're all set.Otherwise, proceed to the next step.
  3. Open your graph's Settings page and scroll down to the API Keys section. Either copy an existing key or click Create New Key. Give your key a name, such as Production. This helps you keep track of each API key's use.
    If you don't see the API Keys section, you don't have sufficient permissions for your graph. Only organization members with the Org Admin or Graph Admin role can manage graph API keys. Learn more about member roles.
  4. Copy the key's value.

After obtaining your graph API key, you set two environment variables in your gateway's environment. If you're using a .env file with a library like dotenv, those environment variables look like this:

sh
.env
1APOLLO_KEY=<YOUR_GRAPH_API_KEY>
2APOLLO_GRAPH_REF=<YOUR_GRAPH_ID>@<VARIANT>

You can also set this value directly in the command you use to start your gateway.

The third environment variable, APOLLO_GRAPH_REF, tells the gateway which graph to use and with which variant. You would supply your graph id and the variant you want to use (for example, current). You can always find a a graph's ref at the top of its Schema Reference page in Studio.

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

On startup, your gateway will use its API key to fetch its federation config from Apollo. It can then begin executing operations across your subgraphs.

Edit on GitHub

Forums