Rover supergraph Commands

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.

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.

To preview how Rover resolves these references, use supergraph config expand.

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

The supergraph plugin

Composition runs in the ELv2-licensed supergraph plugin (built from the federation-rs source). If the plugin isn't installed, rover supergraph compose downloads it and prints a warning that a future version of Rover will stop downloading plugins automatically. To avoid the download and the warning, install the plugin ahead of time, for example in your CI setup, with the rover plugin install command:

1rover plugin install supergraph@=2.9.3 --elv2-license accept

When the command downloads the plugin, it warns:

1Warning: Rover downloaded the `supergraph` plugin v2.9.3 because `APOLLO_ROVER_ALLOW_AUTOMATIC_DOWNLOAD` isn't set. A future version of Rover will not install plugins automatically. Install plugins ahead of time with `rover plugin install supergraph@=2.9.3`, or set `APOLLO_ROVER_ALLOW_AUTOMATIC_DOWNLOAD` to `true` to keep downloading them or `false` to stop now.

To keep downloading without the warning, or to stop downloading, set APOLLO_ROVER_ALLOW_AUTOMATIC_DOWNLOAD. For details, see Automatic downloads.

Rover looks for the plugin in the project's .rover/bin/ directory first, then in the global $APOLLO_HOME/.rover/bin/ directory (by default, ~/.rover/bin/). See Where plugins are installed.

Each run reports the plugin it used on stderr:

1Using the `supergraph` plugin v2.9.3 (already installed).

The line ends with (downloaded) when Rover downloaded the plugin during the run. With --format json, the same facts appear under data.plugins, with each plugin's name, version, source, level, and path. For details, see Output.

Setting a composition version

Rover composes with the federation version from the first of these that's set:

1. The --federation-version option

2. federation_version in your supergraph.yaml

3. The supergraph version declared in rover.yaml, in the project or globally

When supergraph.yaml and rover.yaml both set a version and they disagree, Rover uses supergraph.yaml and warns:

1warning: `supergraph.yaml` sets `federation_version: =2.9.3`, overriding the `supergraph` version declared in `rover.yaml`.

The command composes with Federation 2, provided by the @apollo/composition library.

Automatic updates

Unless you've turned automatic downloads off, when you don't specify an exact federation_version, Rover asks the Apollo plugin registry at https://rover.apollo.dev (or the host set by APOLLO_ROVER_DOWNLOAD_HOST) for the latest matching composition version each time it runs, so you pick up a new release as soon as it's available.

With automatic downloads turned off, a floating version such as 2 uses the newest matching release that's already installed.

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

To make sure Rover never downloads a plugin or contacts the plugin registry, for example on a slow or nonexistent network connection, pass the --skip-update flag to rover supergraph compose, or set the APOLLO_ROVER_SKIP_UPDATE environment variable to 1 or true. This applies even when APOLLO_ROVER_ALLOW_AUTOMATIC_DOWNLOAD is true.

Under --skip-update, Rover uses the version from supergraph.yaml or rover.yaml as usual, and uses the newest installed release that matches it. If none is installed, the command fails with E058, naming the directories it searched:

1error[E058]: Error when updating Federation Version
2
3Caused by:
4    0: Couldn't obtain the `supergraph` plugin
5    1: Rover needs the `supergraph` plugin v2.9.3, but it isn't installed in `/work/app/.rover/bin` or `/home/me/.rover/bin` and downloads are disabled by `--skip-update`.
6        Run `rover plugin install supergraph@=2.9.3` to install it ahead of time, or re-run without `--skip-update` to let Rover download it.

Configuration awareness in your text editor

supergraph config schema

You can use Rover to generate a JSON schema for config validation in your text editor. This schema helps you format the YAML file correctly and also provides content assist.

Generate the schema with the following command:

1rover supergraph config schema

After you generate the schema, configure your text editor. Here are the instructions for some commonly used editors:

• Visual Studio Code

• Emacs

• IntelliJ

• Sublime

• Vim

Expanding a configuration

supergraph config expand

Your supergraph.yaml file can include variable references such as ${env.PRODUCTS_URL} and ${file.path}. To see how Rover resolves these references—without running composition—use supergraph config expand:

1rover supergraph config expand --config ./supergraph.yaml

Rover prints the configuration with every reference expanded. This is useful for confirming that the correct environment variables and files are picked up before you compose. Pass - to --config to read the configuration from stdin instead of a file.

By default the expanded configuration is printed as YAML. For example, given this supergraph.yaml, with PRODUCTS_ROUTING_URL set to https://products.example.com and PRODUCTS_AUTH_TOKEN unset:

1federation_version: =2.9.0
2subgraphs:
3  products:
4    routing_url: ${env.PRODUCTS_ROUTING_URL}
5    schema:
6      subgraph_url: ${env.PRODUCTS_ROUTING_URL}
7      introspection_headers:
8        Authorization: ${env.PRODUCTS_AUTH_TOKEN:-default-token}
9  users:
10    routing_url: http://localhost:4002
11    schema:
12      file: ./users.graphql

Rover prints:

federation_version: =2.9.0
subgraphs:
  products:
    routing_url: https://products.example.com
    schema:
      subgraph_url: https://products.example.com
      introspection_headers:
        Authorization: default-token
  users:
    routing_url: http://localhost:4002
    schema:
      file: ./users.graphql

Add --format json to receive the same YAML, as a single string, in the expanded_config field of data instead:

1{
2  "json_version": "1",
3  "data": {
4    "expanded_config": "federation_version: =2.9.0\nsubgraphs:\n  products:\n    routing_url: https://products.example.com\n    schema:\n      subgraph_url: https://products.example.com\n      introspection_headers:\n        Authorization: default-token\n  users:\n    routing_url: http://localhost:4002\n    schema:\n      file: ./users.graphql\n",
5    "success": true
6  },
7  "error": null
8}