Federation v1 and v2 Support in Cosmo - WunderGraph
Run Federation v1 and v2 with Cosmo Router
Cosmo Router supports Federation v1 and v2 out of the box. Run mixed environments, migrate gradually, or start fresh with v2 while maintaining a unified graph strategy.
The problem
Incompatible federation tooling creates fragmentation and slows migration
Teams should be able to support existing v1 schemas while adopting v2 features gradually.
Incompatible tooling blocks a unified API strategy
Organizations with existing v1 schemas cannot always migrate immediately, while new projects may need v2 features. If tooling cannot support both versions, teams can end up with fragmented graphs instead of one unified API strategy.
Migration can become a complex project
Without support for both versions, moving from Federation v1 to v2 can require a complex migration project before teams can adopt v2 features broadly.
Federation overhead creates performance concerns
Federation can introduce performance concerns from query planning overhead. Teams need a router and query planner designed for high-throughput federation scenarios.
Our solution
One router for Federation v1 and v2
Cosmo Router supports Federation v1 and v2 simultaneously. Teams can migrate at their own pace, adopt v2 features for new services, and continue running existing v1 subgraphs in one federated graph.
How it works end-to-end
- Subgraph teams can define schemas using Federation v1 or v2 directives.
- Cosmo supports mixed Federation v1 and v2 subgraphs in the same federated graph, including directive compatibility across both versions.
- The Router fetches the latest valid router configuration from the CDN and periodically checks for updates.
- The Router creates a cached query planner that serves requests across v1 and v2 subgraphs through one unified API.
- When router configuration updates are available, the router reconfigures its engine on the fly for zero-downtime schema updates.
GraphQL Federation
Before & After
| Before Cosmo | With Cosmo |
|---|---|
| Forced to choose v1 or v2 exclusively | Run both versions simultaneously |
| Complex migration projects required | Gradual migration at your own pace |
| Limited directive support | Full directive compatibility for Federation v1 and v2 |
| Performance concerns with federation overhead | Highly-optimized Go-based query planner |
Directive support
Federation v1 and v2 directives supported
Federation v1
@extends@external@key@provides@requires@tag
Federation v2
@inaccessible@override@shareable@authenticated@requiresScopes@interfaceObject
Full reference in the directives index and compatibility matrix.
Key benefits
Why teams choose Cosmo for federation
- Full protocol compatibility: Compatibility with all Federation v1 directives (@extends, @external, @key, @provides, @requires, @tag) and Federation v2 directives (@inaccessible, @override, @shareable, @authenticated, @requiresScopes, @interfaceObject).
- Zero vendor lock-in: The Cosmo Router is Apache 2.0 licensed, with full code transparency and no vendor dependency.
- Enterprise performance: Built in Go on graphql-go-tools, a mature GraphQL engine. The router creates a highly optimized query planner that is cached across requests for performance.
- Mixed version support: Run Federation v1 and v2 subgraphs together in the same federated graph. Teams can use the federation version that matches their expertise while maintaining one unified API for consumers.
- Future-ready: Cosmo continuously updates to support new federation specifications as they emerge. Teams can start with existing v1 schemas, adopt v2 features for new services, and migrate gradually.
Use cases
Where teams use Cosmo v1 and v2 federation support
- Gradual migration: A company has existing Federation v1 subgraphs and wants to adopt v2 features for new services without disrupting existing infrastructure.
- Greenfield deployment: A team building a new microservices architecture can use Federation v2 features from day one.
- Multi-team schema ownership: Different teams own different subgraphs and have varying levels of GraphQL expertise.
Good fit when
- You have existing Federation v1 subgraphs and want to adopt v2 features for new services.
- You are building a new federated graph with full v2 feature support.
- Multiple teams own subgraphs and need flexibility to use the federation version that matches their expertise.
Requirements
- Cosmo Control Plane access - use Cosmo Cloud or a self-hosted control plane.
- Federation v1 or v2 subgraphs - your subgraphs must implement Federation v1 or v2 protocols.
- Router deployment infrastructure - Docker, Kubernetes, or another supported deployment environment.
Start running Federation v1 and v2 together
Apache 2.0 licensed router. Go-based GraphQL engine. Full directive compatibility. Gradual migration at your own pace. Review Federation compatibility or migrate from Apollo GraphOS.
Dive deeper
- Router introduction
- Federation compatibility matrix
- Federation directives index
- Router configuration options
FAQ
- What is GraphQL Federation?
- What is the difference between Federation v1 and v2?
- Can I run v1 and v2 subgraphs in the same graph?
- What license is the Cosmo Router under?
- Is the router self-hostable?
- How does the router handle zero-downtime updates?
- What is graphql-go-tools?