Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/firetail-io/firetail-krakend-plugin
A proof of concept KrakenD plugin using firetail-go-lib
https://github.com/firetail-io/firetail-krakend-plugin
go go-plugin golang krakend krakend-plugin observability
Last synced: about 2 months ago
JSON representation
A proof of concept KrakenD plugin using firetail-go-lib
- Host: GitHub
- URL: https://github.com/firetail-io/firetail-krakend-plugin
- Owner: FireTail-io
- License: other
- Created: 2023-03-24T12:08:07.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-05T15:13:30.000Z (6 months ago)
- Last Synced: 2024-07-05T20:15:30.595Z (6 months ago)
- Topics: go, go-plugin, golang, krakend, krakend-plugin, observability
- Language: Go
- Homepage:
- Size: 72.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# FireTail KrakenD Plugin
A KrakenD plugin for FireTail, built on [firetail-go-lib](https://github.com/FireTail-io/firetail-go-lib)'s HTTP middleware.
## Getting Started
The FireTail KrakenD plugin distributable is a single `.so` file. To build it, use the KrakenD builder image with a version matching the KrakenD runtime image version you want to use, for example for version `2.2.1`:
```bash
docker run --platform linux/amd64 -it -v "$PWD:/app" -w /app krakend/builder:2.2.1 go build -buildmode=plugin -o firetail-krakend-plugin.so .
```
You should now have a file named `firetail-krakend-plugin.so`.
An [`appspec.yaml`](./example/appspec.yaml) and [`krakend.json`](./example/krakend.json) is included in the [`example`](./example) directory to test out the plugin. To get this running, first move the `.so` file into the [`example`](./example) directory and `cd` into it:
```bash
mv firetail-krakend-plugin.so example
cd example
```
You can then run the KrakenD runtime image with the plugin and provided example [`appspec.yaml`](./example/appspec.yaml) and [`krakend.json`](./example/krakend.json):
```bash
docker run --platform linux/amd64 -p 8080:8080 -v $PWD:/etc/krakend/ devopsfaith/krakend run --config /etc/krakend/krakend.json
```
Curling KrakenD's [`/__health`](http://localhost:8080/__health) endpoint should produce a result similar to the following:
```bash
curl localhost:8080/__health
```
```json
{"agents":{},"now":"2023-03-30 09:29:12.17746026 +0000 UTC m=+6.320137296","status":"ok"}
```
The provided [`krakend.json`](./example/krakend.json) has request and response validation and debug errs enabled. It also defines an endpoint `/test/{id}` which is not included in the provided [`appspec.yaml`](./example/appspec.yaml). We can see the FireTail KrakenD plugin in action by curling the `/test/{id}` endpoint:
```bash
curl localhost:8080/test/1
```
```json
{"code":404,"title":"the resource \"/test/1\" could not be found","detail":"a path for \"/test/1\" could not be found in your appspec"}
```
## Public Releases
You do not have to build the Firetail KrakenD plugin yourself. Versioned releases of the Firetail KrakenD plugin are available as [release assets from this repository](https://github.com/FireTail-io/firetail-krakend-plugin-poc/releases). The naming convention is:
```bash
firetail-krakend-plugin-${ARCH}-$(subst :,-,${KRAKEND_BUILDER_IMAGE})-${RELEASE_VERSION}.so
```
- `${ARCH}` is either `amd64` or `arm64`.
- `${KRAKEND_BUILDER_IMAGE}` correlates to the name of the KrakenD builder image used to build the plugin, which you will need to match to your KrakenD runtime image version. For example:
- For runtime image `krakend/krakend:2.2.1`, `KRAKEND_BUILDER_IMAGE` would be `builder-2.2.1`
- For runtime image `krakend/krakend-ee:2.2`, `KRAKEND_BUILDER_IMAGE` would be `builder-ee-2.2`
- `${RELEASE_VERSION}` is the release version of the Firetail KrakenD plugin.
## Setup With FireTail SaaS
To get the FireTail KrakenD plugin to send logs to the FireTail SaaS platform, you need to create an API or app token to authenticate with the FireTail SaaS' logs API. This can be done using the FireTail SaaS' web UI at [firetail.app](https://firetail.app/). See the docs for [creating an API token](https://firetail.io/docs/create-an-api-token) or [creating an app token](https://firetail.io/docs/create-app-token).
When you have an API token, add it to your KrakenD configuration file as `logs-api-token` under the plugin's configuration, for example:
```json
{
"version": 3,
"plugin": {},
"endpoints": [],
"extra_config": {
"plugin/http-server": {
"name": ["firetail-krakend-plugin"],
"firetail-krakend-plugin": {
"logs-api-token": "YOUR-FIRETAIL-SAAS-API-TOKEN",
}
}
}
}
```
ℹ️ See the [Configuration](#configuration) section for information on the other available config fields.
ℹ️ Logs are sent to FireTail SaaS in batches, so logs may not appear immediately on the FireTail SaaS' web UI.
## Installation Into Existing KrakenD Instances
The FireTail KrakenD plugin is a HTTP server plugin. See the KrakenD docs on [injecting plugins](https://www.krakend.io/docs/extending/injecting-plugins/) to learn how to load it into your KrakenD instances, and view the following section on [Configuration](#configuration) to learn how to configure the FireTail KrakenD plugin once you have successfully injected it.
## Configuration
See the [example/krakend.json](./example/krakend.json) for an example configuration of the FireTail KrakenD plugin. The following table describes all of the currently supported configuration fields, all of which are optional:
| Field Name | Type | Example | Optional | Description |
| ---------------------------- | ------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ |
| `logs-api-token` | String | `"PS-XX-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"` | Yes | Your API token for the FireTail SaaS. If unset, no logs will be sent to FireTail. |
| `logs-api-url` | String | `"https://api.logging.eu-west-1.prod.firetail.app/logs/bulk"` | Yes | The URL to which logs will be sent via POST requests. Defaults to the Firetail SaaS' bulk logs endpoint. |
| `openapi-spec-path` | String | `"/etc/krakend/appspec.yaml"` | Yes | The absolute path to your appspec. By default, no appspec will be used. |
| `enable-request-validation` | Bool | `true`, `false` | Yes | Whether or not requests should be validated against the provided appspec. This defaults to `false` and requires `openapi-spec-path` to be defined. |
| `enable-response-validation` | Bool | `true`, `false` | Yes | Whether or not requests should be validated against the provided appspec. This defaults to `false` and requires `openapi-spec-path` to be defined. |
| `debug-errs` | Bool | `true`, `false` | Yes | Whether or not to include more verbose information in the RFC7807 error responses' `details` member, returned when requests or responses are blocked by validation if enabled. Defaults to `false`. |