Deploy a Supergraph

In this guide, you will:

• Create a graph in GraphOS Studio

• Define a SupergraphSchema to compose your Subgraphs

• Deploy a Supergraph as a running GraphQL API

You will need:

• Apollo GraphOS Operator installed in your cluster (see Install Operator)

• Subgraphs deployed and schemas loaded (see Add Subgraphs)

1. Create a graph in GraphOS Studio

The Apollo GraphOS Operator can publish and deploy graphs and graph variants from GraphOS Studio, but it cannot create new graphs. You can also use existing graphs with the Operator, however we strongly recommend to use a new graph for this tutorial.

Let's create a new graph in Studio to use as our base for supergraph publishes and deploys.

1. Navigate to https://studio.apollographql.com/ and log in.

2. Click on the Add graph button.

3. Click on Connect an existing graph.

4. Name your graph, then click on Next.

5. Take note of the graph ID, you should find it on a line starting with rover subgraph publish <graph ID>@current.

2. Create a SupergraphSchema

The SupergraphSchema resource defines how your Subgraphs are composed into a supergraph. It specifies which Subgraphs to include and how they should be composed.

Open a new file named supergraphschema.yaml in your favorite IDE. Make sure to replace <graph ID> with the value obtained in step 1.

1apiVersion: apollographql.com/v1alpha2
2kind: SupergraphSchema
3metadata:
4  name: retail
5spec:
6  selectors:
7    - matchLabels:
8        domain: retail
9  graphRef: <graph ID>@current

In this schema, we are taking all the Subgraph resources that match the retail domain label and composing them together. The graphRef points to the graph we created in GraphOS Studio.

Now let's apply our resource and monitor its status:

kubectl apply -f supergraphschema.yaml
kubectl get supergraphschema retail -o yaml

After some time, you should see an Available condition showing the latest available schema. You can also navigate to https://studio.apollographql.com/graph/<graph ID>/variant/current to see your Operator-managed variant in Studio.

3. Deploy the supergraph

Now that you have a supergraph schema, you can deploy it into your cluster.

Open a supergraph.yaml file in your favorite IDE:

1apiVersion: apollographql.com/v1alpha2
2kind: Supergraph
3metadata:
4  name: retail
5spec:
6  replicas: 2
7  schema:
8    resource:
9      name: retail
10  routerConfig:
11    homepage:
12      enabled: false
13    sandbox:
14      enabled: true
15    supergraph:
16      introspection: true
17  podTemplate:
18    routerVersion: 2.4.0

Apply the resource and wait for a Ready condition:

kubectl apply -f supergraph.yaml
kubectl get supergraph retail -o yaml

4. Test your supergraph

Finally, forward the port to your supergraph.

1kubectl port-forward deployment/retail 4000:4000

Then navigate to [http://localhost:4000/]. You should now see the Apollo Sandbox for your Operator-managed Supergraph!

Configuration options

Direct graph reference

You can also deploy a supergraph that references a GraphOS graph directly:

1apiVersion: apollographql.com/v1alpha2
2kind: Supergraph
3metadata:
4  name: retail
5spec:
6  replicas: 2
7  schema:
8    graphRef: your-graph-name@current
9  routerConfig:
10    sandbox:
11      enabled: true
12  podTemplate:
13    routerVersion: 2.4.0

Multiple subgraph selectors

You can use multiple selectors to include subgraphs from different groups:

1spec:
2  selectors:
3    - matchLabels:
4        domain: retail
5    - matchLabels:
6        environment: production

Safe deployments

By default, the Supergraph uses a standard Kubernetes Deployment with the RollingUpdate strategy, which gradually replaces pods (typically 25% at a time). For production workloads, use safe deployments to enable:

• Canary deployments: Gradually shift traffic to new versions

• Automated analysis: Run tests and checks before promoting new versions

• Automatic rollback: Revert to previous versions if issues are detected

For more details, see the Safe Deployments guide.

Next steps

You're all done! You have successfully composed and deployed a supergraph using the Apollo GraphOS Operator.

Looking to go further? Here are some next steps:

• Explore different ways of defining your subgraphs

• Customize your supergraph deployment

• Configure safe deployments for production workloads