6. Publishing the subgraphs with Rover
9m

Overview

Now that we've seen what the full workflow looks like, it's time to pick up where we left off with FlyBy. We have our locations and reviews in place, so the next steps are to create a in and publish our subgraphs!

In this lesson, we will:

  • Create a for FlyBy in
  • Use the to register our with the schema registry
  • Review the generated by the schema registry

✏️ Creating a graph in GraphOS Studio

Let's start by spinning up a new for FlyBy.

  1. Open a new browser window and go to GraphOS Studio.

    studio.apollographql.com

    The landing page for a fresh Enterprise account

  2. If you haven't created a in Studio before now, you'll can get started by clicking Connect a GraphQL API.

    Otherwise, we can click the + Create New Graph button in the upper right corner of the Graphs tab.

    studio.apollographql.com
    The New Graph button in Studio
  3. We'll give our a descriptive title, keep the default settings for Graph Architecture as "", then click Next.

    studio.apollographql.com

    Creating a new graph in Studio

    If you don't see the modal above, you may be on the wrong plan.

    Check your plan: Part of this course covers the self-hosted GraphOS 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.

  4. We should now see a modal with options for publishing a schema.

    studio.apollographql.com

    The Publish your Schema with Federation modal in Studio

    We'll get to that in a moment.

Task!

✏️ Storing GraphOS environment variables

To publish our using , we'll need to save two environment variables from Studio:

  • APOLLO_KEY: An API key for authenticating . It starts with something like service:your-graph-name.
  • APOLLO_GRAPH_REF: The graph reference (or ) for our , which we'll use to tell where to publish our .
    • A starts with the graph's ID, followed by an @ symbol, followed by the .

We can get the values for APOLLO_KEY and APOLLO_GRAPH_REF out of the publishing options modal in Studio.

  1. Go back to the configuration options in Studio that appeared after you created your . Make sure you're on the Schema Document tab.

  2. First, make sure that the Supergraph Pipeline Track dropdown is set to Federation 2.7 Supergraph. This specifies that our should be built using the latest features of .

    studio.apollographql.com

    The Publish your schema with Federation modal, highlighting the Federation 2 Supergraph option for the Supergraph Pipeline Track

  3. Below, take a little peek at the command for publishing a . 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
  4. Click on the eye icon on the code block to reveal the full value of APOLLO_KEY. Copy APOLLO_KEY and its value to your clipboard.

  5. Back in our code editor, we'll create a new file in the router directory called .env.

  6. Paste your APOLLO_KEY into router/.env.

    router/.env
    APOLLO_KEY=your-graphs-apollo-key
  7. Now let's go back to Studio to get our . The value we're looking for appears in the same code block, directly after the " publish" part of the command. We'll copy this value onto our clipboard.

    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

    Note: Our uses the current for our , which is the default variant. We'll talk more about variants in Voyage III: Federation in Production.

  8. In your router/.env file, add a new line and set your APOLLO_GRAPH_REF environment variable:

    router/.env
    APOLLO_KEY=your-graphs-apollo-key
    APOLLO_GRAPH_REF=your-graph-name@current
Task!

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 !

The rover subgraph publish command

has a command ready to help us with this important task: rover subgraph publish. This command pushes the latest version of a single to .

rover subgraph publish <APOLLO_GRAPH_REF> \
--name <SUBGRAPH NAME> \
--schema <SCHEMA FILE PATH> \
--routing-url <ROUTING URL>

To use this command, we need the for the we want to publish to and the following command line options:

OptionWhat is it?
--nameWhat we want to call our subgraph in GraphOS
--schemaThe relative path to our subgraph's schema file
--routing-urlThe URL where our subgraph runs (locally, for now)

We'll fill in these options with the details for each of our .

✏️ Publishing the locations subgraph

