Cosmo OSS Schema Registry Compatibility Mode for Apollo Router and Gateway

At the heart of GraphQL Federation is the schema registry, which is responsible for storing all Subgraphs and their schemas, validating and composing them into a single schema, and serving the composed schema to the Gateway.

Some of our users are already using Apollo GraphOS with Apollo Router or Gateway, and they asked us for a seamless way to transition from Apollo's schema registry to Cosmo. Ideally, they want to keep their existing Apollo Router and Gateway setup for a while, switch to the Cosmo schema registry, and then gradually migrate to the Cosmo Router.

To make this transition as smooth as possible, we're introducing the Cosmo Compatibility Mode for Apollo Router and Gateway.

Cosmo Compatibility Mode for Apollo Router and Gateway is a feature that allows you to switch from Apollo GraphOS (closed source) to the Cosmo schema registry (open source) without changing your existing Apollo Router or Gateway setup.

Cosmo Compatibility Mode is 100% compatible with Apollo Federation and works seamlessly with Apollo Router and Gateway. It allows you to use Cosmo as the schema registry for your Apollo Router and Gateway setup without any changes to your existing configuration.

Here's an overview of how Cosmo Compatibility Mode works:

Let's break down how Cosmo Compatibility Mode works:

1. Publish your Subgraphs to Cosmo using the Cosmo CLI (wgc)
2. Configure a WebHook in Cosmo to trigger a service or build pipeline when a new Supergraph composition is available
3. Use wgc federated-graph fetch <graph-name> --apollo-compatibility to fetch the Supergraph and generate all the necessary files to run Apollo Composition
4. Run the generated apollo.sh script to generate a Supergraph Schema configuration file for Apollo Router or Gateway
5. Update the Apollo Router or Gateway configuration to use the generated Supergraph Schema configuration file

The Cosmo Schema Registry retains all Apollo-related directives such as @link so that Rover can generate a valid Supergraph Schema configuration file for Apollo Router or Gateway.

Let's talk about a migration strategy leveraging Compatibility Mode to move from Apollo GraphOS with Apollo Gateway or Router to Cosmo.

At the beginning of the migration, you have Apollo GraphOS with Apollo Gateway or Router running in production. You have a set of Subgraphs published to Apollo GraphOS and a Gateway/Router that's using Apollo GraphOS as the schema registry.

Next, you create and publish all Subgraphs to Cosmo using the Cosmo CLI (wgc). Once all Subgraphs are published to Cosmo, you can create a Federated Graph and set up CI for your existing repositories to not just publish to Apollo GraphOS but also to Cosmo.

At this stage, you have your existing production setup running with Apollo GraphOS, while keeping the Cosmo Schema registry up-to-date with your Subgraphs. You're running composition twice in the CI pipeline, once for Apollo GraphOS and once for Cosmo, which takes a little bit longer but ensures that both registries are in sync.

Once this setup is running smoothly, you can implement a WebHook in Cosmo to trigger a service or build pipeline when a new Supergraph is composed in Cosmo. This pipeline will use the wgc federated-graph fetch <graph-name> --apollo-compatibility command to fetch the Supergraph and generate all the necessary files to run Apollo Composition. The artifacts generated by this command can be used to update the Apollo Router or Gateway configuration.

Finally, you update the Apollo Router or Gateway configuration and deployment scripts to use the generated Supergraph Schema configuration file from using the Cosmo Compatibility Mode.

Once you've updated the configuration and deployment scripts, your Apollo Router or Gateway setup now runs completely independent of Apollo GraphOS and only uses Cosmo as the schema registry.

At this point, you can start migrating custom configuration, middleware, or plugins from Apollo Router or Gateway to Cosmo Router. Once you've migrated all configurations and plugins, you can stand up a Cosmo Router Cluster side-by-side with your Apollo Router or Gateway setup and start routing traffic to the newly deployed cluster. If you'd like to be extra cautious, you can do this process in a staging environment first, and use a canary deployment strategy for the production environment to gradually move traffic to the Cosmo Router.

Once you've successfully migrated all traffic to the Cosmo Router, you can keep the Apollo Router or Gateway setup running for a while, just in case something unexpected happens and you need to roll back to the old setup.

In the last step, you can shut down the Apollo Router or Gateway setup and remove all references to Apollo GraphOS from your codebase. You can remove the CI pipeline steps that previously published to Apollo GraphOS.

We've prepared extensive documentation for this new feature. Please take a look at the complete tutorial to learn more about how to use this feature.

In addition, we've created a full example including configuration and setup for Apollo Router and Gateway, which you can find on GitHub .

In this blog post, we introduced the Cosmo Compatibility Mode for Apollo Router and Gateway. You've learned how to use this feature to migrate from Apollo GraphOS to Cosmo without changing your existing Apollo Router or Gateway setup.

The Cosmo Compatibility Mode is 100% compatible with Apollo Federation and can be used in multiple stages to gradually migrate from Apollo GraphOS to Cosmo. In case you're not intending to do a full migration to Cosmo Router right away, you can use this feature to switch to Cosmo as the schema registry for your Apollo Router or Gateway setup. This allows you to gradually move away from a closed-source solution.