.svg?alt=media&token=06f1bc51-8b97-4fc6-8caf-fdd3a8cd9ec8)
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 monitor federated GraphQL APIs. It facilitates collaboration across teams with robust CI workflows, breaking change detection, and schema change notifications.
Follow the five steps below to get from zero to managed Federation.
Prerequisites
Node >= 18
Account 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 includes all the reference code you need. It features two subgraphs (Posts and Users), a Router, and a CI/CD setup 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.
If you prefer Yarn over npm, use the following command instead:
Authenticate with the CLI
We need to ensure that the CLI can communicate with the Cosmo Control Plane so that we can publish and compose the subgraphs.
Run the following command in your terminal.
After logging in, you can use the arrow keys to select your organization in your terminal.
Alternatively, you can log into the Cosmo Dashboard, click on API Keys, and export the generated API key using the following command.
Now that you're done with the prerequisites let's 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 expose the Subgraphs to the public. 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 can communicate with the Subgraphs over the network.
For the sake of this guide's simplicity, we assume that you make the "Posts" Subgraph accessible at the URL `https://posts.domain.com` and the "Users" Subgraph accessible at the URL `https://users.domain.com`.
To help you get started quickly, we have prepared two compatible subgraphs in the Demo Project. You can either use these and follow along step by step or create your own subgraphs while mimicking the rest of the setup.
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 them locally, but you’ll need two terminal windows—one for each subgraph.
First, open two terminal windows.
You will navigate to a different subgraph in each terminal and ensure the dependencies are installed.
In Terminal 1, navigate to the Posts subgraph and install dependencies:
In Terminal 2, navigate to the Users subgraph and install dependencies:
You will only need to install the dependencies once. Once they are installed, you’re ready to start the subgraphs.
Use the same two terminals to start the subgraphs. In each terminal, navigate to the corresponding subgraph and run:
This command allows you to run the subgraphs locally in each directory.
Additionally, each subgraph includes a Dockerfile for quick deployment to a platform of your choice.
Here are the schemas for the subgraphs:
Create and Publish Subgraphs
Once you have deployed the subgraphs, the next step is to register them on Cosmo and publish their GraphQL schemas to the Registry. This process is as simple as running two commands: create and publish.
Cosmo also uses labels, which allows you to assign each subgraph with one or more labels. The labels help federated graphs dynamically select the appropriate subgraphs for composition, offering teams greater flexibility in structuring their graphs.
Here is an example using the demo project. These commands need to be run in the project's root directory.
After you run this command, you should see a confirmation message in the terminal
If you’d like to confirm that your subgraphs have been successfully created and published, go to the Cosmo Dashboard and select Subgraphs from the menu. You should see a list of all registered subgraphs, their routing URLs, labels, and the last published time.
Now that both subgraphs have been registered on Cosmo and their GraphQL schemas have been published, 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, which we use 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.
After you run this command, you will see a confirmation message in the terminal.
To verify that your federated graph was successfully created, navigate to the Studio Overview in the Cosmo Dashboard. This page displays key details such as the number of subgraphs, composition status, schema validation, and the router URL. If everything is set up correctly, you should see a successful schema check and a router URL ready to fetch data from the subgraphs.
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 checkon pull requests to prevent merging breaking changes into your main branch.Run
subgraph publishon 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
Was this helpful?