Let's see this command in action by publishing our locations .

  1. Bounce back to the terminal and make sure we're in the root directory for the project.

  2. Now let's type out the rover subgraph publish command:

    We'll paste in the value of our APOLLO_GRAPH_REF environment variable.

    For the name option, we'll pass in locations.

    For the schema option, we'll pass the relative path to our locations.graphql file.

    And for the routing-url option, we'll pass in localhost:4001.

    rover subgraph publish <APOLLO_GRAPH_REF> \
    --name locations \
    --schema ./subgraph-locations/locations.graphql \
    --routing-url http://localhost:4001

    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 \.

  3. After running the command, 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]

    Type in y to allow it. We're in tutorial land and working in local environments for now!

    Note that you'll need to do this after every publish command.

  4. If all is well in the world, running this command should output a message confirming that the has been published and the has been updated!

Checking the results in Studio

Let's go back to Studio and have a look at "See schema changes" to see what's changed in our .

This new page looks similar to the Sandbox we used in previous lessons, but with additional features for managing our .

Let's click on the Schema tab in the sidebar.

Schema Reference

The Schema Reference page lets us see all the types and in our composed . That's right, even though we've only published one so far, we already have a supergraph schema!

We see that our 's Query type includes the two from the locations . Each is annotated with its description, any it requires, and which subgraph it belongs to.

studio.graphql.com/graph/flyby/schema/reference?variant=current
The Schema page for our graph

✏️ Publishing the reviews subgraph

Let's use rover subgraph publish again to publish the reviews and see how our schema changes.

  1. Back in the terminal in the root of our project, we'll use the rover subgraph publish command again. We won't change our , but we'll update the other command line options to reflect the reviews :

    rover subgraph publish <APOLLO_GRAPH_REF> \
    --name reviews \
    --schema ./subgraph-reviews/reviews.graphql \
    --routing-url http://localhost:4002
  2. After it runs successfully, head back to Studio and refresh the Schema Reference page. Now we can see the new latestReviews that our reviews added to the Query type!

    studio.apollographql.com
    The updated Schema reference page, now including the latestReviews Query entrypoint

Nice job! With just a few commands, we've reached an important milestone on our federation journey. We've used to register our to the schema registry, and automatically composed our for us!

Reviewing our schemas

Let's take a closer look at that . Click on the SDL tab at the top of the Schema page. Here we can see details about our published , along with two additional schemas.

The API schema is the API that gets exposed to your clients. It cleanly and logically represents the combination of your . (We won't worry about this schema for now.)

The Supergraph schema is used by the like a map, to define how incoming can be divided up among the underlying . Let's investigate the Supergraph schema to get an idea of what is doing for us behind the scenes.

studio.apollographql.com
The supergraph schema composed from publishing two subgraphs

Looks like the includes some new syntax and that we didn't create ourselves. We don't need to dive into these. But what's more interesting to us is seeing how the supergraph schema identifies the types and that belong to each one of our .

Scroll down in the and take a look at the Query type. Here, the we added to the Query type in both have been consolidated in one place. Each is annotated with a special @join_field that references the name of its originating .

type Query @join__type(graph: LOCATIONS) @join__type(graph: REVIEWS) {
"""
The full list of locations presented by the Interplanetary Space Tourism department
"""
locations: [Location!]! @join__field(graph: LOCATIONS)
"""
The details of a specific location
"""
location(id: ID!): Location @join__field(graph: LOCATIONS)
"""
The three latest reviews submitted for FlyBy's locations
"""
latestReviews: [Review!]! @join__field(graph: REVIEWS)
}

Our provides a complete picture for the to for information about locations, reviews, or any combination of the two! And as we learned in the previous lesson, will automatically recompose this supergraph schema anytime we push a change to either one of our .

Practice

Which of the following are true statements about the supergraph?

Key takeaways

  • We can use the rover subgraph publish command from the to publish our to the Apollo schema registry.
  • Whenever a new is published, composes a new with any subgraphs registered to our supergraph.
  • The consolidates all the types and across our published . It also includes extra to help the determine which subgraphs can resolve each field.

Up next

Our next task is to look at how the uses the to resolve incoming and bundle data from multiple into one clean response.

Previous

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.