Setting up managed federation

This tutorial describes how to set up Apollo Graph Manager for a data graph that uses Apollo Federation.

As with all changes, you should first set up managed federation in a non-production environment, such as staging. To support this, you can use variants, which are distinct versions of the same data graph for different environments.

1. Register your implementing services

To enable managed federation, each of your data graph's implementing services must register its schema with Graph Manager:

To get set up with schema registration, do the following for each of your implementing services:

1. Complete the prerequisites in the dropdown below. However, only create a single graph in Graph Manager. All of your implementing services register their schema with the same graph.
2. How to configure an Apollo project
3. In each service's apollo.config.js file, add a name field to the service object. This value must match the name of the graph in Graph Manager that your services belong to.

apollo.config.js
module.exports = {
  service: {
    name: "docs-example-graph",localSchemaFile: "schema.gql"
  }
};

1. Obtain the following values, which are required for the apollo service:push command:
   • The URL that your gateway will use to communicate with each service (e.g., http://products-graphql.svc.cluster.local:4001/)
   • The name that will uniquely identify each service within your graph (e.g., Products)
2. Now you can run the apollo service:push command with the necessary options from each service's root directory.

2. Configure continuous delivery

With managed federation, Graph Manager composes your individual service schemas into a single federated schema, just like your gateway does. Consequently, each service in your data graph must re-register its schema every time the schema changes. Otherwise, your gateway can't obtain the latest configuration from Graph Manager.

The best way to accomplish this is to add the apollo service:push call to your continuous delivery pipeline. Every time you deploy a schema change to production, this call should automatically accompanythat deploy.

3. Modify the gateway

Because your gateway isn't responsible for fetching your implementing service schemas anymore, you need to modify its initialization.

This section assumes you are using Apollo Server with the @apollo/gateway library as your gateway.

Remove the serviceList argument

A bare-bones initialization of an ApolloGateway object (without managed federation) looks like this:

const gateway = new ApolloGateway({
  serviceList: [
    { name: 'Products', url: 'http://products-graphql.svc.cluster.local:4001/' },
    // Additional services defined here
  ],
});

The serviceList argument specifies the name and URL for each of your implementing services. With managed federation, your gateway obtains this information from Graph Manager instead.

Remove the serviceList argument from your ApolloGateway constructor entirely:

const gateway = new ApolloGateway();

Connect the gateway to Graph Manager

Like your implementing services, your gateway uses an API key to identify itself to Graph Manager. Obtain a graph API key from your graph's Settings page in the Graph Manager UI.

Provide your API key to your gateway by setting it as the value of the ENGINE_API_KEY environment variable in your gateway's environment. Apollo Server will automatically read this environment variable on startup.

Note that if you specify the API key in a .env file, the gateway does not automatically read this file. Use a library such as dotenv.

When running your gateway in an environment where outbound traffic to the internet is restricted, consult the directions for configuring a proxy within Apollo Server.

4. Deploy the modified gateway

You can now deploy your modified gateway to begin fetching your federated schema from Graph Manager instead of directly from your services.

On startup, your gateway will use its API key to access its federation config from Google Cloud Storage. After it completes schema composition based on the config, the gateway can begin executing operations across your implementing services.

Previous: Managed federation overview
Next: Advanced topics for managed federation