Skip to content

Latest commit

 

History

History
192 lines (132 loc) · 8.5 KB

supergraphs.mdx

File metadata and controls

192 lines (132 loc) · 8.5 KB
title description
Rover supergraph commands
For use with Apollo Federation

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

graph BT;
  gateway(["Supergraph (A + B + C)"]);
  serviceA[Subgraph A];
  serviceB[Subgraph B];
  serviceC[Subgraph C];
  gateway --- serviceA & serviceB & serviceC;
Loading

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

Fetching a supergraph schema from Apollo Studio

supergraph fetch

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.

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.

You can omit @ 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:

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 (films and people):

federation_version: 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 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:

federation_version: 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
    schema:
      subgraph_url: https://example.com/people

  # Apollo Studio graph ref
  actors:
    routing_url: https://localhost:4005
    schema:
      graphref: mygraph@current
      subgraph: actors

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 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 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, 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=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. It determines which version to use according to the following logic:

flowchart TB;
  version("Is the <code>federation_version</code> key<br/>present in <code>supergraph.yaml</code>?");
  version--No-->optin("Does <strong>at least one</strong> subgraph schema<br/>opt in to Federation 2?");
  version--Yes-->usesetting("Use the version specified<br/>by <code>federation_version</code>");
  optin--No-->fed1("Use Federation 1<br/>composition");
  optin--Yes-->fed2("Use Federation 2<br/>composition");
  class usesetting,fed1,fed2 tertiary;
Loading

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

Here's an example supergraph.yaml file that specifies Federation 1 composition:

federation_version: 1
subgraphs:
  films:
    routing_url: https://films.example.com
    schema:
      file: ./films.graphql

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

Updating composition libraries

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

Whenever you run rover supergraph compose, Rover automatically downloads the latest version of the library for your selected composition version (if there's an update).

Any updates to a given composition version should always be backward compatible. If composition unexpectedly breaks following an update, please submit an issue and see Pinning composition to a library version.

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

Pinning composition to a library version

⚠️ You should do this only if composition unexpectedly breaks between calls to rover supergraph compose as an attempt to debug the issue.

You can pin your composition algorithm to a particular version of its library via the federation_version key in your supergraph.yaml file:

federation_version: =2.0.1

In the above example, Rover uses exactly version 2.0.1 of the @apollo/composition library for Federation 2 composition.

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