Updating your graph safely

Your supergraph consists of multiple components that are each versioned independently:

• The router is powered by a particular version of the
  Apollo Router
  .
  • This is true for all supergraph types (
    cloud
    and
    self-hosted
    ).
• The GraphOS build pipeline uses a particular version of Apollo Federation to compose your router's supergraph schema.
  • If you use the
    Rover CLI
    to compose your supergraph schema, this is true for Rover as well. In this case, you effectively maintain your own build pipeline.
• Your subgraph schemas might each use special directives that were first introduced in a particular version of Apollo Federation.

These components each target support for a particular version of

Recommended update order

To avoid runtime or composition errors, your supergraph's components should always maintain the following relationship between their targeted Apollo Federation versions:

To maintain this relationship, always update these supergraph components in order from left to right:

1. Update your router

The method you use to update your router depends on which type of supergraph you have:

• If you have a

  self-hosted supergraph
  , you
  download the latest Apollo Router binary
  in every environment where your router runs.

• If you have a

  cloud supergraph
  , GraphOS automatically updates your router to the latest supported version whenever that version changes.
  • You can see which Apollo Router version you're running from the Cloud Router section of your variant's Settings page in
    Studio
    :
  

For details on each Apollo Router version's corresponding Apollo Federation version, see

2. Update your build pipeline

Whenever you make an operational change to your graph (such as

1. Go to your variant's Settings page, then find the General > Build Configuration section.

2. Click Edit Configuration.

3. In the dialog that appears, select a Federation version from the Supergraph Pipeline Track dropdown and click Save.

GraphOS immediately initiates a new build using the selected Federation version, and all future builds also use the selected version.

Composing with the Rover CLI

If you host your own Apollo Router instance, you can use the

If you do perform composition with rover supergraph compose, the command uses the exact version of composition you specify via the federation_version key in the YAML configuration file you pass:

rover supergraph compose --config ./supergraph.yaml

1
federation_version: =2.3.2 
2
subgraphs:
3
  # ...

This value must target a specific patch release (2.3.1, 2.3.2, etc.), and it must start with an equals sign (=).

3. Update subgraph schemas (as needed)

After both your

As an example, the

1. Make sure your chosen subgraph library has added support for the @interfaceObject directive by consulting

   this table
   .
   • If your library doesn't yet support the directive, reach out to its maintainers about adding support.

2. Upgrade to the latest version of your subgraph library to make sure you're using a version that supports @interfaceObject.

3. Modify the following @link directive in your subgraph schema (or add it if it isn't present yet):

   GraphQL

   1
   extend schema
   2
     @link(
   3
       url: "https://specs.apollo.dev/federation/v2.3"
   4
       import: ["@key", "@shareable", "@interfaceObject"]
   5
     )

   Copy

   Notice that the url argument targets v2.3 of the Apollo Federation spec, and @interfaceObject is included in the import list.

4. Apply the @interfaceObject directive to relevant locations in your subgraph schema.

Because you've already updated your

Why is this update order necessary?

GraphOS supergraphs use the

• Each version of the Apollo Router is compiled against a particular version of Federation 2 (for details,

  see this table
  ). Any given router version is backward compatible with previous versions of Federation. However, it isn't compatible with newer versions.

  Therefore, it's important to update your router first, before any other supergraph component begins using a later Federation 2 version. Otherwise, you might cause your router to break by providing it a supergraph schema that it doesn't support.

• Your graph's Supergraph Pipeline Track setting in GraphOS Studio determines which version of Federation 2 is used to compose your supergraph schema. This composition process fails if one of your subgraph schemas uses a directive that was introduced in a Federation version later than your chosen pipeline track.

  • In the case of a failed build, GraphOS continues to provide your router with the supergraph schema from the most recent successful build.

• Finally, subgraph schemas are where you actually apply new Federation 2 directives. You need to update your subgraph library to a version that recognizes all directives that you use in your schema.

  You perform this update last to make sure that every other component of your supergraph is prepared to interact with any newly introduced directives.