Enterprise features for the Apollo Router
Available with GraphOS Enterprise
The Apollo Router provides expanded performance, security, and customization features for organizations with a GraphOS Enterprise plan.
You can test out these features for free with an Enterprise trial.
List of features
- Real-time updates via GraphQL subscriptions
- Authentication of inbound requests via JSON Web Token (JWT)
- Authorization of specific fields and types through the
@requiresScopes
and@authenticated
directives - Redis-backed distributed caching of query plans and persisted queries
- Custom request handling in any language via external coprocessing
- Mitigation of potentially malicious requests via operation limits and safelisting with persisted queries
Articles specifically about Enterprise features are marked with a ❖ icon in the left navigation.
For details on these features, see this blog post in addition to the documentation links above.
Enabling Enterprise features
To enable support for Apollo Router Enterprise features:
- Your organization must have a GraphOS Enterprise plan.
- You must run v1.12 or later of the Apollo Router. Download the latest version.
- Certain Enterprise features might require a later router version. See a particular feature's documentation for details.
- Your Apollo 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. Consult the documentation for each feature to learn more.
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.
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.
Licenses with local development
While building your supergraph, you might run an Apollo Router instance on your local machine (such as with the rover dev
command). It's likely that this router instance doesn't currently connect to GraphOS, because it obtains its supergraph schema via another mechanism. For example, rover dev
performs composition locally after introspecting your running subgraphs, which might change frequently as you develop.
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.
Setup
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):
type Query {hello: String}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:APOLLO_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.
- The value of
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. |
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.
You disable an Enterprise feature by removing all of its associated configuration keys from your router's YAML config file.