/router

A customized Apollo Router binary

Primary LanguageRustMIT LicenseMIT

Apollo Router project

This generated project is set up to create a custom Apollo Router binary that may include plugins that you have written.

Note: The Apollo Router is made available under the Elastic License v2.0 (ELv2). Read our licensing page for more details.

Compile the router

To create a debug build use the following command.

cargo build

Your debug binary is now located in target/debug/router

For production, you will want to create a release build.

cargo build --release

Your release binary is now located in target/release/router

Run the Apollo Router

  1. Download the example schema

    curl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql
  2. Run the Apollo Router

    During development it is convenient to use cargo run to run the Apollo Router as it will

    cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql

If you are using managed federation you can set APOLLO_KEY and APOLLO_GRAPH_REF environment variables instead of specifying the supergraph as a file.

Create a plugin

  1. From within your project directory scaffold a new plugin

    cargo router plugin create hello_world
  2. Select the type of plugin you want to scaffold:

    Select a plugin template:
    > "basic"
    "auth"
    "tracing"

    The different templates are:

    • basic - a barebones plugin.
    • auth - a basic authentication plugin that could make an external call.
    • tracing - a plugin that adds a custom span and a log message.

    Choose basic.

  3. Add the plugin to the router.yaml

    plugins:
      starstuff.hello_world:
        message: "Starting my plugin"
  4. Run the Apollo Router and see your plugin start up

    cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql

    In your output you should see something like:

    2022-05-21T09:16:33.160288Z  INFO router::plugins::hello_world: Starting my plugin

Remove a plugin

  1. From within your project run the following command. It makes a best effort to remove the plugin, but your mileage may vary.
    cargo router plugin remove hello_world

Docker

You can use the provided Dockerfile to build a release container.

Make sure your router is configured to listen to 0.0.0.0 so you can query it from outside the container:

 supergraph:
   listen: 0.0.0.0:4000

Use your APOLLO_KEY and APOLLO_GRAPH_REF environment variables to run the router in managed federation.

   docker build -t my_custom_router .
   docker run -e APOLLO_KEY="your apollo key" -e APOLLO_GRAPH_REF="your apollo graph ref" -p 4000:4000 my_custom_router

Otherwise add a COPY step to the Dockerfile, and edit the entrypoint:

# Copy configuration for docker image
COPY router.yaml /dist/config.yaml
# Copy supergraph for docker image
COPY my_supergraph.graphql /dist/supergraph.graphql

# [...] and change the entrypoint

# Default executable is the router
ENTRYPOINT ["/dist/router", "-s", "/dist/supergraph.graphql"]

You can now build and run your custom router:

   docker build -t my_custom_router .
   docker run -p 4000:4000 my_custom_router