Deployment Patterns

Production deployment patterns for Apollo Router

Graph artifacts

Graph artifacts contain a supergraph created from a single build. Whereas graphs are referred to by their graph id and variant name, graph artifacts are instead referred to by their unique hash digest. Given that digest reference, a router can be configured to point to a single, immutable supergraph instead of the latest-built supergraph, giving you complete control over what is running in your production environment.

Choose a deployment strategy with graph artifacts

StrategyBest ForDowntimeRollback SpeedComplexity
Blue/greenHigh-traffic productionZeroInstantHigh
RollingLower-traffic or simpler setupsMinimalDelayedLow

Retrieving a graph artifact digest

See Schema from graph artifacts for information on how supergraph builds are mapped to OCI URIs and how to retrieve them.

Launch router fleets

Blue/green deployment

In a blue/green deployment, you pin two separate fleets of routers to different schemas.

  1. Launch the blue fleet with the initial URI.

  2. Make a change to a subgraph and let it build.

  3. Launch the green fleet with the updated URI.

  4. Validate the green fleet and shift traffic from blue to green.

  5. Monitor for errors, and if necessary, shift traffic back to blue.

1. Launch the blue router fleet

Use the URI queried above as the graph artifact reference:

Bash
1APOLLO_KEY="your-api-key" \
2APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/my-graph-a50b9d546b298e5a@sha256:14409db3d8a8d74ff9e9a0b5712c0aa8d574bcacc3656e1bc0c55ecf97cd9264" \
3router

2. Publish a new subgraph to GraphOS

GraphOS composes a new supergraph, but your router fleet does not automatically deploy. Query for the new graph artifact URI using the above queries.

3. Launch the green router fleet

Bash
1# Using tag reference
2APOLLO_KEY="your-api-key" \
3APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/my-graph-a50b9d546b298e5a@sha256:08a2d3c63bf9fc88276d97a9e8df5f841fd772724ad10f119f7e516f228b74c6" \
4router

4-5. Shift traffic and monitor

Use your existing infrastructure to monitor and adjust your load balancer's weighted routing as appropriate. If errors occur, shift traffic back to the blue fleet.

Trade-offs

Pros:

  • Zero downtime

  • Instant rollback

  • Gradual rollout

  • Deterministic versions

  • Staging environment mirroring production

  • Pre-provisioned failover environment

Cons:

  • Cost for two full environments

Rolling deployment

Instead of maintaining two fleets, you can redeploy each router in the fleet with a new APOLLO_GRAPH_ARTIFACT_REFERENCE.

Trade-offs

Pros:

  • Simpler and cheaper setup, no need for two fleets

Cons:

  • Slower rollback that requires pod restarts

  • Less control over traffic distribution

  • Failover requires full environment creation
Feedback

Edit on GitHub

Ask Community