Docs
Launch GraphOS Studio

Rover supergraph commands

For use with Apollo Federation


A supergraph (also called a federated graph) is a graph composed of multiple subgraphs:

Supergraph (A + B + C)
Subgraph A
Subgraph B
Subgraph C

commands that interact with s begin with rover supergraph. These commands primarily deal with supergraph schemas.

Fetching a supergraph schema from GraphOS

supergraph fetch

This command requires authenticating Rover with GraphOS.

You can use to fetch the of any federated Studio graph it has access to. Run the supergraph fetch command, like so:

rover supergraph fetch my-supergraph@my-variant

To fetch a 's API instead, use graph fetch. Learn about different schema types.

The my-supergraph@my-variant in the example above specifies the ID of the Studio graph you're fetching from, along with which variant you're fetching.

You can omit @ and the name. If you do, uses the default variant, named current.

Composing a supergraph schema

supergraph compose

You can use the supergraph compose command to compose a based on a supergraph configuration file, like so:

rover supergraph compose --config ./supergraph.yaml

You can also pass config via stdin:

cat ./supergraph.yaml | rover supergraph compose --config -

YAML configuration file

The configuration file (often referred to as supergraph.yaml) includes configuration options for each of your subgraphs. The following example file configures a with two s (films and people):

supergraph.yaml
federation_version: =2.3.2
subgraphs:
films:
routing_url: https://films.example.com
schema:
file: ./films.graphql
people:
routing_url: https://people.example.com
schema:
file: ./people.graphql

In the above example, The YAML file specifies each 's public-facing URL (routing_url), along with the path to its (schema.file).

A single configuration file can pull s from a variety of sources. For example, here's a configuration that includes subgraph schemas from three different types of sources:

supergraph.yaml
federation_version: =2.3.2
subgraphs:
# Local .graphql file
films:
routing_url: https://films.example.com
schema:
file: ./films.graphql
# Subgraph introspection
people:
routing_url: https://example.com/people # <- can be omitted if the same as introspection URL
schema:
subgraph_url: http://127.0.0.1:4002
introspection_headers: # Optional headers to include in introspection request
Authorization: Bearer ${env.PEOPLE_AUTH_TOKEN}
# Apollo Studio graph ref
actors:
routing_url: http://localhost:4005 # <- can be omitted if matches existing URL in Studio
schema:
graphref: mygraph@current
subgraph: actors

Variable expansion

The supergraph.yaml file supports expansion using the same syntax as Apollo Router.

Output format

By default, rover supergraph compose outputs a supergraph schema document to stdout. You provide this artifact to @apollo/gateway or the 🦀 Apollo Router on startup.

⚠️ Your router/gateway fails to start up if you provide it with a supergraph schema that it doesn't support! To ensure compatibility, we recommend that you always test launching your /gateway in a CI pipeline with the it will ultimately use in production.

You can save the output to a local .graphql file like so:

# Creates prod-schema.graphql or overwrites if it already exists
rover supergraph compose --config ./supergraph.yaml --output prod-schema.graphql

For more on passing values via stdout, see Using stdout.

Federation 2 ELv2 license

The first time you use Federation 2 composition on a particular machine, prompts you to accept the terms and conditions of the ELv2 license. On future invocations, remembers that you already accepted the license and doesn't prompt you again (even if you update Rover).

⚠️ Important: CI systems wipe away any persisted configuration on each run, and they can't accept the interactive ELv2 prompt. To automatically accept the prompt in CI, do any of the following:

  • Set the environment APOLLO_ELV2_LICENSE=accept in your CI environment.
  • Include --elv2-license accept in your rover supergraph compose command.
  • Run yes | rover supergraph compose

The ELv2-licensed supergraph plugin (built from this source) is installed to ~/.rover/bin if you installed with the curl | sh installer, and to ./node_modules/.bin/ if you installed with npm.

Setting a composition version

The supergraph compose command supports both Federation 2 and Federation 1 composition.

⚠️ Note that if you use Federation 1 composition and any of your s uses a Federation 2 , composition will fail!

Federation 1 and Federation 2 use different composition algorithms, which are implemented in different libraries:

Whenever you run rover supergraph compose, automatically downloads the version of the library for your selected federation version.

⚠️ The federation_version you target must not exceed the highest version supported by your router! Make sure to update your before incrementing your federation_version. For details, see this support table.

Automatic updates

If you don't specify a federation_version in supergraph.yaml, determines which version to use according to the following logic:

No
Yes
No
Yes
Is the federation_version key
present in supergraph.yaml?
Does at least one subgraph schema
opt in to Federation 2?
Use the version specified
by federation_version
Use latest Federation 1
composition
Use latest Federation 2
composition

A "opts in" to Federation 2 by adding a special @link described in this article.

The latest federation library version is stored in this file on the main branch of the repository. If you don't specify an exact federation version, new plugin versions will be delivered and sourced from this file.

This auto-update flow will cause issues if you don't update your router version prior to updating your composition pipeline. We strongly recommend always specifying an exact federation_version.

Preventing auto-updates

In some cases, you might want to skip updating its composition library to the latest version. For example, you might have a slow or nonexistent network connection.

In these cases, you can pass the --skip-update flag to rover supergraph compose. If you provide this flag, your supergraph.yaml file must specify a federation_version (which is recommended regardless).

Legacy Rover versions

Versions of prior to v0.5.0 support only Federation 1 composition, via the @apollo/federation JavaScript package.

We recommend updating to the latest version of as soon as possible. If you're still using a legacy version, see the following compatibility table regarding support for different versions of the @apollo/gateway library:

Rover versionGateway version
<= v0.2.x<= v0.38.x
>= v0.3.x>= v0.39.x
Previous
subgraph
Next
template
Edit on GitHubEditForumsDiscord