Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify required version for graphql library, plus other edits #1946

Merged
merged 1 commit into from
Jun 30, 2022
Merged

Clarify required version for graphql library, plus other edits #1946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 6 additions & 14 deletions docs/source/federated-types/composition.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,7 @@ The [Rover CLI](https://www.apollographql.com/docs/rover/) supports a `supergrap
rover supergraph compose --config ./supergraph-config.yaml
```

> ⚠️ **Important:** To perform Federation 2 composition with Rover, the YAML `--config` file you provide must include the following line:
>
> ```yaml title="supergraph-config.yaml"
> federation_version: 2
> ```
>
> Otherwise, Rover uses Federation 1 composition.

To learn how to install Rover and use this command, see the [Quickstart](../quickstart/setup/#1-install-the-rover-cli).
To learn how to install Rover and use this command, see the [quickstart](../quickstart/setup/#1-install-the-rover-cli).

### Automatically with managed federation

Expand All @@ -62,7 +54,7 @@ graph LR;
class uplink secondary;
```

To learn how to perform composition with managed federation, see the [Quickstart](../quickstart/studio-composition/).
To learn how to perform composition with managed federation, see the [quickstart](../quickstart/studio-composition/).

## Breaking composition

Expand Down Expand Up @@ -253,7 +245,7 @@ This is a useful solution when a type corresponds closely to an entry in a data

If a particular GraphQL type is defined _differently_ by different subgraphs, composition uses one of two strategies to merge those definitions: **union** or **intersection**.

* **Union**: The supergraph schema includes _all_ parts of _all_ subgraph definitions for the type.
* **Union**: The supergraph schema includes _all_ parts of _all_ subgraph definitions for the type.
* **Intersection:** The supergraph schema includes _only_ the parts of the type that are present in _every_ subgraph that defines the type.

The merging strategy that composition uses for a particular type depends on the type, as described below.
Expand Down Expand Up @@ -373,7 +365,7 @@ As you can see, the supergraph schema includes only the input fields and argumen

### Enums

Composition might use the union strategy _or_ the intersection strategy when merging enum type definitions, _depending on how the enum is used_.
Composition might use the union strategy _or_ the intersection strategy when merging enum type definitions, _depending on how the enum is used_.

```mermaid
graph TB;
Expand Down Expand Up @@ -420,7 +412,7 @@ enum Color {
}
```

If you use an enum as _either_ a field argument or an input field's return type in at least one of your subgraphs, composition merges using the [intersection strategy](#merging-types-from-multiple-subgraphs).
If you use an enum as _either_ a field argument or an input field's return type in at least one of your subgraphs, composition merges using the [intersection strategy](#merging-types-from-multiple-subgraphs).

Let's say we add a new field to Subgraph A that uses our `Color` enum as a field argument:

