Document updated on Feb 2, 2023
All different types of plugins let you freely implement your logic without restrictions. However, make sure to write them implementing the correct interface and compile them respecting the requirements. In this document, we will see how to do it right.
Writing plugins isn’t complicated per se, but Go is very strict with the environment where you compile and load them. Therefore, the following principles are essential:
krakend.json
configuration.Yes, it sounds rigorous, but fortunately, some tools will tell you about this, so you don’t have to lose time thinking much about this. Let’s see them below.
Once you have decided what type of plugin to write and started developing it, you need to ensure that your plugin uses the library versions compatible with KrakenD. You can use the following tools:
krakend version
gives you information about the Go and Glibc versions used during compilation.check-plugin
analyzes your go.sum
file and warns you about incompatibilities.test-plugin
loads a compiled a plugin and tells you if it is loadable or not.Regardless where you want to use your plugin, compiling your plugins using the right builder is the way to go. The builder makes sure that the system architecture and Go version match the destination, making the plugin loadable.
If you choose to compile locally without the builder, you use a different architecture and underlying libc libraries that will make your plugin unusable.
There are two builders you should use, depending on where you want to run the plugin:
Architecture | Alpine (Docker) | Non-Docker (on-premises) |
---|---|---|
AMD64 | krakend/builder:2.6 | krakend/builder:2.6-linux-generic |
ARM64 | krakend/builder:2.6 with cross-compile instructions | krakend/builder:2.6-linux-generic with cross-compile instructions |
When using Docker to deploy your gateway, our official KrakenD container uses Alpine as the base image. Therefore, to use your custom plugins, they must compile using the Alpine builder.
To build your plugin for Docker targets, you only need to execute the following command inside the folder where your plugin is:
$docker run -it -v "$PWD:/app" -w /app krakend/builder:2.6 go build -buildmode=plugin -o yourplugin.so .
The command will generate a yourplugin.so
file (name it as you please) that you can now copy into a devopsfaith/krakend:2.6
Docker image (but not to tag mismatching the builder), and load it as described in injecting plugins.
To build the plugin for on-premises installations use the following command instead:
$docker run -it -v "$PWD:/app" -w /app krakend/builder:2.6-linux-generic go build -buildmode=plugin -o yourplugin.so .
Regardless of the host architecture you use when running the Docker builder, the default plugin architecture target is AMD64. Therefore, if you want to test the plugin on ARM64 (e.g., a Macintosh, Raspberry, etc.), you must cross-compile it. This is because the plugin builder is available for AMD64 only, as emulation does not work well on Go compilation.
To cross-compile a plugin for Docker ARM64, you need to add extra flags when compiling the plugin:
$docker run -it -v "$PWD:/app" -w /app \
-e "CGO_ENABLED=1" \
-e "CC=aarch64-linux-musl-gcc" \
-e "GOARCH=arm64" \
-e "GOHOSTARCH=amd64" \
krakend/builder:2.6 \
go build -ldflags='-extldflags=-fuse-ld=bfd -extld=aarch64-linux-musl-gcc' \
-buildmode=plugin -o yourplugin.so .
And the same command, changing the builder, when you need on-premises plugins for ARM64:
$docker run -it -v "$PWD:/app" -w /app \
-e "CGO_ENABLED=1" \
-e "CC=aarch64-linux-musl-gcc" \
-e "GOARCH=arm64" \
-e "GOHOSTARCH=amd64" \
krakend/builder:2.6-linux-generic \
go build -ldflags='-extldflags=-fuse-ld=bfd -extld=aarch64-linux-musl-gcc' \
-buildmode=plugin -o yourplugin.so .
Remember that the resulting plugin will only work on ARM64 and that you cannot reuse plugins from one platform into another.
As your custom plugins need to match the Go and libraries versions used to build KrakenD, you have to guarantee your plugin is compatible by checking the go.sum
file with the command check-plugin
(read the documentation)
$krakend check-plugin -v 1.17.0 -s ../myplugin/go.sum
1 incompatibility(ies) found...
go
have: 1.17.0
want: 1.16.4
Once you have written your plugin with the interface you have chosen, compile it in the same architecture type as follows:
$go mod init myplugin
go build -buildmode=plugin -o yourplugin.so .
Now test it, or load it in KrakenD
The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.