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.
Overview
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.
Prerequisites
Node >= 18
Docker
Cosmo
wgc
CLIAccount on Cosmo Cloud (Free Trial). This makes it easier to follow the steps. (skip if you are self-hosting the whole of Cosmo)
Project setup
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. You can find it here: https://github.com/wundergraph/cosmo-demo
Install the Cosmo CLI tool
Run the following command to install the latest version of the Cosmo CLI.
Alternatively, you can use yarn.
Authenticate with the CLI
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.
Alternatively, you can log into the Cosmo Dashboard, click on API Keys, and export the generated API key using the following cmd.
We're done with the prerequisites, let's now start with the real work!
Build and Deploy Subgraphs
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 dev
in 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.
Create and Publish 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 create
and publish
.
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.
We have now registered both Subgraphs on Cosmo and published their GraphQL Schemas. We're ready to compose them into a federated Graph.
Create 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.
Our federated Graph is now composed. Let's deploy a Router to wire it all together.
Configure and Deploy your Router
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).
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.
Setup CI/CD with schema checks
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, subgraph check
and subgraph publish
.
You can use the following convention.
Run
subgraph check
on pull requests to prevent merging breaking changes into your main branch.Run
subgraph publish
on push/merge to main
Example GitHub workflows to achieve the above are provided in the demo project under the .github
directory.
The overall picture
All Done!
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.
Last updated