Docs
Launch GraphOS Studio

Apollo Uplink

Fetch your managed router's configuration


When using managed federation, your 's by default regularly polls an endpoint called Apollo Uplink for its latest and other configuration:

Apollo GraphOS
Your infrastructure
Publishes
schema
Publishes
schema
Updates
config
Polls for config changes
Schema Registry
Uplink
Products subgraph
Reviews subgraph
Router

If you're using Enterprise features, Uplink also serves your 's license.

To maximize uptime, Uplink is hosted simultaneously at two endpoints, one in GCP and one in AWS:

  • GCP: https://uplink.api.apollographql.com/
  • AWS: https://aws.uplink.api.apollographql.com/

Default polling behavior

Apollo Router

If you use the with , by default it polls Uplink every ten seconds. Every time it does so, it cycles through Uplink endpoints in round-robin fashion.

Whenever a poll request times out or otherwise fails (the default timeout is thirty seconds), the continues polling as usual at the next interval. In the meantime, it continues using its most recent successfully obtained configuration.

@apollo/gateway

If you use the @apollo/gateway library with , by default your gateway polls Uplink every ten seconds. Every time it does so, it cycles through Uplink endpoints in round-robin fashion.

Versions of @apollo/gateway prior to v0.45.0 don't support multiple Uplink endpoints and only use the GCP endpoint by default.

Whenever a poll request fails, the gateway retries that request (again, using round robin). It continues retrying until a request succeeds, or until reaching the defined maximum number of retries.

Even if a particular poll request fails all of its retries, the gateway continues polling as usual at the next interval (with its own set of retries if needed). In the meantime, the gateway continues using its most recent successfully obtained configuration.

Configuring polling behavior

You can configure the following aspects of your 's Uplink polling behavior:

  • The interval at which your polls (minimum ten seconds)
  • The list of Uplink URLs your uses
  • The request timeout for each poll request ( only)
    • For @apollo/gateway, this value is always thirty seconds.
  • The number of retries performed for a failed poll request (@apollo/gateway only)
    • The does not perform retries for a failed poll request. It continues polling at the next interval.

Apollo Router

You configure Uplink polling for the by providing certain command-line options when running the router executable. These options all start with --apollo-uplink.

See the Apollo Router docs.

@apollo/gateway

Retry limit

You can configure how many times your gateway retries a single failed poll request like so:

const { ApolloGateway } = require('@apollo/gateway');
// ...
const gateway = new ApolloGateway({
uplinkMaxRetries: 2
});

By default, the gateway retries a single poll request a number of times equal to three times the number of Uplink URLs (this is almost always 6 times).

Even if a particular poll request fails all of its retries, the gateway continues polling as usual at the next interval (with its own set of retries if needed). In the meantime, the gateway continues using its most recently obtained configuration.

Poll interval

You can configure the interval at which your gateway polls Apollo Uplink like so:

const { ApolloGateway } = require('@apollo/gateway');
// ...
const gateway = new ApolloGateway({
pollIntervalInMs: 15000 // 15 seconds
});

The pollIntervalInMs option specifies the polling interval in milliseconds. This value must be at least 10000 (which is also the default value).

⚠️ Most gateways never need to configure their list of Apollo Uplink URLs. Consult this section only if advised to do so.

You can provide a custom list of URLs for the gateway to use when polling Uplink. You can provide this list either in the ApolloGateway constructor or as an environment variable.

ApolloGateway constructor

Provide a custom list of Uplink URLs to the ApolloGateway constructor like so:

const { ApolloGateway } = require('@apollo/gateway');
// ...
const gateway = new ApolloGateway({
uplinkEndpoints: [
// Omits AWS endpoint
'https://uplink.api.apollographql.com/'
]
});

This example omits the AWS endpoint, which means it's never polled.

Note that if you also provide a list of endpoints via environment variable, the environment variable takes precedence.

Environment variable

You can provide a comma-separated list of Uplink URLs as the value of the APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT environment variable in your gateway's environment:

APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT=https://aws.uplink.api.apollographql.com/,https://uplink.api.apollographql.com/

Schema size limit

provided by Uplink cannot exceed 6MB in size. The vast majority of are well below this limit.

If your does exceed 6MB, you can set up a build status webhook for your . Whenever you're notified of a successful , your webhook can fetch the latest supergraph schema via the Rover CLI.

This feature is in preview. Your questions and feedback are highly valueddon't hesitate to get in touch with your Apollo contact or on the official Apollo GraphQL Discord.

In advanced use cases, you may want your to use a different than the latest validated schema provided by Uplink. For example, you have different deployment environments for the same graph variant, and you want everything that provides except for your to use specific to their deployment environment.

For this scenario, you can follow a workflow that, instead of retrieving from Uplink, uses the GraphOS Platform API to retrieve a for a specific GraphOS launch. The workflow, in summary:

  1. When deploying your , publish your in a batch using the Platform API.
    • The Platform API triggers a (and possible downstream launches for ) and returns the launch ID (and downstream launch IDs, if necessary).
  2. Poll for the status, until the launch (and all downstream launches) has completed successfully.
  3. Retrieve the of the successful by calling the Platform API with the launch ID.
  4. Set or "pin" the to your by deploying them with the --supergraph or -s option.

For an example with calling the Platform API, see a blue-green deployment example.

Previous
Setup
Next
Federated schema checks
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company