WunderGraph Cosmo

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for WunderGraph Cosmo Router by SecureAnyCloud, and select Create.

On Basics, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80). Then choose Review + create and Create.

RG="cosmo-prod"; LOCATION="eastus"; VM_NAME="cosmo-01" IMAGE_URN="sac1647283583153:wundergraph-cosmo-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name cosmo-vnet --address-prefix 10.100.0.0/16 --subnet-name cosmo-subnet --subnet-prefix 10.100.1.0/24 az network nsg create -g "$RG" --name cosmo-nsg az network nsg rule create -g "$RG" --nsg-name cosmo-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name cosmo-nsg --name allow-http --priority 110 \
  --destination-port-ranges 80 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:wundergraph-cosmo-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name cosmo-vnet --subnet cosmo-subnet --nsg cosmo-nsg --public-ip-sku Standard

Connect to the VM over SSH as azureuser. Confirm that the router, its two demo subgraphs and nginx are running, then check the listeners:

/opt/cosmo/router --version | head -5 systemctl is-active cosmo-subgraph-products cosmo-subgraph-inventory cosmo-router nginx | paste -sd' ' - sudo ss -tlnp | grep -E ':80 |:3002|:4001|:4002' | awk '{print $1" "$4}' | sort -u

The version prints 0.333.2, and all four services report active. The listeners show nginx on 0.0.0.0:80, the router on 127.0.0.1:3002 and the two subgraphs on 127.0.0.1:4001 and 127.0.0.1:4002. The router and subgraphs are bound to the loopback interface, so the only public entry point is nginx on port 80:

Router: Version: 0.333.2 active active active active LISTEN 0.0.0.0:80 LISTEN 127.0.0.1:3002 LISTEN 127.0.0.1:4001 LISTEN 127.0.0.1:4002

The router exposes a public, unauthenticated /health liveness endpoint, served through nginx on port 80. It suits a load balancer health probe:

curl -s -o /dev/null -w 'GET /health -> HTTP %{http_code}\n' http://localhost/health
curl -s http://localhost/health; echo

This returns HTTP 200 with the body OK. The endpoint needs no authentication. The federated GraphQL endpoint, covered in the next steps, is gated separately.

An API key protects the federated /graphql endpoint. The key is generated uniquely on the first boot of each VM and written, along with the resolved public URL, to a 0600 root:root credentials file. The key is masked in this guide, but the real value is on your VM. View the file details:

sudo stat -c '%A %U:%G %n' /root/wundergraph-cosmo-credentials.txt
sudo grep -E '^COSMO_API_KEY=|^COSMO_URL=' /root/wundergraph-cosmo-credentials.txt \
  | sed -r 's/(COSMO_API_KEY)=.*/\1=<PER-VM-64-HEX-API-KEY>/'

The file is -rw------- root:root. The COSMO_API_KEY is a 64 hex character value unique to this VM. It is created by openssl rand -hex 32 on first boot, before nginx starts serving traffic. There is no default or known key in the image, and the same key gates every call to the federated endpoint.

The federated /graphql endpoint requires the per-instance API key in the X-API-Key header. Confirm that a missing or wrong key is rejected with 401, while the per-instance key is accepted with 200:

KEY=$(sudo grep '^COSMO_API_KEY=' /root/wundergraph-cosmo-credentials.txt | cut -d= -f2-) Q='{"query":"{ topProducts { id } }"}' curl -s -o /dev/null -w '/graphql (no key) -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' -d "$Q" http://localhost/graphql curl -s -o /dev/null -w '/graphql (wrong key) -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' -H 'X-API-Key: wrong' -d "$Q" http://localhost/graphql curl -s -o /dev/null -w '/graphql (real key) -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' -H "X-API-Key: $KEY" -d "$Q" http://localhost/graphql

The calls with no key and with a wrong key are rejected with 401, and the call with the real per-instance key returns 200.

This is the security model. The health probe is open, and the per-instance key gates the federated GraphQL endpoint, so the router is never left as an open, unauthenticated data gateway.

This is the point of a federation router: one query, one endpoint, and data joined from several subgraphs. The products subgraph serves the topProducts field. The inventory subgraph serves inStock and deliveryEstimate for the same products.

