6. Publishing the subgraphs with Rover
9m

Overview

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

In this lesson, we will:

  • Create a for FlyBy in Apollo Studio
  • Use the CLI to register our s with the Apollo
  • Review the generated by the

✏️ Creating a graph in Apollo Studio

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

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

  2. If you haven't created a graph in Apollo 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 of the dashboard.

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

    studio.apollographql.com
    Creating a new graph in Apollo 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 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 . We'll get to that in a moment.

    studio.apollographql.com
    The Publish your Schema with Federation modal in Apollo Studio
Task!

✏️ Storing Apollo environment variables

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

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

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 Apollo 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 Supergraph. This specifies that our should be built using the latest features of Apollo Federation.

    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 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 graph ref. 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 graph ref 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 :

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

Warning: For security, environment s 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 s, but we'll also need to set up the CLI.

✏️ Installing the Rover CLI

  1. If you haven't installed yet, open a new terminal window and run the install command.

    curl -sSL https://rover.apollo.dev/nix/latest | sh

    Note: If you want to install using a different method, see the official Rover installation docs.

  2. Verify that the installation completed successfully by running the rover command in the terminal. If it outputs a list of options and subcommands for using , great! The CLI is installed and ready to go.

✏️ Authenticating Rover

Let's authenticate with so that Studio knows we have permission to publish s to our .

  1. In the terminal, run the following command:

    rover config auth
  2. You'll be prompted to enter the value of APOLLO_KEY, which you can find in your .env file. Paste it into the terminal (only the part after the APOLLO_KEY= piece), and press return. The terminal won't show the actual value when you paste it. It is a secret, after all!

  3. You should see a message in the terminal output that says "Successfully saved API key", which means you've successfully authenticated !

Note: If you ever lose your API key, don't worry! You can generate a new key from your graph's Settings tab in Apollo Studio. Then you'll have to reauthenticate with the new key by running rover config auth again.

Onwards to publishing our s!

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 Apollo Studio.

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 we want to publish to and the following command line options:

OptionWhat is it?
--nameWhat we want to call our subgraph in Apollo Studio
--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 s.

✏️ 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 .

    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. 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 Apollo Studio

Let's go back to Studio and have a look at "See 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 s 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 s from the locations . Each is annotated with its description, any s 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 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 graph ref, 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 managed federation to register our s to the , and Apollo Studio automatically composed our schema for us!

Reviewing our schemas

Let's take a closer look at that . Click on the SDL tab at the top of the page. Here we can see details about our published s, 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 s. (We won't worry about this schema for now.)

The Supergraph schema is used by the like a map, to define how incoming GraphQL s can be divided up among the underlying s. Let's investigate the Supergraph schema to get an idea of what Apollo Studio 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 s 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 s that belong to each one of our s.

Scroll down in the and take a look at the Query type. Here, the s we added to the Query type in both s 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 query for information about locations, reviews, or any combination of the two! And as we learned in the previous lesson, Studio will automatically recompose this supergraph schema anytime we push a change to either one of our s.

Practice

Which of the following are true statements about the supergraph?

Key takeaways

  • We can use the rover subgraph publish command from the CLI to publish our s to the Apollo .
  • Whenever a new is published, Apollo Studio composes a new schema with any subgraphs registered to our supergraph.
  • The consolidates all the types and s across our published s. It also includes extra s 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 GraphQL s and bundle data from multiple s 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.