Rover supergraph Commands
For use with Apollo Federation supergraphs
A supergraph 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 GraphOS
supergraph fetch
This command requires authenticating Rover with GraphOS.
You can use Rover to fetch the supergraph schema of any federated GraphOS Studio variant it has access to. Run the supergraph fetch
command, like so:
1rover supergraph fetch my-supergraph@my-variant
To fetch a supergraph's API schema instead, use graph fetch
. Learn about different schema types.
The argument 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.
@
and the variant name. If you do, Rover uses the default variant, named current
.Composing a supergraph schema
supergraph compose
You can use the supergraph compose
command to compose a supergraph schema based on a supergraph configuration file, like so:
1rover supergraph compose --config ./supergraph.yaml
You can also pass config via stdin:
1cat ./supergraph.yaml | rover supergraph compose --config -
From a Studio variant
You can optionally pass a variant's graph ref to download each subgraph's SDL and compose the supergraph SDL like so:
1rover supergraph compose --graph-ref platform@staging
You can optionally pass a YAML configuration file to override specific subgraphs or add a new one. This is useful for testing new subgraph schemas before publishing them.
For example, given a supergraph_override.yaml
file like this:
subgraphs:
products:
routing_url: http://localhost:4000
schema:
file: ./products.graphql
You can override a variant's published products
subgraph like so:
rover supergraph compose \
--graph-ref docs-example-graph@current \
--config path/to/supergraph_override.yaml
Note that you only need to set routing_url
if you want to change it from the routing URL registered for the subgraph in GraphOS.
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 (films
and people
):
1federation_version: =2.3.2
2subgraphs:
3 films:
4 routing_url: https://films.example.com
5 schema:
6 file: ./films.graphql
7 people:
8 routing_url: https://people.example.com
9 schema:
10 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 (schema.file
).
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:
1federation_version: =2.3.2
2subgraphs:
3
4 # Local .graphql file
5 films:
6 routing_url: https://films.example.com
7 schema:
8 file: ./films.graphql
9
10 # Subgraph introspection
11 people:
12 routing_url: https://example.com/people # <- can be omitted if the same as introspection URL
13 schema:
14 subgraph_url: http://127.0.0.1:4002
15 introspection_headers: # Optional headers to include in introspection request
16 Authorization: Bearer ${env.PEOPLE_AUTH_TOKEN}
17
18 # GraphOS Studio graph ref
19 actors:
20 routing_url: http://localhost:4005 # <- can be omitted if matches existing URL in Studio
21 schema:
22 graphref: mygraph@current
23 subgraph: actors
Variable expansion
The supergraph.yaml
file supports variable expansion using the same syntax as GraphOS Router.
Output format
By default, rover supergraph compose
outputs a supergraph schema document to stdout
. You provide this artifact to @apollo/gateway
or the 🦀 GraphOS Router on startup.
You can save the schema output to a local .graphql
file like so:
1# Creates prod-schema.graphql or overwrites if it already exists
2rover 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, 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).
- Set the environment variable
APOLLO_ELV2_LICENSE=accept
in your CI environment. - Include
--elv2-license accept
in yourrover 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
Whenever you run rover supergraph compose
, Rover automatically downloads the composition library for the given federation version you specified either in your supergraph.yaml or via stdin.
The command supports both Federation 1 and Federation 2 composition. Federation 1 and Federation 2 use different composition algorithms, which are implemented in different libraries:
Federation 1:
@apollo/federation
Federation 2:
@apollo/composition
- The federation version you specify 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 specify a Federation 1 version and any of your subgraphs uses a Federation 2 schema, composition fails.
- Future versions of rover supergraph compose will fail if you don't specify an exact federation version. Include a federation version in your configuration to prevent breaking changes in future Rover versions.
Automatic updates
If you don't specify a federation_version
in supergraph.yaml
(which will be required in future versions), 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.
Apollo strongly recommends always specifying an exact federation_version
.
Preventing auto-updates
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 @apollo/federation
JavaScript package.
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 @apollo/gateway
library:
Rover version | Gateway version |
---|---|
<= v0.2.x | <= v0.38.x |
>= v0.3.x | >= v0.39.x |