Cosmo Cloud Onboarding - WunderGraph

Getting Started

Welcome to the WunderGraph Cosmo Cloud onboarding tutorial! This guide will walk you through the process of deploying your first federated graph and integrating it with your Cosmo Router. By the end of this tutorial, you’ll have a fully functional federated graph running locally and connected to the Cosmo platform.

Prerequisites

Prepare your Organization

After signing up, a personal organization is automatically created for you. You can use this for the demo, but we recommend creating a separate organization once you complete the tutorial. To do this, open the organization dropdown, select “Create a new organization”, and choose a relevant name and slug for your new organization.

Install the CLI

Install the CLI to interact with the control plane and manage resources like graphs and API keys:

npm install -g wgc@latest

Log in with:

wgc auth login

This opens your browser and prompts you to sign into your Cosmo account. Once logged in, you’ll receive a terminal prompt to select your organization. After logging in, verify your session and ensure you’re in the correct organization by running:

wgc auth whoami

Create the Demo

Create a Namespace

A namespace helps separate resources and prevents unintended modifications between environments. Namespaces can also be used to create isolated environments for better organization and management. To create a development namespace, run:

wgc namespace create development

Create a Federated Graph

A federated graph represents your unified, federated GraphQL schema. Each federated graph is assigned a URL and can be mapped to a single router instance. For this demo, you’ll point to a demo router. The URL doesn’t need to be valid for the demo, but in a production environment, you would specify the URL of your deployed router. Run the following command to create a federated graph:

wgc federated-graph create demo \
    --namespace development \
    --routing-url https://demo-router.fly.dev/graphql

The CLI documentation provides detailed explanations of the parameters. If necessary, the parameters can be changed later.

Create Subgraphs

A federated graph requires subgraphs to function. Without subgraphs, it cannot serve a valid GraphQL schema. For this demo, you’ll use pre-deployed demo subgraphs on a serverless platform. Follow the order below to ensure proper configuration:

  1. Create the subgraph:
wgc subgraph create products \
    --namespace development \
    --routing-url https://product-api.fly.dev/graphql
  1. Download the schema and publish it:
curl -O https://raw.githubusercontent.com/wundergraph/cosmo/refs/heads/main/demo/pkg/subgraphs/products/subgraph/schema.graphqls \
&& wgc subgraph publish products \
    --namespace development \
    --schema ./schema.graphqls
  1. Create the subgraph:
wgc subgraph create employees \
    --namespace development \
    --routing-url https://employees-api.fly.dev/graphql
  1. Download the schema and publish it:
curl -O https://raw.githubusercontent.com/wundergraph/cosmo/refs/heads/main/demo/pkg/subgraphs/employees/subgraph/schema.graphqls \
&& wgc subgraph publish employees \
--namespace development \
--schema ./schema.graphqls
  1. Create the subgraph:
wgc subgraph create mood \
    --namespace development \
    --routing-url https://mood-api.fly.dev/graphql
  1. Download the schema and publish it:
curl -O https://raw.githubusercontent.com/wundergraph/cosmo/refs/heads/main/demo/pkg/subgraphs/mood/subgraph/schema.graphqls \
&& wgc subgraph publish mood \
    --namespace development \
    --schema ./schema.graphqls
  1. Create the subgraph:
wgc subgraph create availability \
    --namespace development \
       --routing-url https://availability-api.fly.dev/graphql
  1. Download the schema and publish it:
curl -O https://raw.githubusercontent.com/wundergraph/cosmo/refs/heads/main/demo/pkg/subgraphs/availability/subgraph/schema.graphqls \
&& wgc subgraph publish availability \
     --namespace development \
     --schema ./schema.graphqls

Your graph has been successfully composed and is now ready to be retrieved by the router. To verify, open the Cosmo Overview page for your graph.

Create a Router Token

After publishing all subgraphs, you need to generate a Router Token. This token allows the router to communicate with the control plane and fetch the latest valid graph composition. Run the following command to create a router token:

