Federated Schema

IMPORTANT: Schema Federation is not applicable for Single Schema configurations.

Apollo Federation Support

Inigo supports composition for Apollo's GraphQL Federation implementation for both Version 1.x and Version 2.x.

Definitions

Here are helpful definitions of terms that are used in this document:

• Instance Schemas: The GraphQL supergraph and subgraph schema definitions that are deployed in your Apollo Gateway/Router and GraphQL server instances.
• Configured Schema: The GraphQL subgraph schema definition (i.e. schema.graphql) that is referenced from your Inigo Gateway or Subgraph YAML definition(s).
• Composed Schema: The GraphQL supergraph schema definition that's composed from your Inigo Gateway YAML definition.

  The Instance Supergraph Schemas and the Composed Schema will have the same exact definition after the Composed Schema is published and applied to the Apollo Gateway/Router.

• Control Plane: Where Inigo Cloud applies, processes, and tracks Inigo configurations, and that tracking includes Composed Schema and Configured Schema definitions.
• Schema Check Pipeline: Where Inigo Cloud performs the automated validations and checks of the applied Composed Schema.
• Schema Registry: Where Inigo Cloud stores versions of your Composed Schema.
• Breaking Change: The Configured Schema has changes that remove or modify parts of the schema recently used by GraphQL clients and may result in client errors if the schema changes are published.

Architecture

Figure 1 shows the architecture for how Inigo handles federated schema deployments with its schema management features. In addition to the Inigo cloud, the inigo CLI plays an essential role in reading, composing, and applying the Composed Schema and also performing the schema-checking commands.

Figure 1. Inigo Schema Management Architecture (Composed Schema Configuration)

Architecture Details

• inigo CLI enables the local composition of schemas, applying these composed schemas to the Inigo cloud, and publishing the schemas to Inigo's schema registry.
  • inigo compose is analogous to Apollo's rover supergraph compose.
• The Inigo cloud manages the composed schema versions by:
  • Comparing a new subgraph schema(s) with the previous version to determine if schema composition is feasible.
  • Employing GraphQL client usage history to identify any breaking schema changes (i.e. queries and fields used in the last 30 days).
  • Storing the composed schema in an internal schema registry in the Inigo cloud.
• Inigo's schema registry operates with GraphQL gateways, facilitating the distribution of the latest composed schema. The schema registry:
  • Retrieves the most recent schema from Inigo's cloud and publishes it to all gateways.
  • Can optionally be run as a private schema registry.

Option #1: Set Up the Federated Schema using Gateway + Subgraph

To set up Federated Schemas using Inigo, a Gateway configuration must be created and applied. The Gateway correlates to an instance of Apollo Gateway or Apollo Router that implements Apollo Federation and calls the underlying subgraph services.

A distributed approach with separate YAML configurations for each subgraph is preferred for distributed teams that are each responsible for their own subgraph deployment. With the distributed approach, each Subgraph YAML configuration can live with the actual subgraph implementation and be maintained by the subgraph owner.

Example 1 and 2 demonstrate how to set up the Gateway and Subgraph YAML configurations for the distributed approach.

kind: Gateway
name: apollo-gateway-fed-2-demo
spec:
  composition: ApolloFederation_v2

Example 1. Gateway definition for the distributed approach with separate Subgraph configurations.

kind: Subgraph
name: accounts
spec: 
  gateway: apollo-gateway-fed-2-demo
  url: "http://accounts.dev/graphql"
  schema_files:
  - ./schema.graphql

Example 2. Subgraph definition for the distributed approach that references the Gateway configuration.

IMPORTANT: The Gateway name in each subgraph configuration must match the Gateway configuration's name value.

Applying and Checking the Gateway and Subgraph Configurations

Using inigo apply, you can apply the Gateway:

inigo apply inigo/gateway.yaml --label dev

With the Gateway now applied, you can now run inigo check and inigo apply for the subgraphs.

inigo check services/products/subgraph.yaml --label dev
inigo apply services/products/subgraph.yaml --label dev

inigo check services/accounts/subgraph.yaml --label dev
inigo apply services/accounts/subgraph.yaml --label dev

inigo check services/inventory/subgraph.yaml --label dev
inigo apply services/inventory/subgraph.yaml --label dev

inigo check services/reviews/subgraph.yaml --label dev
inigo apply services/reviews/subgraph.yaml --label dev

Example 3. Checking and applying the Gateway and Subgraph configurations separately.

No-YAML Subgraph Approach

You may optionally check and apply a subgraph without a Subgraph YAML configuration using inigo subgraph. This approach would be more familiar to those currently moving from rover. Example 4 demonstrates how to run inigo subgraph check and inigo subgraph apply.

inigo subgraph check apollo-gateway-fed-2-demo --label dev --subgraph accounts --schema services/accounts/schema.graphql --url http://localhost:4001/graphql
inigo subgraph check apollo-gateway-fed-2-demo --label dev --subgraph accounts --schema services/accounts/schema.graphql --url http://localhost:4001/graphql

