Comment on page
From Zero to Federation in 5 Steps using Cosmo
This guide brings you from zero to Federation in 5 Steps. Deploy and compose your Subgraphs and set up powerful CI Workflows for collaboration.
Cosmo enables teams to build, manage, and observe federated GraphQL APIs. It enables collaboration across teams through powerful CI workflows with breaking change detection and schema change notifications.
Follow the five steps below to get from zero to managed Federation.
You can clone the example project which has all the reference code that you need. It consists of 2 subgraphs namely posts and users, a Router, and the CI/CD configuration with GitHub actions.
Run the following command to install the latest version of the Cosmo CLI.
npm i -g wgc@latest
Alternatively, you can use yarn.
yarn global add wgc@latest
We need to make sure that the CLI can talk with the Cosmo Control Plane to be able to publish the Subgraphs and compose them.
Run the following command and select your organization after logging in.
wgc auth login
We're done with the prerequisites, let's now start with the real work!
The first step is for each team to build and deploy their Subgraphs. You can deploy the Subgraphs on any infra you want. It's not required to publicly expose the Subgraphs. You can make them accessible on the public internet, or keep them private in your own VPC or on-premises. In a later step, you will deploy the Cosmo Router to the same infra, so the only requirement is that the Router is able to communicate with the Subgraphs over the network.
For the sake of simplicity of this guide, we assume that you make the "Posts" Subgraph accessible on the URL `https://posts.domain.com` and the Users Subgraph on the `https://users.domain.com` URL.
To get you through this tutorial as easily as possible, we've prepared two Subgraphs for you in the Demo Project. You can use these two and follow all steps closely, or you can use your own Subgraphs and mimic the rest of the steps.
In the demo project, we have two simple Subgraphs that are compatible, meaning that they will compose into a federated Graph without errors. You can run the subgraphs locally using
npm run devin each directory. There is also a Dockerfile for each to deploy them to the platform of your choice. Here are the schemas for the subgraphs.
Once your teams have deployed their subgraphs, we now have to register them on Cosmo and publish their GraphQL Schemas to the Registry. It is as simple as running 2 commands
Note that we have the concept of labels. Each subgraph is given one or more labels which are then used by a federated graph to select the right subgraphs for composition. This gives ultimate flexibility for several teams to compose any desired graphs.
Here is an example using the demo project. Commands are run at the root of the project.
# Team A
wgc subgraph create posts --label team=A --routing-url https://posts.domain.com
wgc subgraph publish posts --schema ./subgraph-posts/schema.graphql
# Team B
wgc subgraph create users --label team=B --routing-url https://users.domain.com
wgc subgraph publish users --schema ./subgraph-users/schema.graphql
We have now registered both Subgraphs on Cosmo and published their GraphQL Schemas. We're ready to compose them into a federated Graph.
Now it is time to compose the above subgraphs. We create a federated Graph by defining label-matchers. The matchers are being used to select the Subgraphs we'd like to add to our federated Graph.
Below is the command to create a federated graph. We need to specify the labels that it needs to consider and the routing URL. The routing URL is the endpoint of the router that we will deploy in the next step.
wgc federated-graph create production --label-matcher team=A,team=B --routing-url https://graph.domain.com/graphql
Our federated Graph is now composed. Let's deploy a Router to wire it all together.
The final step before we can start querying our federated Graph is to configure and deploy the Cosmo Router. The Router is responsible for routing the requests to the correct service, aggregating the responses, and generating observability data like metrics and traces so we can understand the traffic that's flowing through our federated Graph.
The Router has to connect to the Control Plane to fetch its Configuration and update it automatically when you make changes to the federated Graph.
As the router needs to authenticate against the Control Plane to be able to fetch the correct configuration, we have to create a Router Token first. We're doing so by using wgc with the name of our composed Graph (production).
wgc router token create mytoken --graph-name production
You can run the router by executing a single Docker command. This way you can easily deploy to your own infra and expose the router using an endpoint with which your clients can query against. You can use this command to run a Router locally, or adjust it slightly to deploy a Router to your own infra, like Kubernetes, AWS Fargate or other deployment targets that allow you to run Container workloads.
docker run \
--name cosmo-router \
-p 3002:3002 \
-e FEDERATED_GRAPH_NAME=$GRAPH_NAME \
-e DEV_MODE=true \
-e LISTEN_ADDR=0.0.0.0:3002 \
-e GRAPH_API_TOKEN=$TOKEN \
Finally, we want to set up a workflow to facilitate collaboration across teams while ensuring that changes don't break our composed Graph.
The wgc CLI provides two commands to accomplish this task,
You can use the following convention.
subgraph checkon pull requests to prevent merging breaking changes into your main branch.
subgraph publishon push/merge to main
Example GitHub workflows to achieve the above are provided in the demo project under the
Congrats! You're done with the initial setup of your federated Graph infrastructure. You've deployed two subgraphs for two different teams, composed them into a federated Graph, deployed a Router, and configured the necessary CI/CD pipelines to prevent breaking changes and publish changes to the Subgraphs.
Your federated Graph is now ready to be queried through the Explorer or GraphQL Endpoint on your Router. Once you've made some requests to the Graph, you can observe the metrics and traces in Cosmo Studio.