APISIX integration

The FireTail APISIX plugin integrates with the FireTail SaaS platform to log and validate API requests and responses.

Go Runner Implementation

The FireTail APISIX plugin works as an external plugin using the open-source APISIX Go plugin runner, available in the Apache GitHub organization.

Out of the box, it:

• Sends logs to the FireTail SaaS platform (EU region by default; for the US region, additional configuration is required).
• Validates requests.
• Validates responses.

Build the FireTail APISIX Plugin

Clone the GitHub Repository

Clone the FireTail APISIX GitHub repository:

git clone \
  git@github.com:FireTail-io/firetail-apisix-go-plugin.git

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

cd firetail-apisix-go-plugin

Compiling

To use the APISIX plugin, you first need to compile it. A makefile can be found in the FireTail APISIX plugin’s GitHub repository. which performs the build process. Use this makefile to compile the APISIX plugin.

1. In the root directory, run make build.
2. Running make build should yield a binary called go-runner, which is the FireTail APISIX plugin.

Running in Development Mode

1. In the root directory, run the Unix socket with the following command:

APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock APISIX_CONF_EXPIRE_TIME=3600 ./go-runner run

2. Add the following configuration to the config.yaml file in APISIX:

ext-plugin:
  path_for_test: /tmp/runner.sock

3. Restart APISIX with the command apisix restart.

Installing the Plugin

After building the FireTail APISIX plugin, update your APISIX instance’s config.yaml file to load the plugin.

1. Add the ext-plugin property to your config.yaml file with a cmd property containing a list. The first element of this list should be the absolute file path to the FireTail APISIX plugin binary on your APISIX instance’s filesystem. The second element should be the command run, which is passed to the APISIX Go runner.

ext-plugin:
 cmd: ["/firetail/go-runner", "run"]

2. Restart APISIX with apisix restart.

This should result in an entry in the APISIX logs similar to the text below, stating that the FireTail plugin was registered:

demo-apisix-1  | 2024-04-30T13:19:12.123Z	
INFO	plugin/plugin.go:73	register plugin firetail

Configure Routes

When the FireTail plugin is successfully registered with your APISIX instance, set it up on routes using the ext-plugin-pre-req and ext-plugin-post-resp options.

routes:
 - uri: /*
   plugins:
     ext-plugin-pre-req:
       conf:
         - name: firetail
           value: '{"body":""}'
     ext-plugin-post-resp:
       conf:
         - name: firetail
           value: '{"body":""}'
   upstream:
     nodes:
       "web:80": 1
     type: roundrobin

Configure Routes for the FireTail Plugin using the APISIX Instance’s REST API

Note: You will need to run your application at localhost (127.0.0.1) port 1980. If you wish to point it elsewhere, change the "nodes" parameter from example below.

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 
'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
  "uri": "/profile/alice/comment",
  "plugins": {
    "ext-plugin-pre-req": {
      "conf": [
        {"name":"firetail", "value":"{\"body\":\"\"}"}         
      ]
    },
    "ext-plugin-post-resp": {
      "conf": [
        {"name":"firetail", "value":"{\"body\":\"\"}"}      
      ]
    }
  },
  "upstream": {
    "type": "roundrobin",
      "nodes": {
        "127.0.0.1:1980": 1
    }
  }
}'

Configuration of the FireTail APISIX Plugin

The FireTail APISIX plugin can be configured by setting various environment variables. Here are the key environment variables you need to set:

FIRETAIL_URL

This variable defines the endpoint to which the FireTail APISIX plugin should send logs. By default, it uses the log ingest endpoint for the EU region of the FireTail SaaS platform. If you are using a different region, configure this variable accordingly.

FIRETAIL_URL=https://api.logging.eu-west-1.prod.firetail.app/logs/bulk


FIRETAIL_API_KEY=YOUR_API_KEY_HERE

OpenAPI Specification

FIRETAIL_API_KEY

This variable provides the API key used when sending log data to the FireTail platform. You can generate an API token on an API page in the FireTail platform. Learn how to generate an API token.

OpenAPI Specification

Besides setting the environment variables, you also need to place an OpenAPI specification on the filesystem of the APISIX instance. The FireTail APISIX plugin uses this specification to validate requests and responses. Note: Your OpenAPI specification must be in YAML format.

Go to FireTail's APISIX GitHub repository to learn more.