GraphOS Router Features
Use router features enabled by GraphOS and the Enterprise plan
A router connected to GraphOS, whether cloud-hosted or self-hosted, is called a GraphOS Router. It has access to specific GraphOS features depending on the connected GraphOS organization's plan. Refer to the pricing page to compare GraphOS Router features across plan types.
GraphOS Router features
The GraphOS Router supports a collection of premium features specific to GraphOS. For self-hosted GraphOS Routers, these features require an Enterprise plan .
These features include:
Real-time updates via GraphQL subscriptions
Improved performance with query batching
Authentication of inbound requests via JSON Web Token (JWT)
Authorization of specific fields and types through the
@requiresScopes
,@authenticated
, and@policy
directivesIncremental migration between subgraphs through the progressive
@override
directive .Redis-backed distributed caching of query plans and persisted queries
Redis-backed entity caching of subgraph responses
Custom request handling in any language via external coprocessing
Mitigation of potentially malicious requests via request limits ,demand control , and safelisting
Custom instrumentation and telemetry, including custom attributes for spans .
An offline Enterprise license that enables running the router with Enterprise features when disconnected from the internet.
Using contexts to share data with the
@context
and@fromContext
directives
For details on these features, see this blog post in addition to the documentation links above.
Enterprise plan features
To enable support for Enterprise features in GraphOS Router:
Your organization must have a GraphOS Enterprise plan .
You must run GraphOS Router v1.12 or later. Download the latest version.
Certain Enterprise features might require a later router version. See a particular feature's documentation for details.
Your router instances must connect to GraphOS with a graph API key and graph ref associated with your organization.
You connect your router to GraphOS by setting these environment variables when starting the router.
If your router already connects to your GraphOS Enterprise organization, no further action is required.
After enabling support, you can begin using all Enterprise features .
The Enterprise license
Whenever your router instance starts up and connects to GraphOS, it fetches a license, which is the credential that authorizes its use of Enterprise features:
A router instance retains its license for the duration of its execution. If you terminate a router instance and then later start a new instance on the same machine, it must fetch a new license.
Licenses are served via Apollo Uplink , the same multi-cloud endpoint that your router uses to fetch its supergraph schema from GraphOS. Because of this, licenses introduce no additional network dependencies, meaning your router's uptime remains unaffected. To learn more about multi-cloud Uplink, read the Apollo blog post .
A router instance's license is valid for the duration of your organization's current subscription billing period (plus a grace period ), even if the router temporarily becomes disconnected from GraphOS.
Offline Enterprise licenseSince 1.37.0
Running your GraphOS 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 GraphOS 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 the GraphOS schema delivery pipeline for supergraph CI (schema checks, linting, contracts, etc.).
An offline license can be retrieved from GraphOS with the rover license fetch
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.
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 GraphOS Router
Follow these steps to configure an GraphOS Router to use an offline Enterprise license:
Fetch an offline license by running
rover license fetch
with the ID of the graph from which you want to fetch a license:Bash1rover license fetch --graph-id <apollo-graph-id>
Provide the offline license to your router on startup. The router accepts an offline license in a few ways:
--license <license_path>
CLI option, with an argument containing an absolute or relative path to an offline license fileAPOLLO_ROUTER_LICENSE_PATH
environment variable, containing an absolute or relative path to an offline license fileAPOLLO_ROUTER_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 withrover dev
, you must use environment variables to provide your offline license.
Configure the router to use a local supergraph schema by setting one of the following:
--s/-supergraph
CLI option, with an argument containing an absolute or relative path to supergraph schema fileAPOLLO_SUPERGRAPH_PATH
environment variable, containing an absolute or relative path to supergraph schema fileAPOLLO_SUPERGRAPH_URLS
environment variable, containing URLs to supergraph schemas
(Recommended) Configure the router to report usage metrics to GraphOS in a best-effort basis by setting both the
APOLLO_KEY
andAPOLLO_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 GraphOS Router instance on your local machine, such as with the rover dev
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.
You can use Enterprise router features with a locally composed supergraph schema! To do so, your router must still connect to GraphOS to obtain its license .
Set up local development
These steps work both for running the router executable directly (./router
) and for running it via rover dev
:
Create a new variant for your supergraph that you'll use only to fetch Enterprise licenses.
Give the variant a name that clearly distinguishes it from variants that track schemas and metrics.
Every team member that runs a router locally can use this same variant.
When you create this variant, publish a dummy subgraph schema like the following (your router won't use it):
GraphQL1type Query { 2 hello: String 3}
Create a graph API key for your supergraph and assign it the Contributor role.
We recommend creating a separate graph API key for each team member that will run the router locally.
When you start up your local router with your usual command, set the
APOLLO_GRAPH_REF
andAPOLLO_KEY
environment variables for that command:Bash1APOLLO_GRAPH_REF="..." APOLLO_KEY="..." ./router --supergraph schema.graphql
The value of
APOLLO_GRAPH_REF
is the graph ref for the new, license-specific variant you created (e.g.,docs-example-graph@local-licenses
).The value of
APOLLO_KEY
is the graph API key you created.
Your router will fetch an Enterprise license while using its locally composed supergraph schema.
Common errors
If your router doesn't successfully connect to GraphOS, it logs an error that begins with one of the following strings if any Enterprise features are enabled:
Error Message | Description |
---|---|
Not connected to GraphOS. | At least one of the APOLLO_KEY and APOLLO_GRAPH_REF environment variables wasn't set on router startup. |
License not found. | The router connected to GraphOS with credentials that are not associated with a GraphOS Enterprise plan. |
License has expired. | Your organization's GraphOS Enterprise subscription has ended. Your router will stop processing incoming requests at the end of the standard grace period . |
Disabling Enterprise features
To disable an Enterprise feature, remove all of its associated configuration keys from your router's YAML config file .
Grace period for expired plans
If your organization terminates its GraphOS Enterprise subscription, your router's Enterprise license is considered expired at the end of your final paid subscription period. GraphOS provides a grace period for expired licenses so that you can disable Enterprise features before they produce breaking errors in your router.
If your router has an expired Enterprise license, its behavior degrades according to the following schedule, if any Enterprise features are still enabled:
For the first 14 days after your license expires, your router continues to behave as though it has a valid license.
After 14 days, your router begins a soft outage: it continues processing client requests, but it emits logs and metrics that indicate it's experiencing an outage.
After 28 days, your router begins a hard outage. It no longer processes incoming client requests and continues emitting logs and metrics from the soft outage.
Your router resumes normal functioning whenever you renew your GraphOS Enterprise subscription or disable all Enterprise features .