Expand Down Expand Up @@ -495,4 +487,4 @@ enum Color {
type ColorQuery {
avatar(borderColor: Color): String
}
```
```
6 changes: 3 additions & 3 deletions docs/source/federated-types/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Federated schemas
description: Overview
---

A federated graph uses multiple "types" of GraphQL schemas:
A federated supergraph uses multiple "types" of GraphQL schemas:

```mermaid
graph TB;
Expand All @@ -21,9 +21,9 @@ graph TB;

* **Subgraph schemas.** Each **subgraph** has a distinct schema that indicates _which_ types and fields of your composed **supergraph** it can resolve.
* These are the only schemas that your teams define manually.
* **Supergraph schema.** This schema combines all of the types and fields from your subgraph schemas, _plus_ some Federation-specific information that tells your gateway which subgraphs can resolve which fields.
* **Supergraph schema.** This schema combines all of the types and fields from your subgraph schemas, _plus_ some federation-specific information that tells your gateway which subgraphs can resolve which fields.
* This schema is the result of performing [composition](./composition/) on your collection of subgraph schemas.
* **API schema.** This schema is like the supergraph schema, but it _omits_ types, fields, and directives that are considered "machinery" and are not part of your public API (this includes Federation-specific information).
* **API schema.** This schema is similar to the supergraph schema, but it _omits_ federation-specific types, fields, and directives that are considered "machinery" and are not part of your public API.
* This is the schema that your gateway exposes to clients, who don't need to know internal implementation details about your graph.

Let's look at an example!
Expand Down
17 changes: 10 additions & 7 deletions docs/source/federation-2/moving-to-federation-2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Upgrade your supergraph incrementally at any pace

You can (and should!) move your Apollo Federation 1 supergraph to Federation 2 **incrementally**, one component at a time. Your supergraph will work as expected after each step in the process, even if some of your subgraphs continue using Federation 1 schemas.

Each individual step of moving your supergraph has its own benefits, so it's useful to complete as many steps as you're ready to complete. You can always complete the rest later.
Each individual step of moving your supergraph has its own benefits, so it's useful to complete as many steps as you're ready to complete. You can always finish the rest later.

Here are the three steps for moving to Federation 2:

Expand All @@ -18,23 +18,26 @@ graph LR;
composition --> subgrahs(Update individual subgraphs);
```

1. Update your gateway to a version that supports Federation 2 (or swap out your gateway for the [Apollo Router](/router/)).
1. Update your gateway to a version that supports Federation 2.
* Alternatively, you can swap out your Node.js gateway for the [Apollo Router](/router/).
2. Begin composing your supergraph schema with Federation 2 composition logic.
3. Update your individual subgraphs to use Federation 2 features and directives.

Steps 1 and 2 are quick, and it's straightforward to reverse them if you need to for any reason. Step 3 requires schema changes that _remove_ backward compatibility with Federation 1. Because of this, we recommend first completing it with a test instance of your graph.

> If you encounter an issue while moving your supergraph to Federation 2, please describe the issue in the [community forums](https://community.apollographql.com/).

## Step 1: Update `@apollo/gateway`
## Step 1: Update your gateway

The `@apollo/gateway` library supports Federation 2 supergraph schemas in version `2.0.0` and later. You can install the latest version in your gateway project with the following command:
The `@apollo/gateway` library supports Federation 2 supergraph schemas in version `2.0.0` and later. These versions of `@apollo/gateway` require version `16.0.0` or later of the `graphql` library.

You can install updated versions of these libraries in your gateway project with the following command:

```bash
npm install @apollo/gateway
npm install @apollo/gateway graphql
```

Alternatively, you can _swap out_ your supergraph's gateway for the **Apollo Router**, a high-performance graph router implemented in Rust. [See the docs.](/router/migrating-from-gateway/)
Alternatively, you can _swap out_ your Node.js gateway for the **Apollo Router**, a high-performance graph router implemented in Rust. [See the docs.](/router/migrating-from-gateway/)

> Both `@apollo/gateway` v2.x _and_ the Apollo Router support Federation 1! You can update to either without making any other changes, and your Federation 1 supergraph will work as expected.

Expand Down Expand Up @@ -62,7 +65,7 @@ Open the Settings page for the variant you want to move to Federation 2, then se

Click **Edit Configuration**. The following dialog appears:

<img class="screenshot" alt="Edit supported directives in Studio" src="../images/set-federation-version.jpg" width="600"/>
<img class="screenshot" alt="Edit supported directives in Studio" src="../images/set-federation-version.jpg" width="500"/>

In the Federation Version dropdown, select **Federation 2** and click **Save**.

Expand Down
3 changes: 2 additions & 1 deletion docs/source/gateway.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
title: Implementing the gateway
description: In a federated supergraph
---

> 📣 **The Apollo Router** is a new high-performance graph router written in Rust that is currently in preview. You can try out the Apollo Router in place of the Apollo Gateway documented here. [See the documentation.](https://www.apollographql.com/docs/router/)
> 📣 **The Apollo Router** is a new high-performance graph router written in Rust. You can use the Apollo Router in place of the Node.js gateway documented here. [See the documentation.](https://www.apollographql.com/docs/router/)

After you set up at least one federation-ready [subgraph](./subgraphs/), you can configure a **gateway** to sit in front of your subgraphs. The gateway serves as the entry point to your supergraph, and it executes incoming operations across one or more of your subgraphs.

Expand Down
4 changes: 2 additions & 2 deletions docs/source/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import FederationArchitecture from '../shared/diagrams/federation-architecture.m
>
> Docs for Federation 1 are [available here](/federation/v1/).

**Apollo Federation** is a powerful, open architecture that helps you create a **unified supergraph** that combines multiple GraphQL APIs:
**Apollo Federation** is a powerful, open architecture for creating a **supergraph** that combines multiple GraphQL APIs:

```mermaid
graph BT;
Expand Down Expand Up @@ -127,7 +127,7 @@ graph BT;

* The gateway is one of the following:
* An instance of Apollo Server using special extensions from the [`@apollo/gateway`](./api/apollo-gateway) library
* An instance of [the Apollo Router](https://www.apollographql.com/docs/router/), a highly performant Rust-based graph router that is currently in public preview
* An instance of [the Apollo Router](https://www.apollographql.com/docs/router/): a high-performance, Rust-based graph router
* Subgraphs can run Apollo Server using special extensions from the [`@apollo/subgraph`](./api/apollo-subgraph) library, _or_ they can run any other [subgraph-compatible GraphQL server](./other-servers/). Different subgraphs in the same supergraph can even use different server libraries.


Expand Down
3 changes: 2 additions & 1 deletion docs/source/other-servers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
title: Subgraph-compatible server libraries
description: For use in a federated supergraph
---

The following open-source GraphQL server libraries support acting as a subgraph in a federated graph, and their support is tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility). Check out the repository for details on the compatibility tests listed in the table below.
The following open-source GraphQL server libraries support acting as a subgraph in a federated supergraph, and their support is tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility). Check out the repository for details on the compatibility tests listed in the table below.

> To add a library to this list, feel free to open an [issue](https://github.com/apollographql/apollo-federation-subgraph-compatibility/issues) or check out the [Apollo Federation Library Maintainers Implementation Guide](https://github.com/apollographql/apollo-federation-subgraph-compatibility/blob/main/CONTRIBUTORS.md) to learn how to submit a PR for your library!

Expand Down
5 changes: 3 additions & 2 deletions docs/source/subgraphs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
---
title: Implementing subgraphs
description: In a federated supergraph
---

import FederationArchitecture from '../shared/diagrams/federation-architecture.mdx';

This article demonstrates how to create a **subgraph** for a federated supergraph using Node.js and Apollo Server.

> To create a subgraph using a different language and/or framework, see the list of [subgraph-compatible libraries](./other-servers/). Note that not all libraries provide full support for Federation features.
> To create a subgraph using a different language and/or framework, see the list of [subgraph-compatible libraries](./other-servers/). Note that not all listed libraries provide full support for Federation features.

## Defining a subgraph

Expand Down Expand Up @@ -202,7 +203,7 @@ Because of the power and flexibility of the [`Query._entities` and `Query._servi

<FederationArchitecture />

Make sure to implement any necessary firewall rules, access control lists, or other measures to ensure that individual subgraphs can be accessed _only_ via the gateway. We also recommend that subgraphs do not enable CORS (or at least do not use the wildcard `access-control-allow-origin: *` header) so that attackers cannot use a victim's browser to access the subgraph directly. With Apollo Server, this means disabling the default "wildcard" CORS policy which is appropriate for most publicly-exposed servers but not for inaccessible servers. See [the Apollo Server CORS documentation](/apollo-server/security/cors/#choosing-cors-options-for-your-project) for more details.
Make sure to implement any necessary firewall rules, access control lists, or other measures to ensure that individual subgraphs can be accessed _only_ via the gateway. We also recommend that subgraphs do not enable CORS (or at least do not use the wildcard `access-control-allow-origin: *` header) so that attackers cannot exploit a user's browser to access the subgraph directly. With Apollo Server, this means disabling the default "wildcard" CORS policy which is appropriate for most publicly-exposed servers but not for inaccessible servers. See [the Apollo Server CORS documentation](/apollo-server/security/cors/#choosing-cors-options-for-your-project) for more details.

## Subgraph-specific fields

Expand Down