In this lesson, we will:
- Create a supergraph with a self-hosted router in GraphOS
- Publish a subgraph schema to the schema registry using the Rover CLI
Creating a graph in GraphOS Studio
Let's start by spinning up a new supergraph.
- Open up a new browser window and go to GraphOS Studio.
Check your plan: Part of this course covers the self-hosted router, which requires a GraphOS Enterprise plan. You can still follow along if your organization is on a different plan, but you won’t be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free Enterprise trial.
If you haven't created a graph in Studio before now, you'll be prompted to do so.
Otherwise, we can create a new graph by clicking the + Create New Graph button in the upper right corner.
We'll give our graph a descriptive title (we've chosen the name "MusicMatcher"), keep the default settings for Graph Architecture as "Supergraph", then click Next.
If you don't see the graph modal above, you may be on the wrong plan.
We should now see a new modal with instructions for publishing our schema.
To publish our soundtracks schema to our new graph, we'll use the Rover CLI. Rover lets us connect to our graph from the command line and publish schemas, but it needs a couple of pieces of data first:
APOLLO_KEY: Your graph's API key, used to interact with a single graph in GraphOS. It starts with something like "
service:your-graph-name". Note that this is different from your personal API key, which we used to authenticate Rover in the first lesson, and grants you partial access to every graph in the organization you belong to.
APOLLO_GRAPH_REF: The graph reference (or graph ref) for our supergraph, which we'll use to tell Rover where to publish our subgraphs. A graph ref starts with the graph's ID, followed by an
@symbol, followed by the graph variant.
We'll use these values again when we run the router, so we can store them in a new file we'll add to the router directory called
Let's create that file now.
📦 Odyssey.MusicMatcher┣ 📂 Router┃ ┣ 📄 router-config.yaml┃ ┣ 📄 .env
First, make sure that the Supergraph Pipeline Track dropdown is set to Federation 2.5 Supergraph. This specifies that our supergraph should be built using the same federation version as our schemas. The Apollo Federation Hot Chocolate subgraph we're using only supports 2.5 at this time.https://studio.apollographql.com
Make sure you're on the Schema Document tab, not the Introspection tab.
Below, take a little peek at the command for publishing a subgraph schema. We'll be running this command shortly, but for now, we're more interested in the APOLLO_KEY environment variable here.APOLLO_KEY=your-graphs-apollo-key \rover subgraph publish your-graph-name@current \--name products --schema ./products-schema.graphql \--routing-url http://products.prod.svc.cluster.local:4001/graphql
Click on the eye icon on the code block to reveal the full value of
APOLLO_KEYand its value to your clipboard, then paste it into
Now let's go back to Studio to get our graph ref. The value we're looking for appears in the same code block, directly after the "rover subgraph publish" part of the command. We'll save this value as an environment variable as well, but we can access it anytime from our graph's home page.Router/.envAPOLLO_KEY=your-graphs-apollo-key \rover subgraph publish your-graph-name@current \--name products --schema ./products-schema.graphql \--routing-url http://products.prod.svc.cluster.local:4001/graphql
Router/.envfile, add a new line and set your
Warning: For security, environment variables should never be committed to version control. For this reason, this project includes a
.gitignore file which specifies that the
.env file should be ignored when committing code changes to a repository.
We've got the values we need to publish our subgraph!
rover subgraph publish command
Rover has a command ready to help us with this important task:
rover subgraph publish. This command publishes the latest version of a single subgraph schema to the GraphOS schema registry.
rover subgraph publish <APOLLO_GRAPH_REF> \--name <SUBGRAPH NAME> \--schema <SCHEMA FILE PATH> \--routing-url <ROUTING URL>
To use this command, we need the graph ref for the supergraph we want to publish to and the following command line options:
|What is it?
|What we want to call our subgraph
|The relative path to our subgraph's schema file
|The URL where our subgraph runs (locally, for now)
Note: If your
soundtracks server is not already running, boot it up now!
We'll fill in these options with the details of our
Bounce back to the terminal and make sure we're in the root directory for the project.
Now let's type out the
rover subgraph publishcommand, and paste in the value of our
nameoption, we'll pass in
schemaoption, we'll pass the relative path to our
And for the
routing-urloption, we'll pass in
http://localhost:5059/graphql, where our server is running.rover subgraph publish <APOLLO_GRAPH_REF> \--name soundtracks \--schema schema.graphql \--routing-url http://localhost:5059/graphql
Note: We've used the \ character in this command to improve legibility by putting each command-line option on its own line. If you choose to type the entire rover subgraph publish command on a single line, you don't need to include the
You'll see the following message:The host `localhost` is not routable via the public internet.Continuing the publish will make this subgraph reachable in local environments only.Would you still like to publish? [y/N]
yto allow it. We're in tutorial land and working in local environments for now! In a production environment, we would incorporate this command into CI/CD and deploy it to be accessible outside of our own computers.
Note that you'll see this message after every subgraph schema publish command that points to a localhost URL.
If all is well in the world, we should see a message confirming that the subgraph has been published and the supergraph has been updated!
Checking the results in GraphOS Studio
Let's go back to Studio and have a look at "See schema changes".
This takes us to a new page called Launches. A launch is the process that runs every time we make a change to our supergraph. We'll take a closer look at launches in an upcoming lesson.
For now let's click on the Schema tab in the sidebar.
The Schema Reference page lets us see all the types and fields in our supergraph schema. That's right, even though we've only published one subgraph so far, we already have a supergraph schema!
We see that our supergraph's Query type includes the two fields:
playlist(id). Each field is annotated with its description, any variables it requires, and which subgraph it belongs to.
Let's take a closer look at that supergraph schema. Click on the SDL tab at the top of the Schema page. Here we can see details about our published subgraphs, along with two additional schemas.
The API schema is the GraphQL API that gets exposed to your clients. It cleanly and logically represents the combination of your subgraph schemas. (We won't worry about this schema for now.)
The Supergraph schema is used by the router like a map, to define how incoming GraphQL operations can be divided up among the underlying subgraphs. We only have one at the moment, so all fields in an operation will be routed over to the
- We can use the
rover subgraph publishcommand from the Rover CLI to publish our subgraph schemas to GraphOS.
- The supergraph schema consolidates all the types and fields across our published subgraphs. It also includes extra directives to help the router determine which subgraphs can resolve each field.
We're still missing an important piece of the supergraph architecture: the router.
Share your questions and comments about this lesson
This course is currently in
You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.