Rover supergraph commands
For use with Apollo Federation
A supergraph (also called a federated graph) is a graph composed of multiple subgraphs:
Rover commands that interact with supergraphs begin with
rover supergraph. These commands primarily deal with supergraph schemas.
Fetching a supergraph schema from Apollo Studio
This command requires authenticating Rover with Apollo Studio.
You can use Rover to fetch the supergraph schema of any federated Studio graph variant it has access to. Run the
supergraph fetch command, like so:
rover supergraph fetch my-supergraph@my-variant
To fetch a supergraph's API schema instead, use
graph fetch. Learn about different schema types.
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 variant name. If you do, Rover uses the default variant, named
Composing a supergraph schema
You can use the
supergraph compose command to compose a supergraph schema 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 supergraph configuration file (often referred to as
supergraph.yaml) includes configuration options for each of your subgraphs. The following example file configures a supergraph with two subgraphs (
federation_version: =2.3.2subgraphs:films:routing_url: https://films.example.comschema:file: ./films.graphqlpeople:routing_url: https://people.example.comschema:file: ./people.graphql
In the above example, The YAML file specifies each subgraph's public-facing URL (
routing_url), along with the path to its schema (
A single configuration file can pull subgraph schemas from a variety of sources. For example, here's a configuration that includes subgraph schemas from three different types of sources:
federation_version: =2.3.2subgraphs:# Local .graphql filefilms:routing_url: https://films.example.comschema:file: ./films.graphql# Subgraph introspectionpeople:routing_url: https://example.com/peopleschema:subgraph_url: https://example.com/people# Apollo Studio graph refactors:routing_url: https://localhost:4005schema:graphref: mygraph@currentsubgraph: actors
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 router/gateway in a CI pipeline with the supergraph schema it will ultimately use in production.
You can save the schema output to a local
.graphql file like so:
# Creates prod-schema.graphql or overwrites if it already existsrover supergraph compose --config ./supergraph.yaml --output prod-schema.graphql
For more on passing values via
stdout, see Using
Federation 2 ELv2 license
The first time you use Federation 2 composition on a particular machine, Rover prompts you to accept the terms and conditions of the ELv2 license. On future invocations, Rover 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 Rover 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 variable
APOLLO_ELV2_LICENSE=acceptin your CI environment.
--elv2-license acceptin your
rover supergraph composecommand.
yes | rover supergraph compose
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
supergraph compose command supports both Federation 2 and Federation 1 composition.
⚠️ Note that if you use Federation 1 composition and any of your subgraphs uses a Federation 2 schema, composition will fail!
Federation 1 and Federation 2 use different composition algorithms, which are implemented in different libraries:
- Federation 1:
- Federation 2:
Whenever you run
rover supergraph compose, Rover automatically downloads the version of the library for your selected federation version.
federation_version you target must not exceed the highest version supported by your router! Make sure to update your router before incrementing your
federation_version. For details, see this support table.
If you don't specify a
supergraph.yaml, Rover determines which version to use according to the following logic:
A subgraph schema "opts in" to Federation 2 by adding a special
@link directive described in this article.
The latest federation library version is stored in this file on the
main branch of the Rover 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
In some cases, you might want Rover 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 Rover prior to v0.5.0 support only Federation 1 composition, via the
We recommend updating to the latest version of Rover as soon as possible. If you're still using a legacy version, see the following compatibility table regarding support for different versions of the
|Rover version||Gateway version|
|<= v0.2.x||<= v0.38.x|
|>= v0.3.x||>= v0.39.x|