Cosmo OSS Schema Registry Compatibility Mode for Apollo Router and Gateway - WunderGraph

Jens Neuse
CEO & Co-Founder at WunderGraph
April 24, 2024·6min read
Edited on July 9, 2026 by Brendan Bondurant

State of GraphQL Federation 2026

How are teams governing schema changes, handling production traffic, and measuring Federation success? Share your experience and get early access to the full report. For every valid survey completed, we'll donate $30 to UNICEF.

TL;DR

Cosmo Compatibility Mode lets you use the open-source Cosmo schema registry with your existing Apollo Router or Gateway, without config changes to your runtime. You publish subgraphs to Cosmo, fetch an Apollo-compatible supergraph with wgc federated-graph fetch --apollo-compatibility, and point Apollo Router or Gateway at the generated config. It is compatible with Apollo Federation, so you can drop the metered GraphOS registry bill first and migrate to the Cosmo Router later, one step at a time.

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.

Why switch the registry but keep Apollo Router

The trigger is usually cost. Apollo's schema registry is part of GraphOS, and running a production graph on GraphOS is metered per request. As of July 2026, the Developer plan starts at $5 per million requests (Apollo pricing). The Cosmo schema registry is Apache 2.0 and self-hostable, with no per-request fee.

Compatibility Mode lets you keep Apollo Router or Gateway exactly as they are and point them at Cosmo for schema storage and composition. You drop the GraphOS registry bill without touching your runtime, then migrate to the Cosmo Router on your own schedule. If you want the fuller picture, see the open-source alternative to Apollo GraphOS.

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.

How Cosmo Compatibility Mode for Apollo Router and Gateway Works

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

Cosmo Compatibility Mode is compatible with Apollo Federation and works 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:

Cosmo Schema Registry Compatbility Mode for Apollo Gatway and Router

Let's break down how Cosmo Compatibility Mode works:

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

How to leverage Cosmo Compatibility Mode for Apollo Router and Gateway to migrate to Cosmo

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.

Full Example and Documentation for Cosmo Compatibility Mode for Apollo Router and Gateway

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.

Conclusion

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 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 source-available, non-OSI license.

Frequently Asked Questions (FAQ)

What is Cosmo Compatibility Mode for Apollo Router and Gateway?
It’s a feature that lets you use the open-source Cosmo Schema Registry with Apollo Router or Gateway without changing your existing configuration.

Is Cosmo Compatibility Mode compatible with Apollo Federation?
Yes. It is compatible with Apollo Federation and works with both Apollo Router and Gateway setups.

How do I switch from Apollo GraphOS to Cosmo using Compatibility Mode?
You can publish your Subgraphs to Cosmo, set up a WebHook for new Supergraph compositions, fetch the Supergraph using wgc federated-graph fetch --apollo-compatibility, and update Apollo Router or Gateway to use the generated configuration file.

Can I run Apollo GraphOS and Cosmo together during migration?
Yes. The blog explains that you can keep Apollo GraphOS as your production registry while keeping Cosmo synchronized, running composition for both in your CI pipeline until you’re ready to switch fully.

What happens after migrating Apollo Router or Gateway to Cosmo?
Once your Router or Gateway uses Cosmo as the schema registry, you can gradually move configuration and plugins to the Cosmo Router and eventually retire Apollo GraphOS.

Where can I find the example setup and documentation?
Full documentation and a working example are available in the official tutorial and on GitHub at the provided links in the blog.

Can I use Cosmo's schema registry without replacing Apollo Router?
Yes. Compatibility Mode lets you keep Apollo Router or Gateway and point them at the Cosmo schema registry for storage and composition. Your runtime stays the same, and you can migrate to the Cosmo Router later if you choose.

Is the Cosmo schema registry free?
Yes. The Cosmo schema registry is Apache 2.0 and self-hostable, with no per-request fee. This is what lets you drop the metered GraphOS registry bill while keeping Apollo Router or Gateway.