Apollo Router

Apollo Router is the Rust implementation of the Apollo Federation runtime.

Hive ships a custom build of Apollo Gateway, because that’s how native extensions works.

With the custom build, Apollo Gateway will poll the supergraph from the high availability CDN to ensure production deployments without interruptions.

Installation

Make sure you have published all your subgraph schemas to your Federation target on the Hive registry. Once you have all subgraph schemas published and the subgraphs can be composed, the latest valid supergraph is always available via the CDN.

You also need to create a CDN Access Token, that will be used for authenticating the supergraph polling from the CDN.

Download Apollo Router for Linux (x86_64), MacOS (x86_64) or Windows (x86_64). To download the latest version of the router, use the following script:

curl -fsSL https://graphql-hive.com/apollo-router-download.sh | bash

To download a specfic version of the router, use the -v or --version flag:

curl -fsSL https://graphql-hive.com/apollo-router-download.sh | bash -s -- --version router1.57.1-plugin1.0.0

The full list of releases can be found in the releases registry page

Start the router:

HIVE_CDN_ENDPOINT="..." \ # The endpoint of your CDN access token
HIVE_CDN_KEY="..." \ # The CDN access token
  ./router

To run Apollo Router with Hive plugin, use the following Docker command.

Make sure to replace IMAGE_TAG_HERE with the image tag. You can use latest for development, or pick a specific version for production from the releases registry page.

docker run -p 4000:4000 \
  --env HIVE_CDN_ENDPOINT="..." \ # The endpoint of your CDN access token
  --env HIVE_CDN_KEY="..." \ # The CDN access token
  --rm \
  ghcr.io/graphql-hive/apollo-router:IMAGE_TAG_HERE

Passing command-line arguments:

docker run -p 4000:4000 \
  --env HIVE_CDN_ENDPOINT="..." \ # The endpoint of your CDN access token
  --env HIVE_CDN_KEY="..." \ # The CDN access token
  --rm \
  ghcr.io/graphql-hive/apollo-router:IMAGE_TAG_HERE --log debug

Creating a custom Apollo Router binary requires compiling it from source. To setup a project, please follow “Create a new project” section of “Creating a custom Apollo Router binary” guide.

Once your project is ready, update Cargo.toml file with the hive_apollo_router_plugin Crate dependency:

Cargo.toml

[dependencies]
# You can find the version additional information in Crates.io:
# https://crates.io/crates/hive-apollo-router-plugin
hive_apollo_router_plugin = "..."

Alternatively, you can point to a Git if you need a specific commit or version of the plugin:

Cargo.toml

[dependencies]
# You can use a "branch", or commit id with "rev" key
hive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }

Next, update src/main.rs file with the following content to add GraphQL Hive:

src/main.rs

  mod plugins;
 
  use anyhow::Result;
+ use hive_apollo_router_plugin::registry;
 
  fn main() -> Result<()> {
-   apollo_router::main()
+   match registry::HiveRegistry::new(None).and(apollo_router::main()) {
+     Ok(_) => {}
+     Err(e) => {
+         eprintln!("{}", e);
+         std::process::exit(1);
+     }
+   }
  }

Finally, build the binary and run it using HIVE_CDN_ENDPOINT and HIVE_CDN_KEY environment variables.

In case of any issues, please refer to the official guide or open an issue in GraphQL Hive repository.

Version Structure

The Docker image’s and the binary artifact’s versioning follows the pattern routerX.Y.Z-pluginX.Y.Z, combining both the core Apollo Router and Hive plugin versions.

For example: router1.57.1-plugin1.0.0.

You can find the list of releases in the releases registry page.

Configuration

HIVE_CDN_ENDPOINT - the endpoint Hive generated for you in the previous step
HIVE_CDN_KEY - the access key
HIVE_CDN_POLL_INTERVAL - polling interval (default is 10 seconds)
HIVE_CDN_ACCEPT_INVALID_CERTS - accepts invalid SSL certificates (default is false)
HIVE_REGISTRY_LOG - defines the log level for the registry (default is INFO)
HIVE_CDN_SCHEMA_FILE_PATH - where to download the supergraph schema (default is /<tmp-dir>/supergraph-schema.graphql)

💡

The HIVE_CDN_ENDPOINT variable should not include any artifact suffix (for example, /supergraph), it should be in the following format: https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID

Usage Reporting

You can send usage reporting to Hive registry by enabling hive.usage plugin in the config file (router.yaml).

Configuration

