Creating a custom Apollo Router binary
To use custom plugins that aren't bundled with the default Apollo Router distribution, you need to compile your own custom router binary. This page walks you through creating that binary from scratch and adding a plugin to it.
Note: The Apollo Router is made available under the Elastic License v2.0 (ELv2). This applies to its source code and all distributions. For details, see our licensing page.
To compile the Apollo Router, you need to have the following installed:
After you install the above, also install the
cargo install cargo-xtaskcargo install cargo-scaffold
cargo-scaffoldcommand to create a project for your custom router:cargo-scaffold scaffold https://github.com/apollographql/router.git -r apollo-router-scaffold/templates/base
cargo-scaffoldcommand prompts you for some configuration settings. For the purposes of this tutorial, set your project's name to
After your project is created, change to the
The generated project has the following layout:
starstuff├── Cargo.toml # Dependencies are declared here├── README.md├── router.yaml # Router yaml config├── src│ ├── main.rs # Entry point│ └── plugins # Custom plugins are located here│ └── mod.rs└── xtask # Build support files├── Cargo.toml└── src└── main.rs
The Apollo Router uses an auto-discovery mechanism for plugins, so any plugins you add via dependency are automatically available to the Router at runtime.
Create a debug build of the Apollo Router with the following command:
The resulting debug binary is located in
To create a release build for production environments, use this command instead:
cargo build --release
The resulting release binary is now located in
Now you can test out your compiled router with an example supergraph schema.
Download the example schema with the following command:curl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql
Run the router and provide the example schema like so:cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql
During development, it's helpful to use
cargo runto run the router.
If you're using managed federation, you set the
APOLLO_GRAPH_REF environment variables instead of specifying the supergraph schema as a file. For details, see this section.
From within your project directory, scaffold a new plugin with the following command:cargo router plugin create hello_world
The command prompts you to choose a starting template:Select a plugin template:> "basic""auth""tracing"
The available templates are:
basic- a barebones plugin
auth- an authentication plugin for making an external call
tracing- a telemetry plugin that adds a custom metric span and a log message
For the purposes of this tutorial, choose
Add configuration options for the created plugin to your
router.yamlfile:router.yamlplugins:starstuff.hello_world:message: "starting my plugin"
Run the router again:cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql
This time, you should see a log line like the following:2022-05-21T09:16:33.160288Z INFO router::plugins::hello_world: starting my plugin
Nice work! You now have a custom router binary with an associated plugin. Next, you can extend the plugin with the functionality you need or add more plugins.
To remove a previously added plugin from your router project, use the following command:
cargo router plugin remove hello_world
Note that depending on the structure of your plugin, the command might fail to remove all of its associated files.