The router plans the query, calls both subgraphs, resolves the shared Product entity by its key and returns a single joined response:

KEY=$(sudo grep '^COSMO_API_KEY=' /root/wundergraph-cosmo-credentials.txt | cut -d= -f2-)
curl -s -X POST http://localhost/graphql \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $KEY" \
  -d '{"query":"{ topProducts { id name price inStock deliveryEstimate } }"}' \
  | python3 -m json.tool

For each product, the response joins name and price from the products subgraph with inStock and deliveryEstimate from the inventory subgraph, in a single result:

{ "data": { "topProducts": [ { "id": "1", "name": "Cosmo Router T-Shirt", "price": 24.99, "inStock": true, "deliveryEstimate": "2-3 business days" }, { "id": "2", "name": "GraphQL Federation Mug", "price": 12.5, "inStock": false, "deliveryEstimate": "3-4 weeks" }, { "id": "3", "name": "WunderGraph Cap", "price": 18, "inStock": true, "deliveryEstimate": "1-2 business days" } ] } }

Neither subgraph can answer this query on its own. The products service does not know stock levels, and the inventory service does not know names or prices. The router makes them queryable as one graph.

The demo supergraph is composed from two local subgraph schemas and a small graph config. To federate your own services, edit the graph config, point it at your subgraphs, recompose the execution config with the Cosmo CLI and restart the router:

# The graph config lists each subgraph name, routing URL and SDL file:
sudo cat /etc/cosmo/graph.yaml
# The composed execution config the router loads at startup:
sudo head -c 300 /etc/cosmo/execution-config.json; echo

To point the router at your own subgraphs, replace the routing_url and schema.file entries in /etc/cosmo/graph.yaml with your services. Install the Cosmo CLI (npm install -g wgc). Recompose with sudo wgc router compose -i /etc/cosmo/graph.yaml -o /etc/cosmo/execution-config.json, then run sudo systemctl restart cosmo-router.

The two bundled Node demo subgraphs are systemd services (cosmo-subgraph-products, cosmo-subgraph-inventory). You can disable them once you have wired in your own upstreams.

For production graphs managed across a team, connect the router to the Cosmo Cloud schema registry instead of a static file. See the WunderGraph Cosmo documentation.

From anywhere that can reach the VM on port 80, call the federated endpoint at the VM public IP with your per-instance API key. The /health check needs no credentials:

curl http://<vm-ip>/health
curl -s -X POST http://<vm-ip>/graphql \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <YOUR-PER-VM-API-KEY>' \
  -d '{"query":"{ topProducts { id name inStock } }"}'

Fetch <YOUR-PER-VM-API-KEY> from /root/wundergraph-cosmo-credentials.txt on the VM (sudo grep '^COSMO_API_KEY=' /root/wundergraph-cosmo-credentials.txt).

Distribute the key to your GraphQL clients as their gateway credential. To rotate it, edit /etc/nginx/conf.d/cosmo-apikey.conf and reload nginx.

The image serves the endpoint over plain HTTP on port 80, which suits a load balancer or private network. For production, terminate TLS in front of the router so that credentials and payloads travel encrypted. You have two options:

• Front the VM with Azure Application Gateway, a load balancer with a managed certificate, or a CDN, and forward to nginx on port 80.
• Install your own certificate. Add a TLS server block to /etc/nginx/sites-available/wundergraph-cosmo that references your certificate and key, open 443/tcp on the NSG, then run sudo systemctl reload nginx.

