Moving to Apollo Federation 2
⚠️ Until Federation 2 is generally available, do not move business-critical graphs to Federation 2. Learn about release stages.
This article describes how to move an existing federated graph to Apollo Federation 2. If you haven't yet, see what's new in Federation 2.
Moving a federated graph to Apollo Federation 2 requires very few changes. Moving back to Federation 1 is more complex if you then make incompatible changes to your subgraphs, so we recommend starting with a test instance of your graph.
Update your gateway's
@apollo/gateway library to version
2.0.0-alpha.1 or later. This enables your gateway to interact with supergraph schemas composed with Federation 2.
You can install the latest alpha gateway with the following command:
npm install @apollo/gateway@latest-2
These updated versions of
@apollo/gateway continue to support Federation 1, so you can deploy this update without breaking your existing graph.
Federation 2 uses more flexible rules for schema composition. Moving to Federation 2 primarily involves switching to use this logic. Follow the instructions for your current composition method:
If you perform composition with the Rover CLI, do the following:
Install the latest version of Rover using the appropriate command for your system:
⚠️ If you already have Rover globally installed and you installed it with
npm, first uninstall that version with
# MacOS / Unix-like curl -sSL https://rover.apollo.dev/nix/latest | sh
# Windows iwr 'https://rover.apollo.dev/win/latest' | iex
Install the Federation 2 plugin for Rover using the appropriate command for your system:
# MacOS / Unix-like curl https://rover.apollo.dev/plugins/rover-fed2/nix/latest | sh
# Windows iwr https://rover.apollo.dev/plugins/rover-fed2/win/latest | iex
⚠️ During the Federation 2 alpha, your installed versions of Rover and its Federation 2 plugin must be identical. If you encounter an error when using the plugin, try updating both binaries to their latest version.
That's it! You can now use the Federation 2 version of Rover's
supergraph compose command anywhere you currently perform composition:
rover fed2 supergraph compose --config ./supergraph.yaml
This command's requirements, options, and output format are all identical to those of
supergraph compose. It just uses Federation 2 composition logic instead of Federation 1.
If you're using managed federation, you move individual variants of your graph to Federation 2 in the Apollo Studio UI.
Open your graph's Settings page and find the Manage Variants section:
Click Edit Build Configuration for the variant you want to move to Federation 2. The following dialog appears:
In the Federation Version dropdown, select Federation 2 and click Save.
Studio automatically begins composing your supergraph schema using Federation 2 composition logic. Your updated managed gateway automatically fetches the updated schema when it next polls Apollo:
Congratulations, your federated graph is now using Federation 2! The natural next question is, "What does this change about my graph's behavior?" And at this point, the answer is: nothing!
Currently, your subgraph schemas are probably fully compatible with both Federation 1 and 2. You could switch back and forth between Federation 1 and Federation 2, and everything would work as expected.
If your graph does not successfully compose with Federation 2, see Breaking changes for the most common causes.
To get the most out of Federation 2, you modify your subgraph schemas to take advantage of flexible composition rules that help your teams work independently.