Cosmo Cloud Onboarding
Learn how to deploy your first federated graph and integrate it with your Cosmo Router.
Last updated
Was this helpful?
Learn how to deploy your first federated graph and integrate it with your Cosmo Router.
Last updated
Was this helpful?
Head over to cosmo.wundergraph.com and create an account. Once you are in, your are on the Developer Plan with 10 million requests for free.
Create an account at https://cosmo.wundergraph.com/login
You need to have Node.js LTS (or higher), npm, and docker installed.
Curl is needed to download files.
After a successful signup, a personal organization is automatically created for you. This organization can be used to run the demo. However, based on your requirements, we recommend creating a separate organization after completing this tutorial. To do so, click on the organization dropdown and select "Create a new Organization." Be sure to choose an appropriate name and slug for your new organization.
Run the following command to install our CLI. The CLI enables interaction with the control plane to create and manage resources such as graphs and API keys.
Log-in with the following command.
This will open your browser, and you are instructed to log into your Cosmo account. Once logged in, you get a prompt in your terminal to select your organization.
After successful login you should be able to run the command to verify if you are logged in to the right organization.
For clear separation of concerns, we create a new namespace. Namespaces are an effective tool for creating isolated environments. A namespace is a physical container that separates resources, preventing accidental modification of resources between environments.
The next step is to create a federated graph that represents your unified, federated GraphQL schema. A federated graph is assigned a URL and can be logically mapped to a single router instance. For this demo, we will point to our demo router. It is not important for the demo to point to a valid URL but in a production environment, you would need to specify here the URL of your deployed router.
I refer to the CLI documentation to explain the parameters in detail but they should be very self-descriptive. Don't worry all parameters can be changed later.
A federated graph without any subgraph is not functional. Let's create a few subgraphs to build a valid and accessible GraphQL schema. For simplicity, we will use demo subgraphs, which have been deployed on a serverless platform. Please create the subgraphs from left to right, we start with the Products subgraph.
Create the subgraph:
Download the schema and publish it:
After publishing all subgraphs, we have to issue a Router token that gives the router permission to communicate with the controlplane and to download the latest valid Graph composition. Please run the following command:
Finally, go to the Overview page of your federated graph in Cosmo Cloud and click on "Run Router locally" to copy the second command to run the Router locally.
Ensure that you have replaced <graph-api-token>
with your token, which was generated in a previous step.
Alternatively, you can use the following command:
Open http://localhost:3002/graphql and run your first GraphQL operation with WunderGraph Cosmo! 🚀 The same playground is also available on Cosmo Cloud.
After executing the Example Query, use the dropdown on the right to review how the query was executed on the router and examine the generated query plan. This provides you with the necessary tools to investigate issues of any kind, both during development and, more importantly, in production.
If you want to learn more about it, please take a look at ART and Query Plans.
Each time you perform an operation against the router, we collect schema usage data. This data is centralized on our platform, providing you with the necessary tools to manage federation at scale. One of the most critical features is the ability to understand when your customers may be impacted by schema changes. To make this process part of your workflow, we provide a check command to understand the impact of a potential change. Based on the demo above, please run the following commands.
You should see a similar output as follows. We have identified the change as a breaking change, and since the departments
field was queried in the example query, it was correctly identified as being in use as well.
Click on the link next to Open in studio
to see the check in Cosmo Studio!
You can delete all resources by deleting the namespace with the following command:
In this tutorial, you have learned how to run your router with a functional federated graph consisting of four subgraphs, and how to safely release changes to production. I hope you enjoyed it. Now, it's the perfect moment to visit your Dashboard to get meaningful insights into your usage.