Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free

Setting Up Managed Federation

Connect your supergraph to Apollo GraphOS

This article describes how to connect your to Apollo GraphOS to enable 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 . Each 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 in Studio
  • Installing and authenticating the

2. Publish all subgraph schemas

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

rover subgraph publish
rover subgraph publish
rover subgraph publish
Products subgraph
Reviews subgraph
Inventory subgraph
Schema Registry

Do the following for each of your :

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

    • The name that uniquely identifies the within your graph (e.g., products).
    • The URL that your 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:

    # 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 , the schema registry attempts to compose their latest versions into a single . Whenever 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 's startup command:

./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 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):

./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)
    • This tells the router which variant of which graph to use (for example, docs-example-graph@production). You can find your variant's 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.

Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy