Publish subgraphs to the GraphQL CDN and refresh the frontend client schema
The GraphQL CDN is the registry of the graph's schema. The Cosmo router control
plane composes the graph and updates it, and the Cosmo router reads it to learn
which subgraphs exist. Studio is where you inspect the result. See
AxonMundi onboarding for the URLs.
A successful composition means the registry has a valid graph configuration.
It does not prove a service is healthy or that a new client surface is
deployed. Producers deploy compatible services before publishing a schema, then
verify the composition and router telemetry afterward.
Routing URLs
The router needs a URL for each subgraph. For the dev router, whether it takes
these URLs from the registry or from Helm values is an open question.
Refresh the frontend schema
@prepared911/data-gql vendors the composed client schema so code generation and
mocks do not depend on a running router. The normal refresh fetches the latest
valid schema from axonmundi/default:
Copy .env.wgc.example to the untracked .env.wgc file and load it:
Log in with the Keycloak device flow (realm cosmo). Whether it signs in
with Okta and needs no VPN is not yet verified:
Refresh the schema, regenerate dependent types, and check the committed copy:
pnpm schema:sync:check compares the committed copy without writing. It must
print matches Cosmo registry.
pnpm schema:login is a personal login session. Do not run it for another
person or substitute a CI API key. Neither COSMO_API_URL nor COSMO_API_KEY
belongs in a local file you commit, a repository variable, or a log.
Sync only from the registry
Refresh the vendored schema only with pnpm schema:sync against the Cosmo
registry, as above. Do not sync axon911-frontend's schema from a local AxonMundi
checkout (AXONMUNDI_DIR) or a hand-picked file (SCHEMA_SOURCE), and never
edit packages/data-gql/src/schema.graphql by hand.If a subgraph change is not in the registry yet, wait for its owner to publish
it. See Publish a subgraph.
Publish a subgraph
Note for frontend developers: You do not need to run these commands or
publish subgraphs. This section is for backend service owners.
A service defines its GraphQL schema (*.graphqls) and exposes a GraphQL or gRPC
endpoint. Publishing uploads the schema, and an optional gRPC mapping, to the
registry, which tells the router to serve the subgraph.For now, publish by hand with wgc from your service's repository. CI/CD comes
later. These steps are not yet verified end to end against the dev router.
Log in with the Keycloak device flow, as above:
Set the subgraph name and the URL the router can reach:
Whether the dev router uses this URL is open; see
Routing URLs. Set it correctly either way.
Check the schema. This changes nothing:
Publish. This stops if the composition fails:
For an event subgraph (EDFS), publish its owner first. Then create the event
subgraph, and publish it with no --routing-url:
Sync axon911-frontend. The last command must print matches Cosmo registry:
Watch out
publish never changes an existing subgraph's URL or labels. Use
wgc subgraph update for that.
Publish the owner before its EDFS subgraph, or the EDFS check fails.
A router below 0.335.0 fails to start once an EDFS subgraph is in the graph.
Never roll a router back below 0.335.0 while an EDFS subgraph is published.
Delete it first with wgc subgraph delete <name>-edfs -n default.
Kafka providers live in router config, not in the registry.
A new registry owned from git is planned. Subgraphs will be republished from
git, so set URLs correctly now.
For generated-code requirements, CI credential setup, and rollback details, use
the
subgraph CI and registry publication runbook.
These runbooks are not yet updated for the GraphQL CDN.