What is a feature flag?
In WunderGraph Cosmo , feature flags work by creating toggle-able collections of “subgraph replacements”, known as feature subgraphs, for one or more supergraphs.
The three pieces
In summary, a feature flag is built from three things:
A normal subgraph that already composes your supergraph.
An override of a base subgraph. It is linked to exactly one base subgraph and is meant to replace it when active. It carries a new version of that subgraph's schema.
A named, toggle-able collection of one or more feature subgraphs. When the flag is enabled and matched to a request, each of its feature subgraphs replaces its respective base subgraph for that request.
How they fit together
A feature subgraph does nothing on its own. It only takes effect once it is part of a feature flag and that flag is enabled. Toggling a feature flag is what swaps the feature subgraphs in for their base subgraphs.
When you enable a flag, Cosmo runs a fresh composition that includes the feature subgraphs, and embeds that result as a feature-flag configuration inside the router's execution config.
The composed artifact the router loads to execute requests. It includes the supergraph schema, subgraph routing info, and any embedded feature-flag compositions so the router can plan and serve queries per request.
Core terminology
This course uses a few core GraphQL Federation terms. As a quick primer, here are the terms we will use in this course:
The overall approach: a way to combine many independently built GraphQL APIs into one unified API, allowing consumers to call a single endpoint instead of each service separately.
One of the individual GraphQL services being combined. Each subgraph can be owned by a single team and covers one part of the business, for example "users," "payments," or "products." On its own, a subgraph is just a normal GraphQL API.
The single, unified API that results from combining all the subgraphs. Consumers query one clean API, even though many independent services (and teams) may sit behind it.
The process of merging all subgraph schemas together, resulting in one composed supergraph.
The entry point for the supergraph. It receives every client query, plans which subgraphs to call, executes those requests, and returns one combined response. Underneath, it's a GraphQL server process you deploy like any other service. It loads the composed supergraph config and directs traffic as necessary.
The central place that stores every subgraph's schema and checks whether they will combine safely. When a team proposes a change, the registry verifies it won't break the combined API before it ships to production.
Our exercise (using WunderGraph Cosmo)
You'll also come across some vendor-specific terms, such as:
WunderGraph’s open-source (Apache 2.0 license) GraphQL Federation router: a Go binary you can run yourself or use as a managed service.
The hosted control plane and Studio UI for schema registry, composition, feature flags, analytics, and router config. Your Cosmo Router connects to Cosmo Cloud to pull the config and report telemetry.
We'll self-host the router locally for this exercise, as described in the next lesson.
Why use feature flags?
Migrating functionalityHow:Pull a capability out of a monolith into a new subgraph and evaluate the results. Once the outputs match and performance looks good, you promote the flag from shadow to a real rollout.Why:De-risks migration efforts.
How:Ship a schema change to 1% of clients, watch your metrics, and ramp up only when it looks healthy.Why:If something is wrong, you disable the flag instead of rolling back an entire deploy.
How:Run more than one version of a subgraph's schema at the same time.Why:Clients that opt into the flag see the new fields; everyone else keeps the stable schema until they are ready.
How:Because the flag is chosen per request (via a header or cookie), you can drive it from a JWT claim, a cookie, or a gateway rule.Why:Effectively a per-user or per-cohort toggle.
How:Instead of standing up a full parallel stack per developer, a single shared environment plus a feature flag can give each developer or team an isolated view of their in-progress schema.Why:Reduces infrastructure overhead and lets developers collaborate or test safely in isolation.
What the router does not handle
An important boundary: the Cosmo Router is not responsible for deciding which percentage of traffic gets the flag.
The router simply reads a header or cookie on each request and serves the matching schema. Deciding which requests carry that header—1%, then 10%, then 100%—is the job of your load balancer, proxy, or gateway. We come back to this in the gradual-rollout lesson.
Task
Knowledge check
What is a feature subgraph?
A feature subgraph on its own, not part of any flag, will…
Who decides what percentage of traffic receives a feature flag?