Docs
Launch GraphOS Studio

Enterprise features for the Apollo Router

Available with GraphOS Enterprise


Since the is source-available, you can use its codebase without connecting it to . GraphOS organizations with the can connect a self-hosted router to GraphOS for an expanded feature set.

A connected to , whether cloud- or self-hosted, is called a GraphOS router. It has access to specific features depending on the connected GraphOS organization's plan. Refer to the pricing page to compare features across plan types.

💡 TIP

Try out Enterprise features for free with an Enterprise trial.

List of features

The Apollo Router supports a collection of premium features specific to . These include:

💡 TIP

Articles 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 Enterprise features:

  • Your organization must have a GraphOS Enterprise plan.
  • You must run v1.12 or later of the . Download the latest version.
    • Certain Enterprise features might require a later version. See a particular feature's documentation for details.
  • Your instances must connect to with a graph API key and graph ref associated with your organization.
    • You connect your to by setting these environment variables when starting the .
    • If your already connects to your 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 instance starts up and connects to , it fetches a license, which is the credential that authorizes its use of Enterprise features:

GraphOS
Your Infrastructure
Fetches supergraph schema
and license
Apollo Uplink
Apollo Router

A 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 uses to fetch its from . 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 instance's license is valid for the duration of your organization's current billing period (plus a grace period), even if the temporarily becomes disconnected from .

Offline Enterprise license
Since 1.37.0

💡 TIP

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

Running your fleet while fully connected to 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, supports offline Enterprise licenses for the . An offline license enables routers to start and serve traffic without a persistent connection to . The functionality available with an offline license is much like being fully connected to GraphOS, including for CI ( checks, schema linting, , etc.).

An offline license can be retrieved from with the rover license fetch command.

With an offline license, a can either be fully disconnected from 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 checks, insights, operation traces, and .

NOTE

A using an offline license cannot use safelisting with persisted queries. The feature relies on Apollo Uplink to fetch , so it doesn't work as designed when the is disconnected from Uplink.

An offline license is valid for the lesser of the duration of your 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 to use an offline :

  1. Fetch an offline license by running rover license fetch with the ID of the from which you want to fetch a license:

    rover license fetch --graph-id <apollo-graph-id>
  2. Provide the offline license to your on startup. The router accepts an offline license in a few ways:

    1. --license <license_path> CLI option, with an containing an absolute or relative path to an offline license file
    2. APOLLO_ROUTER_LICENSE_PATH environment variable, containing an absolute or relative path to an offline license file
    3. APOLLO_ROUTER_LICENSE environment variable, containing the stringified contents of an offline license file

    The 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.

  3. Configure the to use a local by setting one of the following:

    • --s/-supergraph CLI option, with an containing an absolute or relative path to file
    • APOLLO_SUPERGRAPH_PATH environment variable, containing an absolute or relative path to file
    • APOLLO_SUPERGRAPH_URLS environment variable, containing URLs to s
  4. (Recommended) Configure the to report usage metrics to in a best-effort basis by setting both the APOLLO_KEY and APOLLO_GRAPH_REF environment variables.

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

Licenses with local development

You might also need to run an instance on your local machine, such as with the rover dev command. It's likely that your local instance doesn't connect to to get its from Uplink. For example, you can run rover dev to perform locally.

You can use Enterprise router features with a locally composed supergraph schema! To do so, your must still connect to to obtain its license.

Set up local development

These steps work both for running the executable directly (./router) and for running it via rover dev:

  1. Create a new variant for your that you'll use only to fetch .

    • Give the a name that clearly distinguishes it from variants that track schemas and metrics.
    • Every team member that runs a locally can use this same .
    • When you create this , publish a dummy like the following (your won't use it):
    type Query {
    hello: String
    }
  2. Create a graph API key for your and assign it the Contributor role.

    • We recommend creating a separate API key for each team member that will run the locally.
  3. When you start up your local with your usual command, set the APOLLO_GRAPH_REF and APOLLO_KEY environment variables for that command:

    APOLLO_GRAPH_REF="..." APOLLO_KEY="..." ./router --supergraph schema.graphql
    • The value of APOLLO_GRAPH_REF is the for the new, license-specific you created (e.g., docs-example-graph@local-licenses).
    • The value of APOLLO_KEY is the API key you created.
  4. Your will fetch an while using its locally composed .

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 MessageDescription
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 's YAML config file.

Grace period for expired plans

If your organization terminates its Enterprise , your 's 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 has an expired , 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 continues to behave as though it has a valid license.
  • After 14 days, your 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 begins a hard outage. It no longer processes incoming client requests and continues emitting logs and metrics from the soft outage.

Your resumes normal functioning whenever you renew your Enterprise or disable all Enterprise features.

Previous
Federation version support
Next
Overview
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company