Example 4. Checking and applying the subgraph using inigo subgraph rather than the Subgraph YAML.

Option #2: Set Up the Federated Schema using Gateway-only

As shown in Example 5, the subgraph schema files can be directly referenced in the Gateway under the services YAML configuration. This is the centralized approach to configuring the Gateway for composition, and may be useful for small teams with a mono repo GraphQL deployment.

kind: Gateway
name: apollo-gateway-fed-2-demo
label: dev
spec:
  composition: ApolloFederation_v2
  services:
    - name: accounts
      url: "http://accounts.dev/graphql"
      schema_files:
        - ../services/accounts/schema.graphql
    - name: reviews
      url: "http://reviews.dev/graphql"
      schema_files:
        - ../services/reviews/schema.graphql
    - name: products
      url: "http://products.dev/graphql"
      schema_files:
        - ../services/products/schema.graphql
    - name: inventory
      url: "http://inventory.dev/graphql"
      schema_files:
        - ../services/inventory/schema.graphql

Example 5. A Gateway configuration referencing local subgraph schema files.

You can run inigo check and inigo apply for the Gateway configuration, as shown in Example 6.

inigo check inigo/gateway.yaml --label dev
inigo apply inigo/gateway.yaml --label dev

Example 6. Checking and applying the Gateway configuration.

In this case, the check and apply are run for all of the subgraphs the order they were defined in the Gateway configuration.

View Federated Schema Composition Results

When inigo check and inigo apply was run on each of the Subgraphs, the schema composition was run in the Inigo cloud for each command. With the multiple inigo apply commands run, multiple new schema versions will be applied. Examples are shown in Figure 2 to Figure 4.

Figure 2. Version 4 of the composed schema (primary view).

Figure 3. Version 4 of the composed schema (schema view).

Figure 4. Version 1 to 4 of the composed schema (schema comparison view).

Additionally, the schema check pipeline with validation and checks will be run for each inigo apply of the Subgraph, thus checking that the schema composition was valid and successful, as shown in Figure 5.

Figure 5. Results of the apply of Subgraph validation and checks.

Federated Schema Composition Error

If there is a composition error when inigo check or inigo apply is run, the errors will be shown with a link to the report, as shown in Example 7.

services/inventory/subgraph.yaml --label dev
Service: inventory:dev

Changelog:
----------
subgraph/schema_files  updated  

Steps:
------
Validation:   passed
Composition:  failed
Operational:  omitted
Evaluation:   omitted

Field marked @requires must have 'Product.weight' marked as @external.
        subgraph:  inventory
        location:  ./schema.graphql:9:5
        attribute: Product.shippingEstimate

Execute the below command to ignore this failure on the next run:
>  inigo bypass 6c5270bb1e98a39ea0fa131583505a4bfdb5675b

Check out the report in the UI:
https://app.inigo.io/000/config/activity/1234

error: check failed, see report above for details

Example 7. A failed composition output with a link to the report

The failed composition will also be shown in Inigo's UI, as shown in Figure 6.

Figure 6. Results of the failed schema composition in the Inigo cloud.

IMPORTANT: Because the schema composition failed in this example, the schema change will not be applied, and the existing version of the schema will remain the latest version.

Removing Subgraphs

To remove a subgraph, configure enabled: false for Gateway's services or Subgraph configurations. This will effectively remove the subgraph from the gateway.

Remove from Gateway

First, set enabled: false for the subgraph service to the Gateway configuration and run inigo apply, as shown in Example 8.

kind: Gateway
name: apollo-gateway-fed-2-demo
label: dev
spec:
  composition: ApolloFederation_v2
  services:
    - name: accounts
      enabled: false
      url: "http://accounts.dev/graphql"
      schema_files:
        - ../services/accounts/schema.graphql
    - ...

Example 8. Add enabled: false to disable the subgraph.

Next, remove the subgraph service completely from the Gateway configuration as it's no longer needed, as shown in Example 9. Then, run inigo apply to finalize the change.

kind: Gateway
name: apollo-gateway-fed-2-demo
label: dev
spec:
  composition: ApolloFederation_v2
  services:
    - ...

Example 9. Remove the subgraph from the YAML configuration.

Remove from Subgraph

First, set enabled: false for the Subgraph configuration, as shown in Example 10, and then run inigo apply.

kind: Subgraph
name: accounts
spec: 
  gateway: apollo-gateway-fed-2-demo
  enabled: false
  url: "http://accounts.dev/graphql"
  schema_files:
  - ./schema.graphql

Example 10. Add enabled: false to disable the subgraph.

Now the Subgraph configuration file can be deleted, as the subgraph has been removed from Inigo.

Next Steps

Please proceed to Schema Publishing to learn how to publish Configured Schemas.