Odyssey

Voyage I: Federation from Day One

Intro to FederationProject setupAgreeing on a schemaBuilding out the subgraphsManaged federation & the supergraphPublishing the subgraphs with RoverHow the router resolves dataRouter configuration and UplinkConnecting data using entitiesDefining an entityEntities and the query planReferencing an entityContributing to an entityPutting it all together
5. Managed federation & the supergraph
3m

Overview

Our subgraphs are running locally, and it's time to see how they fit in with the rest of our supergraph architecture. Let's take a step back and look at the overall process for how a supergraph gets made, from start to finish, using managed federation.

In this lesson, we will:

  • Outline the overall process for how a supergraph gets made from start to finish

The managed federation workflow

Managed federation is an approach to maintaining a supergraph. With managed federation, updates to your supergraph schema are handled by GraphOS and the schema registry, all with zero downtime for the GraphOS Router—which we'll get to in a bit.

At a high-level, the managed federation workflow looks like this:

  1. Backend developers design and build their subgraphs.
  2. Someone creates a new supergraph in GraphOS Studio.
  3. Backend developers publish their subgraph schemas to the schema registry.
  4. The schema registry automatically composes the subgraph schemas together into a supergraph schema. and makes it available via Apollo Uplink.
  5. The router automatically polls Uplink for any new versions of the supergraph schema.

Let's take a closer look at each of these steps.

Step 1: Teams build their subgraphs

As we've already seen, when using a schema-first approach, the frontend and backend teams first agree on the types and fields their supergraph will include. From there, we move to the backend to decide how to distribute those types and fields across multiple subgraphs.

The schema agreement from earlier, with each field highlighted to show whether it belongs to the locations or reviews subgraph.

With all that in place, backend teams can independently build out their subgraph servers, complete with schemas, resolvers, and data sources.

An illustration showing the first step of the process: backend teams can independently build out their subgraph servers, complete with schemas, resolvers, and data sources.

Step 2: Creating a new supergraph in GraphOS Studio

Next, someone needs to create a new supergraph in Studio, which will be used by all the subgraphs for this app. Only one person needs to do this step.

Step 2: create a new deployed graph in GraphOS Studio where the subgraphs can be registered

Step 3: Publishing subgraphs

When we're happy that our subgraphs are looking slick, we'll use the Rover CLI to publish each subgraph's schema to the schema registry. The schema registry is an Apollo-hosted version control system, which enables us to track changes to our schemas over time.

Step 3: publish each subgraph's schema to the Apollo schema registry

Step 4: Composing the supergraph schema

When the schema registry gets a new or updated version of a subgraph schema, it starts a process called composition. The schema registry attempts to combine all of the schemas from the registered subgraphs into a single supergraph schema. Pretty cool!

Step 4: Composing the supergraph schema

If composition fails, the schema registry displays an error in Studio, and the process stops there. No stress: we can use the error messages to fix the issue in our subgraph, and then try publishing the subgraph with Rover again.

If composition fails, the schema registry displays an error in GraphOS Studio

If composition succeeds and there are no validation errors, the schema registry produces a supergraph schema.

The schema registry automatically sends the supergraph schema to an internal service within Studio called Apollo Uplink. Uplink is a server that stores the latest supergraph schema for each graph.

The schema registry automatically sends the supergraph schema to an internal service within Studio called Apollo Uplink

Step 5: The router polls Uplink for the latest supergraph schema

Next, we need to create another server for the router, which we connect to the supergraph created in Studio in step 2.

The router automatically polls Uplink periodically to see if there's a new version of the supergraph schema.

Most of the time, the router sees that the supergraph schema stored in Uplink is the same version as the one it's already using. In this case, nothing changes.

But if the router sees that Uplink contains a new version of the supergraph schema, the router automatically updates to use the new version—with no need to restart the server, and no downtime!

Step 5: The router polls Uplink for the latest supergraph schema

Now, any clients that communicate with the router will be able to reference and query the updated schema. But let's come back to that.

Here is the full managed federation workflow with the supergraph:

The full managed federation workflow

Practice

Managed federation process
Every supergraph includes one or more 
 
, each of which has its own schema. With 
 
, each of these schemas is published to the Apollo schema registry. Whenever a subgraph schema is published, the schema registry triggers a process called 
 
. If successful, this process results in the creation of a 
 
, which is then fetched by the supergraph's 
 
 via periodic polling.

Drag items from this box to the blanks above

  • composition

  • data source

  • supergraph schema

  • version control

  • subgraphs

  • resolvers

  • managed federation

  • construction

  • Apollo Uplink

  • router

To pick up a draggable item, press the space bar. While dragging, use the arrow keys to move the item. Press space again to drop the item in its new position, or press escape to cancel.

Key takeaways

  • After creating or updating a subgraph schema, developers use the Rover CLI to publish the subgraph schema to the Apollo schema registry.
  • The Apollo schema registry composes the subgraph schemas into a supergraph schema, which the router uses to resolve incoming client requests.
  • With managed federation, schema updates to the router are managed by GraphOS and happen with zero downtime.

Up next

