Supergraph resources
Deploy supergraphs in Kubernetes using the Apollo GraphOS Operator
A Supergraph is a Kubernetes resource that allows you to run the GraphOS Router and its supporting resources.
When you create a Supergraph in your cluster, the Apollo GraphOS Operator will automatically provision the following resources for you:
A Deployment for the GraphOS Router
A Service for traffic ingress
A ConfigMap for your GraphOS Router configuration
A Secret for the graph API key
Deploying a Supergraph
To deploy a Supergraph in your Kubernetes cluster, you must define at least three properties:
The number of replicas
The GraphOS Router version you want to use
The Supergraph schema source
Here is an example that deploys two replicas of the GraphOS Router version 2.4.0, using the latest Supergraph schema version of the my-graph@my-variant graph variant.
1apiVersion: apollographql.com/v1alpha2
2kind: Supergraph
3metadata:
4 name: my-supergraph
5spec:
6 # Number of replicas
7 replicas: 2
8 # Version of the GraphOS Router
9 podTemplate:
10 version: 2.4.0
11 # Source for the Supergraph Schema
12 schema:
13 studio:
14 my-graph@my-variantSpecifying a schema source
The Supergraph resource type supports three schema sources:
A GraphOS Studio graph variant reference (graphRef).
A ../supergraphschema resource reference.
An OCI artifact reference.
Apollo GraphOS Studio
You can specify a graph variant reference (graphRef).
By default, the Supergraph will use the latest available launch in Apollo GraphOS Studio. When you make a change, for example by publishing a new version of a subgraph schema, the Apollo GraphOS Operator will trigger an update to your Supergraph.
1spec:
2 schema:
3 studio:
4 graphRef: my-graph@my-variantIf you want finer grain control over your deployment process, you can specify a launch ID.
You can combine this with a git generator and schema change notifications to automatically create pull requests in your repository whenever a new version of your Supergraph schema is available.
1spec:
2 schema:
3 studio:
4 graphRef: my-graph@my-variant
5 launchId: "00000000-0000-0000-0000-000000000000"SupergraphSchema resource
If you are using Subgraph and SupergraphSchema resources to define your Supergraph schema using Kubernetes-native resources, you can directly reference the SupergraphSchema resource in your cluster instead.
In this case, the Supergraph will use the latest launch ID marked as Available in the SupergraphSchema status.
1spec:
2 schema:
3 resource:
4 name: my-supergraph
5 # Optional: if the resource is not in the same namespace as your Supergraph,
6 # you can specify the namespace here:
7 namespace: apollo-schemasOCI artifact reference
For increased reliability, you can store your Supergraph schema as an OCI artifact in your own registry.
To store your supergraph schema in an OCI artifact, you store it in a layer using the application/vnd.apollographql.schema file type.
1spec:
2 schema:
3 oci:
4 reference: my-registry/my-graph:my-tag
5 # Optional: graph variant referene for automated integration with the GraphOS Platform
6 graphRef: my-graph@my-variantMonitoring Supergraph deployments
The Apollo GraphOS Operator will monitor changes in your Supergraph resource and reflect them in the resource status. These changes can happen either because you have changed the Supergraph spec or there is a new version of your Supergraph schema available.
It will reflect the state of your resource using three status conditions types:
SchemaLoaded: If it was able to load your Supergraph schema and what is the latest known schema version.
Progressing: If a deployment of the GraphOS Router is in progress or was successful, and its current state.
Ready: If your GraphOS Router replicas are able to process traffic.
Here is an example of the conditions for a Supergraph with a successful deployment:
1status:
2 conditions:
3 - type: "SchemaLoaded"
4 status: "True"
5 reason: "Loaded"
6 observedGeneration: 3
7 schema:
8 studio:
9 graphRef: my-graph@my-variant
10 launchId: "00000000-0000-0000-0000-000000000000"
11 updatedAt: "2025-07-03T12:34:56Z"
12 - type: "Progressing"
13 status: "True"
14 reason: "DeploymentCompleted"
15 observedGeneration: 3
16 schema:
17 studio:
18 graphRef: my-graph@my-variant
19 launchId: "00000000-0000-0000-0000-000000000000"
20 updatedAt: "2025-07-03T12:34:56Z"
21 - type: "Ready"
22 status: "True"
23 reason: "DeploymentCompleted"
24 observedGeneration: 3
25 schema:
26 studio:
27 graphRef: my-graph@my-variant
28 launchId: "00000000-0000-0000-0000-000000000000"
29 updatedAt: "2025-07-03T12:34:56Z"Monitoring schema loading
Once the Apollo GraphOS Operator detects that a new Supergraph schema is available, it will update the SchemaLoaded condition with the following properties:
type: SchemaLoadedstatus: Truereason: Loaded
On the other hand, if the Operator fail to load the Supergraph schema, it will have a condition with the following values:
type: SchemaLoadedstatus: Falsereason: MissingData | reason: FetchError | reason: InvalidSpec
Monitoring Supergraph deployments
The deployment of those resources can either be progressing, complete or failed. The Operator will automatically populate the Progressing condition to reflect that state.
Progressing Supergraph deployment
When the Operator starts a deployment, it will update the Progressing condition with the following properties:
type: Progressingstatus: Truereason: HasChanges | reason: DeploymentInProgress
The HasChanges reason reflects that the Operator recently applied changes to the underlying resources. If one of these resources is the underlying Deployment, this will trigger a new rollout and will cause the Progressing condition to update to DeploymentInProgress
Complete Supergraph deployment
When the underlying deployment is complete, the Operator will update the Progressing condition with the following properties:
type: Progressingstatus: Truereason: DeploymentCompleted
It will also update the Ready condition with the following properties:
type: Readystatus: Truereason: DeploymentCompleted
Failed Supergraph deployment
If the deployment fails, the Operator will update the Progressing condition with the following properties:
type: Progressingstatus: Falsereason: DeploymentFailed