Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Updating Your Graph Safely

Upgrade your components in the recommended order to avoid errors


Your consists of multiple components that are each versioned independently:

Your infrastructure
GraphOS
Subgraph A
Subgraph B
GraphOS Router
🛠
Build
pipeline

  • The GraphOS Router is based on a version of the .
    • This is true for all supergraph types (cloud and self-hosted).
  • The GraphOS build pipeline uses a particular version of to compose your 's .
    • If you use the 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 that were first introduced in a particular version of Apollo Federation.

These components each target support for a particular version of Apollo Federation, the architecture that underpins every supergraph. Because of this, it's important to make sure these various Federation versions remain compatible with each other as you make updates to individual components.

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

NOTE

( fed. version) ≥ (Build Pipeline fed. version) ≥ ( fed. version)

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

1. Router
2. Build Pipeline
3. Subgraph Schemas

1. Update your router

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

For details on each router version's corresponding Apollo Federation version, see this article.

2. Update your build pipeline

Whenever you make an operational change to your (such as publishing changes to a subgraph schema), GraphOS initiates a build that composes your graph's new supergraph schema. From GraphOS Studio, you can configure which version of Apollo Federation the build pipeline uses to perform this composition.

NOTE

GraphOS enables you to choose between minor versions of Federation (such as 2.1). Each option automatically uses the latest supported patch release of that minor version (such as 2.1.4).

Although patch release updates are automatic, you must manually move a graph's build pipeline to a different minor release.

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

  2. Click Upgrade.

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

GraphOS immediately initiates a new build using the selected Federation version. All future builds also use the selected version. Successful build completion triggers a that delivers an updated schema to your router.

Composing with the Rover CLI

If you host your own instance, you can use the Rover CLI to compose its supergraph schema via the rover supergraph compose command.

NOTE

Performing composition with is not recommended. Instead, perform composition via the GraphOS build pipeline to help ensure a consistent process across all your graph's environments.

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
supergraph.yaml
federation_version: =2.3.2
subgraphs:
# ...

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

⚠️ CAUTION

If you don't provide a value for federation_version, Rover prints a warning and chooses a composition version according to this logic. This could potentially cause failures. Rover might use a newer composition version than what your router supports, resulting in a supergraph schema that causes the router to fail on startup.

Learn more about setting a Rover composition version.

3. Update subgraph schemas (as needed)

After both your router and your build pipeline support a particular minimum version of Apollo Federation, your can use features that were first introduced in that version.

NOTE

You don't need to update any that doesn't use newly introduced Apollo Federation features. Different subgraph schemas can target different Federation versions as needed. Ultimately, your build pipeline determines which version of composition is actually used to create the supergraph schema.

As an example, the @interfaceObject directive was first introduced in Federation 2.3. To start using this in a , do the following:

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

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

    Notice that the url 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 router and build pipeline, the next time you deploy your subgraph and publish its schema to GraphOS, every component in your supergraph will be prepared to interact with a schema that includes the @interfaceObject directive you've added.

Why is this update order necessary?

GraphOS use the Apollo Federation 2 architecture. Federation 2 is itself a versioned technology (2.2, 2.3, etc.), and each version introduces changes and additions to the set of supported subgraph directives.

  • Each version of the GraphOS 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 determines which version of Federation 2 is used to compose your supergraph schema. This composition process fails if one of your 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.

Previous
Local Subgraph Development
Next
Graph Exploration
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company