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

docs: offline license #5715

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: offline license #5715

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
25 changes: 2 additions & 23 deletions docs/source/configuration/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router

The graph ref for the GraphOS graph and variant that the router fetches its supergraph schema from (e.g., `docs-example-graph@staging`).

**Required** when using [managed federation](/federation/managed-federation/overview/), except when using an [offline license](#--license) to run the router.
**Required** when using [managed federation](/federation/managed-federation/overview/).

</td>
</tr>
Expand All @@ -49,7 +49,7 @@ The graph ref for the GraphOS graph and variant that the router fetches its supe

The [graph API key](/graphos/api-keys/#graph-api-keys) that the router should use to authenticate with GraphOS when fetching its supergraph schema.

**Required** when using [managed federation](/federation/managed-federation/overview/), except when using an [offline license](#--license) to run the router.
**Required** when using [managed federation](/federation/managed-federation/overview/).

</td>
</tr>
Expand Down Expand Up @@ -169,27 +169,6 @@ The default value is `info`.
<tr>
<td style="min-width: 150px;">

##### `--license`

`APOLLO_ROUTER_LICENSE_PATH`, `APOLLO_ROUTER_LICENSE`

</td>
<td>

An offline GraphOS Enterprise license. Enables Enterprise router features when disconnected from GraphOS.

An offline license is specified either as an absolute or relative path to a license file (`--license <license_path>` or `APOLLO_ROUTER_LICENSE_PATH`), or as the stringified contents of a license (`APOLLO_ROUTER_LICENSE`).

When not set, the router retrieves an Enterprise license [from GraphOS via Apollo Uplink](../enterprise-features/#the-enterprise-license).

For information about fetching an offline license and configuring the router, see [Offline Enterprise license](../enterprise-features/#offline-enterprise-license).

</td>
</tr>

<tr>
<td style="min-width: 150px;">

##### `--apollo-uplink-endpoints`

`APOLLO_UPLINK_ENDPOINTS`
Expand Down
6 changes: 1 addition & 5 deletions docs/source/configuration/persisted-queries.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ persisted_queries:

<ExperimentalFeature />

Adding `experimental_local_manifests` to your `persisted-queries` configuration lets you use local persisted query manifests instead of the hosted Uplink version. This is helpful when you're using an offline Enterprise license and can't use Uplink. With the `experimental_local_manifests`, the router doesn't reload the manifest from the file system, so you need to restart the router to apply changes.
Adding `experimental_local_manifests` to your `persisted-queries` configuration lets you use local persisted query manifests instead of the hosted Uplink version. With the `experimental_local_manifests`, the router doesn't reload the manifest from the file system, so you need to restart the router to apply changes.

```yaml title="router.yaml"
persisted_queries:
Expand Down Expand Up @@ -135,7 +135,3 @@ apq:
To enable safelisting, you _must_ turn off [automatic persisted queries](./in-memory-caching#caching-automatic-persisted-queries-apq) (APQs). APQs let clients [register arbitrary operations at runtime](/graphos/operations/persisted-queries/#differences-from-automatic-persisted-queries) while safelisting restricts operations to those that have been explicitly registered.

</Note>

## Limitations

* **Unsupported with offline license**. An Apollo Router using an [offline Enterprise license](../enterprise-features/#offline-enterprise-license) cannot use safelisting with persisted queries. The feature relies on Apollo Uplink to fetch persisted query manifests, so it doesn't work as designed when the router is disconnected from Uplink.
63 changes: 1 addition & 62 deletions docs/source/enterprise-features.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Enterprise Features of the Apollo Router
subtitle: Connect the router to GraphOS for advanced features
description: Unlock Enterprise features for the Apollo Router by connecting it to GraphOS. Enable offline licenses for extended disconnections.
description: Unlock Enterprise features for the Apollo Router by connecting it to GraphOS.
---

Since the Apollo Router is [source-available](https://www.apollographql.com/blog/evaluating-apollo-router-understanding-free-and-open-vs-commercial-features), you can use its codebase without connecting it to GraphOS. GraphOS organizations with the Enterprise plan can [connect a self-hosted router to GraphOS](/graphos/quickstart/self-hosted#6-connect-the-router-to-graphos) for an expanded feature set.
Expand Down Expand Up @@ -60,67 +60,6 @@ Licenses are served via [Apollo Uplink](/federation/managed-federation/uplink/),

A router instance's license is valid for the duration of your organization's current subscription billing period (plus a [grace period](#grace-period-for-expired-plans)), even if the router temporarily becomes disconnected from GraphOS.

<MinVersion version="1.37.0">

### Offline Enterprise license

</MinVersion>

<Tip>

Offline Enterprise license support is available on an as-needed basis. Send a request to your Apollo contact to enable it for your GraphOS Studio organization.

</Tip>

Running your Apollo Router fleet while fully connected to GraphOS is the best choice for most Apollo users. However, some scenarios can prevent your routers from connecting to GraphOS for an extended period, ranging from disasters that break connectivity to isolated sites operating with air-gapped networks. If you need to restart or rapidly scale your entire router fleet, but you're unable to communicate with Apollo Uplink, new router instances won't be able to serve traffic.

To support long-term disconnection scenarios, GraphOS supports **offline Enterprise licenses** for the Apollo Router. An offline license enables routers to start and serve traffic without a persistent connection to GraphOS. The functionality available with an offline license is much like being fully connected to GraphOS, including managed federation for supergraph CI (operation checks, schema linting, contracts, etc.).

An offline license can be retrieved from GraphOS with the [`rover license fetch`](/rover/commands/license) command.

With an offline license, a router can either be fully disconnected from GraphOS or configured to connect to GraphOS on a best-effort basis so that it can send graph usage metrics. Apollo recommends configuring your router to report graph usage metrics to GraphOS whenever possible. Since your router sends metrics in a best-effort fashion, it incurs no performance or uptime penalties while enabling several powerful GraphOS features, such as operation checks, field insights, operation traces, and contracts.

<Note>

A router using an offline license requires [the use of local manifests](./configuration/persisted-queries/#experimental_local_manifests) when using [safelisting with persisted queries](./configuration/persisted-queries), otherwise it will not work as designed when the router is disconnected from Uplink.

</Note>

An offline license is valid for the lesser of the duration of your contract with Apollo, or one year, with an added grace period of 28 days. You are responsible for keeping your offline license files up to date within your infrastructure by rerunning `rover license fetch` to fetch updated license files.

#### Set up offline license for the Apollo Router

Follow these steps to configure an Apollo Router to use an offline Enterprise license:

1. Fetch an offline license by running [`rover license fetch`](/rover/commands/license/#license-fetch) with the ID of the graph from which you want to fetch a license:

```bash
rover license fetch --graph-id <apollo-graph-id>
```

1. Provide the offline license to your router on startup. The router accepts an offline license in a few ways:

1. [`--license <license_path>`](./configuration/overview/#--license) CLI option, with an argument containing an absolute or relative path to an offline license file
1. [`APOLLO_ROUTER_LICENSE_PATH`](./configuration/overview/#--license) environment variable, containing an absolute or relative path to an offline license file
1. [`APOLLO_ROUTER_LICENSE`](./configuration/overview/#--license) environment variable, containing the stringified contents of an offline license file

<Note>

- The router checks the CLI option and environment variables in the listed order, then it uses the value of the first option or variable that is set.
- The `--license <license_path>` option is only available when running the router binary. When running a router with `rover dev`, you must use environment variables to provide your offline license.

</Note>

1. Configure the router to use a local supergraph schema by setting one of the following:

* [`--s/-supergraph`](./configuration/overview/#-s----supergraph) CLI option, with an argument containing an absolute or relative path to supergraph schema file
* [`APOLLO_SUPERGRAPH_PATH`](./configuration/overview/#-s----supergraph) environment variable, containing an absolute or relative path to supergraph schema file
* [`APOLLO_SUPERGRAPH_URLS`](./configuration/overview/#-s----supergraph) environment variable, containing URLs to supergraph schemas

1. (**Recommended**) Configure the router to report usage metrics to GraphOS in a best-effort basis by setting both the [`APOLLO_KEY`](./configuration/overview/#apollo_key) and [`APOLLO_GRAPH_REF`](./configuration/overview#apollo_graph_ref) environment variables.

These metrics are necessary for several important GraphOS features (operations checks, field insights, operation traces, contracts). Sending them best-effort incurs no performance or uptime penalties.

### Licenses with local development

You might also need to run an Apollo Router instance on your local machine, such as with the [`rover dev`](/graphos/graphs/local-development) command. It's likely that your local router instance doesn't connect to GraphOS to get its supergraph schema from Uplink. For example, you can run `rover dev` to perform composition locally.
Expand Down
Loading