Setting up managed federation

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

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

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:

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 router 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
   2
   rover 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
   5
   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 -

   Copy

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

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

1
const gateway = new ApolloGateway();

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 applies in scenarios where the router doesn't retrieve the supergraph schema by polling Apollo Uplink. These include:

• Enabling different deployment environments to refer to a single graph variant, for example, for blue-green deployment: Use a workflow with the Platform API to compose and retrieve the supergraph schema for each environment. This enables each environment's router to use the environment's supergraph schema, and then a single graph variant can capture and analyze the operations and traffic of either environment when deployed.

• Unmanaged federation: The Rover CLI composes the supergraph schema and passes the schema's file path to the router via the --supergraph option.

For other scenarios where the router retrieves the supergraph schema from Apollo Uplink, remove the --supergraph option (but leave --config if it's present):

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

With federation managed by GraphOS, composition is performed when subgraph schemas are published, and the router regularly polls for an updated supergraph schema from Apollo Uplink. 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 can either fetch its supergraph schema from GraphOS on startup or specify its supergraph schema for deployment in a particular environment. It can then begin executing operations across your subgraphs.