In both cases, point a DNS name you control at the VM public IP and use that name (and https://) for your GraphQL consumers.

• Federation router: WunderGraph Cosmo Router v0.333.2 (open source, Apache-2.0)
• Router endpoint: /graphql on loopback 127.0.0.1:3002, fronted by nginx on :80
• API front: nginx on :80 reverse proxying to 127.0.0.1:3002
• Demo subgraphs: products (127.0.0.1:4001) and inventory (127.0.0.1:4002), Apollo Federation v2, loopback only
• Execution config: static, composed at build time by the Cosmo CLI (wgc router compose), with no control plane needed
• Health endpoint: /health (public, no auth)
• API key: per instance, generated on first boot into /root/wundergraph-cosmo-credentials.txt, and required on /graphql through X-API-Key

In AWS Marketplace, find WunderGraph Cosmo Router by SecureAnyCloud. Choose Continue to Subscribe, then Continue to Configuration, then Continue to Launch.

Pick your region, the m5.large instance type, your VPC and subnet, and a security group that allows inbound 22/tcp (from your management network) and 80/tcp (from the networks that will call the GraphQL endpoint). Select your key pair and launch.

aws ec2 run-instances \
  --image-id ami-<cosmo-router-ami> \
  --instance-type m5.large \
  --key-name <key-name> \
  --security-group-ids <sg-id> \
  --subnet-id <subnet-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=cosmo-router-01}]'

On the referenced security group, open 22/tcp to your management network and 80/tcp to your GraphQL clients.

Connect to the instance over SSH as ubuntu. Confirm that the router, its two demo subgraphs and nginx are running, then check the listeners:

/opt/cosmo/router --version systemctl is-active cosmo-subgraph-products cosmo-subgraph-inventory cosmo-router nginx | paste -sd' ' - sudo ss -tln | grep -E ':80 |:3002|:4001|:4002' | awk '{print "LISTEN "$4}' | sort -u

The version prints 0.333.2, and all four services report active. The listeners show nginx on 0.0.0.0:80, the router on 127.0.0.1:3002 and the two subgraphs on 127.0.0.1:4001 and 127.0.0.1:4002. The router and subgraphs are bound to the loopback interface, so the only public entry point is nginx on port 80:

Router: Version: 0.333.2 active active active active LISTEN 0.0.0.0:80 LISTEN 127.0.0.1:3002 LISTEN 127.0.0.1:4001 LISTEN 127.0.0.1:4002

The router exposes a public, unauthenticated /health liveness endpoint, served through nginx on port 80. It suits a load balancer health probe:

curl -s -o /dev/null -w 'GET /health -> HTTP %{http_code}\n' http://localhost/health
curl -s http://localhost/health; echo

This returns HTTP 200 with the body OK. The endpoint needs no authentication. The federated GraphQL endpoint, covered in the next steps, is gated separately.

An API key protects the federated /graphql endpoint. The key is generated uniquely on the first boot of each instance and written, along with the resolved public URL, to a 0600 root:root credentials file. The key is masked in this guide, but the real value is on your instance. View the file details:

sudo stat -c '%A %U:%G %n' /root/wundergraph-cosmo-credentials.txt
sudo grep -E '^COSMO_API_KEY=|^COSMO_URL=' /root/wundergraph-cosmo-credentials.txt \
  | sed -r 's/(COSMO_API_KEY)=.*/\1=REDACTED_PER_INSTANCE_64_HEX_KEY/'

The file is -rw------- root:root. The COSMO_API_KEY is a 64 hex character value unique to this instance. It is created by openssl rand -hex 32 on first boot, before nginx starts serving traffic. There is no default or known key in the image, and the same key gates every call to the federated endpoint.

The federated /graphql endpoint requires the per-instance API key in the X-API-Key header. Confirm that a missing or wrong key is rejected with 401, while the per-instance key is accepted with 200:

KEY=$(sudo grep '^COSMO_API_KEY=' /root/wundergraph-cosmo-credentials.txt | cut -d= -f2-) Q='{"query":"{ topProducts { id } }"}' curl -s -o /dev/null -w '/graphql (no key) -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' -d "$Q" http://localhost/graphql curl -s -o /dev/null -w '/graphql (wrong key) -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' -H 'X-API-Key: wrong' -d "$Q" http://localhost/graphql curl -s -o /dev/null -w '/graphql (real key) -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' -H "X-API-Key: $KEY" -d "$Q" http://localhost/graphql

The calls with no key and with a wrong key are rejected with 401, and the call with the real per-instance key returns 200.

This is the security model. The health probe is open, and the per-instance key gates the federated GraphQL endpoint, so the router is never left as an open, unauthenticated data gateway.

This is the point of a federation router: one query, one endpoint, and data joined from several subgraphs. The products subgraph serves the topProducts field. The inventory subgraph serves inStock and deliveryEstimate for the same products.

