HIVE_CDN_ENDPOINT="..." \ # The endpoint of your CDN access tokenHIVE_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-pluginhive_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" keyhive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }
Next, update src/main.rs file with the following content to integrate with Hive Console:
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.
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.
HIVE_ENDPOINT (optional) - For self-hosting, you can override /usage endpoint (defaults to
https://app.graphql-hive.com/usage)
HIVE_TARGET_ID - A target ID, this can either be a slug following the format
“$organizationSlug/$projectSlug/$targetSlug” (e.g “the-guild/graphql-hive/staging”) or an UUID
(e.g. “a0f4c605-6541-4350-8cfe-b31f21a4bf80”). To be used when HIVE_TOKEN is configured with an
organization access token.
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.
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-pluginhive_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" keyhive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }
Next, update src/main.rs file with the following content to integrate with Hive Console:
src/main.rs
mod plugins; use anyhow::Result;+ use apollo_router::register_plugin;+ use hive_apollo_router_plugin::registry;+ use hive_apollo_router_plugin::usage::UsagePlugin; fn main() -> Result<()> {- apollo_router::main()+ // Register the Hive usage_reporting plugin+ register_plugin!("hive", "usage", UsagePlugin);+ 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.
supergraph: listen: 0.0.0.0:4000plugins: hive.usage: {} # Default: true # enabled: true # # Registry token to use instead of HIVE_TOKEN for usage reporting. # registry_token: "hvo1/xxxxxxx" # # Endpoint for the usage reporting. # registry_usage_endpoint: "https://app.graphql-hive.com/usage" # # The target for which usage should be reported. # target: "the-guild/graphql-hive/production" # # 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"], # # Or use a dynamic expression to exclude requests based on runtime context. # exclude: # expression: '.request.operation.name == "IntrospectionQuery"' # # 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 Hive Console # Default: 1000 # buffer_size: 1000 # # A timeout for the entire request to the usage reporting endpoint in seconds # Default: 15 # connect_timeout: 15 # # Accepts invalid SSL certificates # Default: false # accept_invalid_certs: true # # Frequency of flushing the buffer to the server in seconds # Default: 5 # flush_interval: 5
The exclude option supports both the legacy array format and the dynamic expression object
format. For example, you can skip internal traffic based on a request header:
For more details about the Hive Router expression syntax and available request fields used by this
configuration, see Expressions.
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 configurationplugins: 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 configurationplugins: 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
Use as library
You may also add the persisted-documents plugin:
Cargo.toml
[dependencies]# You can use a "branch", or commit id with "rev" keyhive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }
Next, update src/main.rs file with the following content to integrate with Hive Console:
src/main.rs
mod plugins; use anyhow::Result;+ use apollo_router::register_plugin;+ use hive_apollo_router_plugin::registry;+ use hive_apollo_router_plugin::persisted_documents::PersistedDocumentsPlugin; fn main() -> Result<()> {- apollo_router::main()+ // Register the persisted documents plugin, if needed+ register_plugin!("hive", "persisted_documents", PersistedDocumentsPlugin);+ match registry::HiveRegistry::new(None).and(apollo_router::main()) {+ Ok(_) => {}+ Err(e) => {+ eprintln!("{}", e);+ std::process::exit(1);+ }+ } }
If you are using both plugins (usage and persisted operations), you’ll need to have a
register_plugin! call to both plugins.