Awesome, we've learned how the subgraphs we've built are going to fit into our federated architecture. We're ready to get back to FlyBy and apply what we've learned.

Next up, we're going to use the Rover CLI to publish our subgraph schemas.

Previous
Next

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.

              subgraphs

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              managed federation

              A managed approach to supergraph composition and deployment. With managed federation, subgraphs publish their schemas to GraphOS, which validates, composes, and deploys the supergraph schema.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              managed federation

              A managed approach to supergraph composition and deployment. With managed federation, subgraphs publish their schemas to GraphOS, which validates, composes, and deploys the supergraph schema.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              GraphOS

              A platform for building and managing a supergraph. It provides a management plane to test and ship changes and runtime capabilities to secure and monitor the graph.

              GraphOS Router

              A scalable runtime for supergraphs that's fully integrated with GraphOS and based on the Apollo Router Core. Can be cloud- or self-hosted.

              managed federation

              A managed approach to supergraph composition and deployment. With managed federation, subgraphs publish their schemas to GraphOS, which validates, composes, and deploys the supergraph schema.

              subgraphs

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              GraphOS Studio

              The web interface for GraphOS, which provides graph, variant, and organization management, metrics visualization, schema pipeline tools and more.

              subgraph schemas

              A schema for a subgraph server. A subgraph schema must be compliant with the GraphQL and Apollo Federation specs to be composed into a supergraph.

              subgraph schemas

              A schema for a subgraph server. A subgraph schema must be compliant with the GraphQL and Apollo Federation specs to be composed into a supergraph.

              Apollo Uplink

              An Apollo-hosted endpoint for serving supergraph configurations to GraphOS Router and @apollo/gateway. Also serves the Enterprise license to GraphOS Router.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              Uplink

              An Apollo-hosted endpoint for serving supergraph configurations to GraphOS Router and @apollo/gateway. Also serves the Enterprise license to GraphOS Router.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              subgraphs

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              subgraph servers

              A GraphQL server which acts as a module of a supergraph. Subgraph servers can be written in any federation-compatible language or library.

              resolvers

              A function that populates data for a particular field in a GraphQL schema. For example:

              const resolvers = {
              Query: {
              author(root, args, context, info) {
              return find(authors, { id: args.id });
              },
              },
              };
              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              subgraphs

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              subgraphs

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              Rover CLI

              Apollo's command-line interface for managing and maintaining graphs with GraphOS.

              subgraph schema

              A schema for a subgraph server. A subgraph schema must be compliant with the GraphQL and Apollo Federation specs to be composed into a supergraph.

              subgraphs

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              composition

              The process of combining subgraph schemas into a supergraph schema. A supergraph schema includes all definitions from subgraph schemas and additional metadata.

              subgraph

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              Rover

              Apollo's command-line interface for managing and maintaining graphs with GraphOS.

              composition

              The process of combining subgraph schemas into a supergraph schema. A supergraph schema includes all definitions from subgraph schemas and additional metadata.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              Apollo Uplink

              An Apollo-hosted endpoint for serving supergraph configurations to GraphOS Router and @apollo/gateway. Also serves the Enterprise license to GraphOS Router.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              Uplink

              An Apollo-hosted endpoint for serving supergraph configurations to GraphOS Router and @apollo/gateway. Also serves the Enterprise license to GraphOS Router.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              Uplink

              An Apollo-hosted endpoint for serving supergraph configurations to GraphOS Router and @apollo/gateway. Also serves the Enterprise license to GraphOS Router.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              Uplink

              An Apollo-hosted endpoint for serving supergraph configurations to GraphOS Router and @apollo/gateway. Also serves the Enterprise license to GraphOS Router.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              managed federation

              A managed approach to supergraph composition and deployment. With managed federation, subgraphs publish their schemas to GraphOS, which validates, composes, and deploys the supergraph schema.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              subgraph schema

              A schema for a subgraph server. A subgraph schema must be compliant with the GraphQL and Apollo Federation specs to be composed into a supergraph.

              subgraph schema

              A schema for a subgraph server. A subgraph schema must be compliant with the GraphQL and Apollo Federation specs to be composed into a supergraph.

              subgraph schemas

              A schema for a subgraph server. A subgraph schema must be compliant with the GraphQL and Apollo Federation specs to be composed into a supergraph.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              managed federation

              A managed approach to supergraph composition and deployment. With managed federation, subgraphs publish their schemas to GraphOS, which validates, composes, and deploys the supergraph schema.

              router

              The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

              GraphOS

              A platform for building and managing a supergraph. It provides a management plane to test and ship changes and runtime capabilities to secure and monitor the graph.

              subgraphs

              A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

              Rover CLI

              Apollo's command-line interface for managing and maintaining graphs with GraphOS.

              subgraph schemas

              A schema for a subgraph server. A subgraph schema must be compliant with the GraphQL and Apollo Federation specs to be composed into a supergraph.

              NEW COURSE ALERT

              Introducing Apollo Connectors

              Connectors are the new and easy way to get started with GraphQL, using existing REST APIs.

              Say goodbye to GraphQL servers and resolvers—now, everything happens in the schema!

              Take the course