Plugin Developers Guide
The usage of plugin from the user perspective is described here, which will give you a good overview of how plugins work. The lifecycle of a plugin is described on the same page. This page is a guide for plugin developers.
Overview
Follow these steps to create a plugin:
- Generate a plugin scaffold using the
gatewayd plugin scaffold
command. - Update the
gatewayd_plugins.yml
file with the correct information. - Test your plugin locally using the
make run
target of GatewayD. - Test your plugin in the CI pipeline.
- Test your plugin using this
test.yaml
workflow. - Publish your plugin to GitHub using this
release.yaml
workflow and thisMakefile
.
In the following sections, each step is described in more detail.
Step 1: Generate a plugin scaffold
The gatewayd plugin scaffold
command generates a plugin scaffold for you. You can use the scaffolds, which is based on the GatewayD plugin template for Go project, to create your own plugin. The generated scaffold contains all the hooks you can use with typical message payloads, which you can safely remove. The scaffold contains all the necessary workflows, Makefile
and metadata files to get you started quickly.
Previously, the GatewayD plugin template for Go project could be used to create a plugin. This project is now deprecated and the
gatewayd plugin scaffold
command should be used instead.
This is the structure of the generated directory with the scaffold command:
.
βββ .github/workflows/
βΒ Β βββ commits-signed.yaml # Check if commits are signed
βΒ Β βββ release.yaml # Release workflow
βββ gatewayd_plugin.yaml # Metadata
βββ go.mod # Dependencies
βββ go.sum
βββ LICENSE
βββ main.go # The main function that starts your plugin
βββ Makefile # Targets to build the plugin, create checksum and update dependencies
βββ plugin # Source code of your plugin
βΒ Β βββ metrics.go # Prometheus metrics
βΒ Β βββ module.go # Plugin module: plugin ID, plugin map and plugin config
βΒ Β βββ plugin.go # The actual implementation of your plugin
βββ plugin-template-go # Generated plugin binary
βββ README.md # Documentation
To run the command, you need to have an input.yaml
file that contains the following information. This file is used to scaffold the plugin, which you can find an example here.
remote_url: https://github.com/me/gatewayd-plugin-test
version: 0.0.1
description: This is test plugin
license: Apache-2.0
authors:
- Me <[email protected]>
After you have created the input.yaml
file, run the following command to generate the plugin scaffold:
gatewayd plugin scaffold --input-file input.yaml --output-dir gatewayd-plugin-test
Step 2: Update the gatewayd_plugins.yml
file with the correct information
The gatewayd_plugins.yml
file contains the metadata of your plugin. This file is used by GatewayD to load your plugin. The following fields are required:
name
: The name of your plugin.enabled
: Whether the plugin is enabled or not.localPath
: The path to the plugin binary.env
: The environment variables that are passed to the plugin.
The following fields are optional:
args
: The arguments that are passed to the plugin.checksum
: The checksum of the plugin binary.
Use the
./gatewayd run --dev
command to disable plugin checksum verification when developing a plugin. Otherwise, the plugin will not be loaded or you must change the checksum every time you make a change to the plugin. This is not recommended for production.
These two environment variables with their exact values are required. They must be passed to the HandshakeConfig of the plugin. These pieces of information are used by GatewayD to verify and load the plugin:
MAGIC_COOKIE_KEY=GATEWAYD_PLUGIN
MAGIC_COOKIE_VALUE=5712b87aa5d7e9f9e9ab643e6603181c5b796015cb1c09d6f5ada882bf2a1872
Step 3: Test your plugin locally using the make run
target of GatewayD
You can test your plugin locally by running GatewayD CLI in development mode. The development mode lets your test your plugin without checksum verification. For more information, see GatewayD CLI.
- Install GatewayD according to the installation instructions.
- Run the following command to start GatewayD CLI in development mode:
./gatewayd run --dev
It is recommended to use the
trace
log level to see the logs of your plugin. For more information, see loggers.
Step 4: Test your plugin in the CI pipeline
Copy the test-plugin
job of the GatewayD CI pipeline into the .github/workflows/test.yaml
file. This job will test your plugin using the GatewayD CLI in development mode.
Step 5: Test your plugin using this test.yaml
workflow
If you have written tests for your plugin, you can use the following workflow to test your plugin. Copy the test.yaml
workflow into the .github/workflows/
directory of your plugin. This workflow will test your plugin using the GatewayD CLI in development mode.
Step 6: Publish your plugin to GitHub
If you want to publish your plugin to GitHub, you can use the release.yaml
workflow and Makefile
that are generated as part of the scaffold files in the .github/workflows
directory. All you have to do is to push your changes to your desired GitHub repository and create a release with the tag, for example v0.1.0. The workflow will build your plugin for three platforms and two CPU architectures, create a release with the given tag, and upload the plugin binaries (as archive files) and checksums.txt
as release assets, just like this.
Now, if you want GatewayD to install your plugin from GitHub, you must adhere to the following rules:
- The plugin binary must be named as the repository name, aka. the plugin name.
- The plugin binary must be placed in the root directory of the release asset.
- Each published release asset that contains a plugin binary must also have a
checksum.txt
file next to the plugin binary in the archive file containing the checksum of the plugin binary. - The checksums of all the release assets should be generated using sha256sum, and published as release assets, and named
checksums.txt
. - The release assets must be published as
tar.gz
or.zip
archives. - The release assets must follow the naming convention:
plugin-name-$GOOS-$GOARCH-version.tar.gz
. For example,gatewayd-plugin-cache-linux-amd64-v0.1.0.tar.gz
. - The name of the archive files in the release assets must follow semantic versioning and prefixed with
v
.
Next steps
Check out the using plugins page to know more about the details of the plugin system including hooks, plugin registry, hook registry and different plugin types.