Apollo GraphOS & Schema Registry

Apollo GraphOS is a platform for building, managing, and scaling your supergraph. It provides a Schema Registry that acts as the source of truth for your supergraph’s schema, enabling Managed Federation.

Why use GraphOS?

• Managed Federation: GraphOS handles supergraph composition for you.
• Schema Checks: Validate changes against production traffic before deploying.
• Explorer: A powerful IDE for your supergraph.
• Metrics: Detailed usage statistics and performance monitoring.

Prerequisites

1. An Apollo Studio account.
2. The Rover CLI installed.
3. A created Graph in Apollo Studio (of type “Supergraph”).

Publishing Subgraphs

Instead of composing the supergraph locally, you publish each subgraph’s schema to the GraphOS Registry. GraphOS then composes them into a supergraph schema.

1. Introspect Your Subgraph

First, start your grpc-graphql-gateway instance. Then, verify you can fetch the SDL:

# Example for the 'users' subgraph running on port 8891
rover subgraph introspect http://localhost:8891/graphql > users.graphql

2. Publish the Subgraph

Use rover to publish the schema to your graph variant (e.g., current or production).

# Replace MY_GRAPH with your Graph ID and 'users' with your subgraph name
rover subgraph publish MY_GRAPH@current \
  --name users \
  --schema ./users.graphql \
  --routing-url http://users-service:8891/graphql

Repeat this for all your subgraphs (e.g., products, reviews).

Automatic Composition

Once subgraphs are published, GraphOS automatically composes the supergraph schema.

You can view the status and build errors in the Build tab in Apollo Studio.

Fetching the Supergraph Schema

Your Apollo Router (or Gateway) needs the composed supergraph schema. With GraphOS, you have two options:

Option A: Apollo Uplink (Recommended)

Configure Apollo Router to fetch the configuration directly from GraphOS. This allows for dynamic updates without restarting the router.

Set the APOLLO_KEY and APOLLO_GRAPH_REF environment variables:

export APOLLO_KEY=service:MY_GRAPH:your-api-key
export APOLLO_GRAPH_REF=MY_GRAPH@current

./router

Option B: CI/CD Fetch

Fetch the supergraph schema during your build process:

rover supergraph fetch MY_GRAPH@current > supergraph.graphql

./router --supergraph supergraph.graphql

Schema Checks

Before deploying a change, run a schema check to ensure it doesn’t break existing clients.

rover subgraph check MY_GRAPH@current \
  --name users \
  --schema ./users.graphql

GitHub Actions Example

Here is an example workflow to check and publish your schema:

name: Schema Registry

on:
  push:
    branches: [ main ]
  pull_request:

env:
  APOLLO_KEY: ${{ secrets.APOLLO_KEY }}
  APOLLO_VCS_COMMIT: ${{ github.event.pull_request.head.sha }}

jobs:
  schema-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Rover
        run: curl -sSL https://rover.apollo.dev/nix/latest | sh
      
      - name: Start Gateway (Background)
        run: cargo run --bin users-service &
      
      - name: Introspect Schema
        run: |
          sleep 10
          ~/.rover/bin/rover subgraph introspect http://localhost:8891/graphql > users.graphql

      - name: Check Schema
        if: github.event_name == 'pull_request'
        run: |
          ~/.rover/bin/rover subgraph check MY_GRAPH@current \
            --name users \
            --schema ./users.graphql

      - name: Publish Schema
        if: github.event_name == 'push'
        run: |
          ~/.rover/bin/rover subgraph publish MY_GRAPH@current \
            --name users \
            --schema ./users.graphql \
            --routing-url http://users-service/graphql