KrakenD plugin

The FireTail KrakenD plugin integrates with the KrakenD API Gateway to enhance logging, validation, and observability. This guide provides step-by-step instructions to compile, configure, and verify the plugin on your system.

Setup and Build

To build the FireTail KrakenD plugin, use the official KrakenD builder image available from Docker Hub. Ensure the version of the FireTail KrakenD builder image matches the version of KrakenD runtime image you are using. Using mismatched versions will cause the plugin to fail to load at runtime.

Clone the GitHub Repository

Clone the FireTail KrakenD plugin’s GitHub repository to download a copy of the source code:

git clone git@github.com:FireTail-io/firetail-krakend-plugin-poc.git

After cloning the repository, change directory into the cloned repository:

cd firetail-krakend-plugin-poc

Run Docker Command

Use the docker run command, ensuring the versions of the krakend/builder match the FireTail KrakenD builder image:

docker run -it \
  --platform linux/amd64 \
  -v "$PWD:/app" \
  -w /app krakend/builder:2.2.1 \
  go build -buildmode=plugin -o firetail-krakend-plugin.so

Running this command should yield a new file called firetail-krakend-plugin with a .so file extension.

Run KrakenD With The FireTail KrakenD Plugin

When the FireTail KrakenD plugin is compiled, use the binary it created (firetail-krakend-plugin.so) with the official KrakenD docker image.

FireTail’s GitHub repository contains an example krakend.json and appspec.yaml in the example directory. Use this to check if the plugin is working.

Move the FireTail KrakenD plugin binary into the example directory.

Use the docker run command below to run the official KrakenD runtime image with the FireTail KrakenD plugin, using the KrakenD configuration JSON and OpenAPI specification included in the example directory.

mv firetail-krakend-plugin.so example

docker run --platform linux/amd64 \
  -p 8080:8080 \
  -v $PWD/example:/etc/krakend/ \
  devopsfaith/krakend \
  run --config /etc/krakend/krakend.json

Note: The example directory also includes an OpenAPI specification, and the FireTail KrakenD plugin has been configured to load this OpenAPI specification.

Verify the FireTail KrakenD Plugin

Make a request to its health endpoint using the following curl command:

curl http://localhost:8080/__health

You should receive a response similar to the example below, with a now property holding the current time as a date string, and a status property with a value of ok.

{"agents":{},"now":"2024-04-05 15:23:00.903905546
+0000 UTC m=+177.385972458","status":"ok"}

After confirming that KrakenD is running correctly, the FireTail KrakenD plugin can be verified.

• Make a POST request to the /test endpoint, which is configured in the KrakenD JSON file provided in the example directory. Use the curl command below to make a POST request to the /test endpoint.

curl localhost:8080/test -H "Content-Type: application/json" -d '{}'

• If the FireTail KrakenD plugin is working correctly, you should receive a 400 error response from the FireTail KrakenD plugin. The response body should be a JSON object containing the status code, a title, and a detail property. 
  • The detail property has a detailed explanation as to why the request failed to validate against the OpenAPI specification provided in the example directory of the FireTail KrakenD plugin’s GitHub repository.

{"code":400,"title":"something's wrong with your request body",
"detail":"the request's body did not match your appspec: 
request body has an error: doesn't match the schema: 
Error at \"/name\": property \"name\" is missing\nSchema:\n  
{\n    \"additionalProperties\": false,\n    \"properties\": 
{\n      \"name\": {\n        \"example\": \"John Doe\",\n
\"type\": \"string\"\n      }\n    },\n    \"required\": 
[\n      \"name\"\n    ],\n    \"type\": \"object\"\n  }\n\nValue:\n  {}\n"}

In the example above, the request failed as the request body did not include a name property, which is required, as described in the OpenAPI schema.

Configure The FireTail KrakenD Plugin

The example KrakenD JSON configuration file included in the FireTail KrakenD plugin’s GitHub repository showcases several key configuration options:

 "extra_config": {
   "plugin/http-server": {
     "name": [
       "firetail-krakend-plugin"
     ],
     "firetail-krakend-plugin": {
       "openapi-spec-path": "/etc/krakend/appspec.yaml",
       "enable-request-validation": true,
       "enable-response-validation": true,
       "debug-errs": true,
       "logs-api-token": "Your API token goes here!"
   }
 }

openapi-spec-path

This property specifies the absolute filepath to the OpenAPI schema on the filesystem that the FireTail KrakenD plugin should use to validate API requests and responses.

enable-request-validation and enable-response-validation

These boolean properties determine whether the FireTail KrakenD plugin should validate API requests or responses against the OpenAPI schema. By default, both are set to false. You must explicitly enable them to validate your API requests and/or responses:

debug-errs

This boolean property, which defaults to false, controls whether the FireTail KrakenD plugin includes a details property in responses that failed to validate against your OpenAPI specification. This is useful for debugging validation errors:

Important: The debug-errs option should only be set to true in a development environment. Enabling this option in production can expose sensitive information in error messages, potentially aiding attackers in extracting information from your API.

logs-api-token

This property is used to provide the FireTail API token, which the FireTail KrakenD plugin uses when sending logs to the FireTail SaaS platform.

To get the Firetail KrakenD plugin to send logs to the Firetail platform, you need to create an API token to authenticate with the Firetail platforms logging API. 

When you have an API token, add it to your KrakenD configuration file as logs-api-token under the plugin's configuration, as in the example above.

For information on other available configurations, refer to the FireTail KrakenD plugin’s GitHub repository.