HIVE_TOKEN (required) - Your Registry Access Token with write permission.
HIVE_ENDPOINT (optional) - For self-hosting, you can override /usage endpoint (defaults to https://app.graphql-hive.com/usage)

Start the router:

HIVE_TOKEN="..." \
HIVE_CDN_ENDPOINT="..." \
HIVE_CDN_KEY="..." \
  ./router --config router.yaml

To run Apollo Router with Hive plugin with usage reporting, use the following Docker command.

Make sure to replace IMAGE_TAG_HERE with the image tag. You can use latest for development, or pick a specific version for production from the releases registry page.

docker run -p 4000:4000 \
  --env HIVE_TOKEN="..." \
  --env HIVE_CDN_ENDPOINT="..." \
  --env HIVE_CDN_KEY="..." \
  --mount "type=bind,source=/home/usr/src/hive/router.yaml,target=/dist/config/router.yaml" \
  --rm \
  ghcr.io/graphql-hive/apollo-router:IMAGE_TAG_HERE

To follow the same convention as Apollo Router’s official Docker image, the config file is also located at /dist/config/router.yaml.

Creating a custom Apollo Router binary requires compiling it from source. To setup a project, please follow “Create a new project” section of “Creating a custom Apollo Router binary” guide.

Once your project is ready, update Cargo.toml file with the hive_apollo_router_plugin Crate dependency:

Cargo.toml

[dependencies]
# You can find the version additional information in Crates.io:
# https://crates.io/crates/hive-apollo-router-plugin
hive_apollo_router_plugin = "..."

Alternatively, you can point to a Git if you need a specific commit or version of the plugin:

Cargo.toml

[dependencies]
# You can use a "branch", or commit id with "rev" key
hive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }

Next, update src/main.rs file with the following content to add GraphQL Hive:

src/main.rs

  mod plugins;
 
  use anyhow::Result;
+ use hive_apollo_router_plugin::registry;
+ use hive_apollo_router_plugin::usage;
 
  fn main() -> Result<()> {
-   apollo_router::main()
+   usage::register();
+   match registry::HiveRegistry::new(None).and(apollo_router::main()) {
+     Ok(_) => {}
+     Err(e) => {
+         eprintln!("{}", e);
+         std::process::exit(1);
+     }
+   }
  }

Finally, build the binary and run it using HIVE_TOKEN, HIVE_CDN_ENDPOINT and HIVE_CDN_KEY environment variables. Don’t forget to create router.yaml file with configuration for hive.usage plugin.

In case of any issues, please refer to the official guide or open an issue in GraphQL Hive repository.

router.yaml

supergraph:
  listen: 0.0.0.0:4000
plugins:
  hive.usage:
    {}
    #  Default: true
    # enabled: true
    #
    #  Sample rate to determine sampling.
    #  0.0 = 0% chance of being sent
    #  1.0 = 100% chance of being sent.
    #  Default: 1.0
    # sample_rate: "0.5",
    #
    #  A list of operations (by name) to be ignored by Hive.
    # exclude: ["IntrospectionQuery", "MeQuery"],
    #
    #  Uses graphql-client-name by default
    # client_name_header: "x-client-name",
    #  Uses graphql-client-version by default
    # client_version_header: "x-client-version",
    #
    #  A maximum number of operations to hold in a buffer before sending to GraphQL Hive
    #  Default: 1000
    # buffer_size: 1000
    #
    #  Accepts invalid SSL certificates
    #  Default: false
    # accept_invalid_certs: true

Persisted Documents (App Deployments)

To activate App Deployments in your Apollo Router, you need to enable the hive.persisted_documents plugin. The plugin uses the HIVE_CDN_ENDPOINT and HIVE_CDN_KEY environment variables to resolve the persisted documents IDs.

router.yaml

# ... the rest of your configuration
plugins:
  hive.usage: {}
  hive.persisted_documents:
    enabled: true

Once enabled, follow the App Deployments guide to send persisted document requests from your app, using the Hive CDN for resolving the document IDs.

Configuration

The following environment variables are required:

HIVE_CDN_ENDPOINT - the endpoint Hive generated for you in the previous step (for example: https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/supergraph)
HIVE_CDN_KEY - the access key to Hive CDN

You may configure the plugin with the following options:

router.yaml

# ... the rest of your configuration
plugins:
  hive.usage: {}
  hive.persisted_documents:
    # Enables/disables the plugin
    # Default: true
    enabled: true
    # The endpoint of the Hive CDN. You can either specify it here, or use the existing HIVE_CDN_ENDPOINT environment variable.
    # Required
    endpoint: 'https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/supergraph'
    # The access key to the Hive CDN. You can either specify it here, or use the existing HIVE_CDN_KEY environment variable.
    # Required
    key: '...'
    # Enables/disables the option to allow arbitrary documents to be executed.
    # Optional
    # Default: false
    allow_arbitrary_documents: false
    # HTTP connect timeout in seconds for the Hive CDN requests.
    # Optional
    # Default: 5
    connect_timeout: 5
    # HTTP request timeout in seconds for the Hive CDN requests.
    # Optional
    # Default: 15
    request_timeout: 15
    # Accepts invalid SSL certificates for the Hive CDN requests.
    # Optional
    # Default: false
    accept_invalid_certs: false
    # The maximum number of documents to hold in a LRU cache.
    # Optional
    # Default: 1000
    cache_size: 1000

Additional Resources

Apollo Server Apollo Gateway