Setting up managed federation

This article describes how to connect your supergraph to Apollo GraphOS to enable managed federation features.

As with all changes, you should first set up managed federation in a non-production environment, such as staging. To support this, you can create multiple variants of your supergraph in GraphOS Studio. Each variant represents a distinct version of the same graph for different environments.

1. Get started

First, complete the Set up Apollo tools step from this tutorial, including:

Creating an Apollo account
Creating a graph in Studio
Installing and authenticating the Rover CLI

Then return here.

2. Publish all subgraph schemas

In a supergraph architecture, each of your subgraphs uses the Rover CLI to publish its schema to GraphOS:

Do the following for each of your subgraphs:

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 router will use to communicate with the subgraph (e.g., http://products-graphql.svc.cluster.local:4001/).
Run the rover subgraph publish command, providing it your subgraph's schema in one of the ways shown:
# Provide a local .graphql file path
rover subgraph publish my-graph@my-variant --name products --routing-url http://products-graphql.svc.cluster.local:4001/ --schema ./schema.graphql

# Provide an introspection result via stdin
rover 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 managed router can fetch the latest supergraph schema from GraphOS.

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 GraphOS Studio.

3. Modify your router's startup command

If you've already set up Apollo Federation without connecting your router to GraphOS, you're probably passing the --supergraph (or -s) option to the Apollo Router's startup command:

1
./router --config ./router.yaml --supergraph ./your-local-supergraph.graphql

The --supergraph option is specific to non-managed federation, in which supergraph schema composition is performed via the Rover CLI and provided via a file path.

Remove the --supergraph option (but leave --config if it's present):

1
./router --config ./router.yaml

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

4. Connect your router to GraphOS

Like your subgraphs, your router uses a graph API key to identify itself to GraphOS.

After obtaining your graph API key, you set the following environment variables in your router's environment:

APOLLO_KEY (set this to your graph API key)
APOLLO_GRAPH_REF
- This variable tells the router which variant of which graph to use (for example, docs-example-graph@production). You can find your variant's graph ref at the very top of its README page in GraphOS Studio.

5. Deploy the modified router

You can now deploy your modified router, which will fetch its supergraph schema from GraphOS on startup. It can then begin executing operations across your subgraphs.

Overview

Uplink