The router plans the query, calls both subgraphs, resolves the shared Product entity by its key and returns a single joined response:

KEY=$(sudo grep '^COSMO_API_KEY=' /root/wundergraph-cosmo-credentials.txt | cut -d= -f2-)
curl -s -X POST http://localhost/graphql \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $KEY" \
  -d '{"query":"{ topProducts { id name price inStock deliveryEstimate } }"}' \
  | python3 -m json.tool

For each product, the response joins name and price from the products subgraph with inStock and deliveryEstimate from the inventory subgraph, in a single result:

{ "data": { "topProducts": [ { "id": "1", "name": "Cosmo Router T-Shirt", "price": 24.99, "inStock": true, "deliveryEstimate": "2-3 business days" }, { "id": "2", "name": "GraphQL Federation Mug", "price": 12.5, "inStock": false, "deliveryEstimate": "3-4 weeks" }, { "id": "3", "name": "WunderGraph Cap", "price": 18, "inStock": true, "deliveryEstimate": "1-2 business days" } ] } }

Neither subgraph can answer this query on its own. The products service does not know stock levels, and the inventory service does not know names or prices. The router makes them queryable as one graph.

The demo supergraph is composed from two local subgraph schemas and a small graph config. To federate your own services, first inspect the graph config and the composed execution config:

sudo cat /etc/cosmo/graph.yaml
sudo head -c 300 /etc/cosmo/execution-config.json; echo

To point the router at your own subgraphs, replace the routing_url and schema.file entries in /etc/cosmo/graph.yaml with your services. Install the Cosmo CLI (npm install -g wgc). Recompose with sudo wgc router compose -i /etc/cosmo/graph.yaml -o /etc/cosmo/execution-config.json, then run sudo systemctl restart cosmo-router.

The two bundled Node demo subgraphs are systemd services (cosmo-subgraph-products, cosmo-subgraph-inventory). You can disable them once you have wired in your own upstreams.

For production graphs managed across a team, connect the router to the Cosmo Cloud schema registry instead of a static file. See the WunderGraph Cosmo documentation.

From anywhere that can reach the instance on port 80, call the federated endpoint at the instance public IP with your per-instance API key. The /health check needs no credentials:

curl http://<public-ip>/health
curl -s -X POST http://<public-ip>/graphql \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $KEY" \
  -d '{"query":"{ topProducts { id name inStock } }"}'

Fetch the key from /root/wundergraph-cosmo-credentials.txt on the instance (sudo grep '^COSMO_API_KEY=' /root/wundergraph-cosmo-credentials.txt) and export it as KEY on your client.

Distribute the key to your GraphQL clients as their gateway credential. To rotate it, edit /etc/nginx/conf.d/cosmo-apikey.conf and reload nginx.

The image serves the endpoint over plain HTTP on port 80, which suits a load balancer or private network. For production, terminate TLS in front of the router so that credentials and payloads travel encrypted. You have two options:

• Front the instance with an Application Load Balancer or Network Load Balancer with an AWS Certificate Manager certificate, or a CloudFront distribution, and forward to nginx on port 80.
• Install your own certificate. Add a TLS server block to /etc/nginx/sites-available/wundergraph-cosmo that references your certificate and key, open 443/tcp on the security group, then run sudo systemctl reload nginx.

In both cases, point a DNS name you control at the instance (or the load balancer) and use that name (and https://) for your GraphQL consumers.

• Federation router: WunderGraph Cosmo Router v0.333.2 (open source, Apache-2.0)
• Router endpoint: /graphql on loopback 127.0.0.1:3002, fronted by nginx on :80
• API front: nginx on :80 reverse proxying to 127.0.0.1:3002
• Demo subgraphs: products (127.0.0.1:4001) and inventory (127.0.0.1:4002), Apollo Federation v2, loopback only
• Execution config: static, composed at build time by the Cosmo CLI (wgc router compose), with no control plane needed
• Health endpoint: /health (public, no auth)
• API key: per instance, generated on first boot into /root/wundergraph-cosmo-credentials.txt, and required on /graphql through X-API-Key