wgc router token create myName \
    --graph-name demo \
    --namespace development

Successfully created token myName for graph demo

<tokenhere>

Run the Router

Finally, go to the Overview page of your federated graph in Cosmo Cloud and click “Run Router Locally” to copy the command needed to start the router. Make sure to replace <graph-api-token> with the token you copied set in the previous step.

Alternatively, you can use the following command:

docker run \
  --name cosmo-router \
  --rm \
  -p 3002:3002 \
  --add-host=host.docker.internal:host-gateway \
  --pull always \
  -e DEV_MODE=true \
  -e LISTEN_ADDR=0.0.0.0:3002 \
  -e GRAPH_API_TOKEN="<graph-api-token>" \
  ghcr.io/wundergraph/cosmo/router:latest

Open the Playground

Open http://localhost:3002 and run your first GraphQL operation with WunderGraph Cosmo! The same playground is also available on Cosmo Cloud.

Example Query that involves all subgraphs

query myEmployees {
  employees {
    id
    products
    role {
      departments
    }
    details {
      forename
    }
    isAvailable
    currentMood
  }
}

Bonus

After executing the Example Query, use the dropdown on the right to see how the router processed the request and distributed it across subgraphs. Inspect the generated query plan to understand execution details, troubleshoot issues during development, and ensure optimal performance in production. If you want to learn more about it, please take a look at ART and Query Plans.

Prevent breaking changes

Each time you interact with the router, schema usage data is collected and centralized on our platform. This data helps you manage federation at scale and, more importantly, identify potential impacts on your customers before making changes. To integrate this into your workflow, use the check command to assess the impact of any schema modifications.

  1. Download the schema of the Employees subgraph

Run the following command to download the schema:

curl -O https://raw.githubusercontent.com/wundergraph/cosmo/refs/heads/main/demo/pkg/subgraphs/employees/subgraph/schema.graphqls
  1. Locate and open the schema file

By default, the file is saved in your current working directory. Verify its location with:

ls -l schema.graphqls

If you need to search for the file, use:

find ~ -name "schema.graphqls"
  1. Modify the Schema and Run the Check Command

Remove the OPERATIONS enum value from the schema:

enum Department {
  ENGINEERING
  MARKETING
  # OPERATIONS
}

Run the check command:

wgc subgraph check employees \
    --namespace development \
    --schema ./schema.graphqls
  1. Breaking change detected with client usage

You should see an output similar to the following. The change is flagged as breaking because the departments field was queried in an example query, meaning its removal would impact existing clients.

❯ wgc subgraph check employees \
    --namespace development \
    --schema ./schema.graphqls

Checking the proposed schema
⚠ Compared 1 breaking change's impacting 1 operations.
Found client activity between 10/22/2024, 2:00:00 AM and 10/22/2024, 2:00:00 AM

Detected the following changes:
┌────────────┬────────────────────┬────────────────────────────────────────────────────────────┐
│ CHANGE     │ TYPE               │ DESCRIPTION                                                │
├────────────┼────────────────────┼────────────────────────────────────────────────────────────┤
│ ✖ BREAKING │ ENUM_VALUE_REMOVED │ Enum value 'OPERATIONS' was removed from enum 'Department' │
└────────────┴────────────────────┴────────────────────────────────────────────────────────────┘

✖ Schema check failed. This check has encountered 1 breaking change's that would break operations from existing client traffic.
See https://cosmo-docs.wundergraph.com/studio/schema-checks for more information on resolving operation check errors.
Open in studio: https://cosmo.wundergraph.com/.....
  1. Release your changes

Once you’re confident about the impact of your changes, publish them to automatically update your router fleet:

wgc subgraph publish employees \
    --namespace development \
    --schema ./schema.graphqls

Clean up

To remove all resources, delete the namespace with:

wgc namespace delete -f development

Summary

In this tutorial, you learned how to run a router with a functional federated graph consisting of four subgraphs and safely release production changes. Now is the perfect time to visit your Dashboard to gain insights into your usage.