Apache APISIX Integration

This guide explains how to install the apifort-ingest plugin on Apache APISIX and start capturing HTTP traffic into ApiFort.

What You'll Do

• Install the apifort-ingest Lua plugin on your APISIX gateway.
• Start the httpcap collector agent on your infrastructure.
• Apply the plugin globally with a single Admin API call.
• Verify that traffic is flowing into ApiFort.

---

The httpcap collector must be network-accessible from APISIX on the configured port (default: 9999).

---

Step 1: Install the Plugin File

The plugin file must be present on the filesystem of every APISIX node. Choose the method that matches your deployment:

Bare Metal / VMDockerKubernetes

Copy the file to the APISIX plugins directory:

Bash

cp apifort-ingest.lua /usr/local/apisix/apisix/plugins/apifort-ingest.lua

Verify it is readable by the APISIX process:

Bash

ls -la /usr/local/apisix/apisix/plugins/apifort-ingest.lua

Mount the file as a read-only volume in your docker-compose.yml. Updates take effect after apisix reload without rebuilding the image:

YAML

services:
  apisix:
    volumes:
      - ./apifort-ingest.lua:/usr/local/apisix/apisix/plugins/apifort-ingest.lua:ro

Create a ConfigMap from the plugin file and mount it into the APISIX pod:

Bash

kubectl create configmap apifort-ingest-plugin \
  --from-file=apifort-ingest.lua \
  -n <apisix-namespace>

Add the volume and mount to your APISIX deployment or Helm values:

YAML

volumes:
  - name: apifort-plugin
    configMap:
      name: apifort-ingest-plugin
volumeMounts:
  - name: apifort-plugin
    mountPath: /usr/local/apisix/apisix/plugins/apifort-ingest.lua
    subPath: apifort-ingest.lua

Step 2: Register the Plugin

Open /usr/local/apisix/conf/config.yaml and add apifort-ingest to the plugins list:

YAML

plugins:
  # ... your existing plugins ...
  - apifort-ingest

Reload APISIX to apply the change. This is a graceful reload — no active connections are dropped:

Bash

apisix reload

Confirm the plugin loaded without errors:

Bash

grep -i "apifort" /usr/local/apisix/logs/error.log | tail -5
# No output means the plugin loaded successfully

Step 3: Start the httpcap Collector

The plugin does not write to Kafka directly. It sends each captured event to the httpcap collector agent, which runs entirely within your network and writes to Kafka.

3a. Configure environment variables

Create a .env file with your environment values:

Text Only

# Kafka connection
OUTPUT_KAFKA_HOST=<broker-host>:<port>
OUTPUT_KAFKA_TOPIC=apifort.apisix_logs
OUTPUT_KAFKA_USE_SASL=true
OUTPUT_KAFKA_SASL_MECH=PLAIN
OUTPUT_KAFKA_USERNAME=<kafka-username>
OUTPUT_KAFKA_PASSWORD=<kafka-password>

# Collection ID — provided by ApiFort, identifies this APISIX deployment
OUTPUT_KAFKA_COLLECTION_ID=<uuid-provided-by-apifort>

# Collector listener port
INPUT_APISIX_HTTP_PORT=9999

3b. Start the collector

Bash

docker compose up -d

Verify it is running:

Bash

docker logs httpcap-apisix --tail 5
# Expected: Workers [asm:1 proc:3 bcast:2 kafka:3]

Step 4: Enable the Plugin

Option A — Global (Recommended)

Apply the plugin to all routes with a single Admin API call. No per-route changes are needed.

Bash

curl -X PUT http://127.0.0.1:9180/apisix/admin/global_rules/1 \
  -H 'X-API-KEY: <your-admin-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "plugins": {
      "apifort-ingest": {
        "collector_agent_url": "http://<collector-host>:9999"
      }
    }
  }'

To stop capturing traffic at any time:

Bash

curl -X DELETE http://127.0.0.1:9180/apisix/admin/global_rules/1 \
  -H 'X-API-KEY: <your-admin-key>'

Option B — Per Route

To capture traffic only on specific routes, add the plugin to each route individually:

Bash

curl -X PATCH http://127.0.0.1:9180/apisix/admin/routes/<route-id> \
  -H 'X-API-KEY: <your-admin-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "plugins": {
      "apifort-ingest": {
        "collector_agent_url": "http://<collector-host>:9999"
      }
    }
  }'

Plugin Parameters

Parameter	Type	Default	Description
collector_agent_url	string	—	Required. URL of the httpcap collector agent.
timeout	integer (ms)	500	HTTP call timeout to the collector.
request_body_limit	integer (bytes)	1048576	Maximum request body captured (1 MB).
response_body_limit	integer (bytes)	1048576	Maximum response body captured (1 MB).

Static assets (images, fonts, JS/CSS files) are skipped automatically — no configuration required.

Step 5: Verify

Send a test request through APISIX:

Bash

curl http://127.0.0.1:9080/<any-route-path>

Check that the collector received it:

Bash

docker logs httpcap-apisix --tail 5

Expected output:

Text Only

Win (10s): req:1  resp:1  err:0  drop:0

---

How It Works

Text Only

Client → APISIX → Upstream
              ↓  log phase (async — zero added latency)
     apifort-ingest plugin
              ↓  HTTP POST
     httpcap collector  (on-premises)
              ↓
           Kafka

Zero Latency Impact

The plugin runs entirely in APISIX's log phase, after the response has already been sent to the client. The Kafka send is further deferred via a background timer, so it never blocks gateway workers.

The Collection ID that groups all traffic from this APISIX deployment is set once in the httpcap .env file (OUTPUT_KAFKA_COLLECTION_ID), not per route.

---

Troubleshooting

Route returns 404 after enabling the plugin

Check error.log for schema validation errors:

Bash

grep "apifort-ingest" /usr/local/apisix/logs/error.log | tail -10

An additional properties forbidden error means the route config contains fields from an older version of the plugin. Remove the unknown fields via the Admin API and reload.

Collector not receiving events

Verify network connectivity from the APISIX host to the collector:

Bash

curl -v http://<collector-host>:9999/
# A connection (even an error response) confirms the port is reachable