Traceable Kong

Kong is an orchestration microservice API gateway. It provides a flexible abstraction layer that securely manages communication between clients and microservices via API, allowing you to build robust, high-performance APIs that scale horizontally quickly. Kong also has built-in security, load balancing, and monitoring features to track your system's real-time health and performance. Traceable provides a plugin for your Kong API gateway deployment.

What you will learn from this topic

By the end of this topic, you will be able to:

• Deploy the Traceable Platform Agent for the Kong integration.

• Install and configure the Traceable Kong plugin.

• Configure the integration for synchronous or asynchronous deployment modes.  

• Configure the Traceable plugin for DBless and DB-based Kong deployments.  

• Verify that the Kong integration is working correctly.

• Configure AI Firewall to evaluate, redact, or block sensitive data in AI-related requests and responses.  

• Configure the traceable-ai-extension plugin and attach it to the routes or services you want to protect.  

Before you begin

Before you deploy the Traceable Kong integration, make sure you have the following:

• Make sure the instructions in this topic apply to the Kong Ingress Controller running on Kubernetes.

• Make sure you have access to the kong-values.yml file, which you will update during the configuration.

• Make sure unzip is installed on the host OS.

• Make sure the Traceable Platform Agent (TPA) is installed and configured.

• Make sure the LuaRocks CLI is installed. If it is not already installed, run:

  sudo apt-get install -y luarocks
  

• Make sure you have the IP address or endpoint of the machine running the TPA.

• Make sure Kong is installed and running. For installation instructions, see:

  • DBless: Kong Kubernetes Ingress Controller as an API Gateway: Tutorial.

  • With DB: Install with Kong Gateway using Helm.

• Make sure you have basic knowledge of Kong. For more information, see Kong Documentation.

If you plan to use AI Firewall, also make sure that:

• Make sure Edge Decision Service (EDS) is enabled and reachable from the TPA.

• Make sure the required sensitive data, data protection, or blocking rules are configured in Traceable.

• Make sure the Kong plugin package includes both the traceable and traceable-ai-extension plugins.

• Make sure both plugins are loaded on every Kong data plane:

  KONG_PLUGINS=bundled,traceable,traceable-ai-extension

• Make sure these plugin names are appended to any existing KONG_PLUGINS value.

• If you use Kong Konnect, make sure both custom plugin schemas are uploaded:

  kong/plugins/traceable/schema.lua
  kong/plugins/traceable-ai-extension/schema.lua
  

• Make sure the corresponding plugin code is installed on every Kong data plane.

• Make sure the version is 2.3.0 for the AI firewall extension.

Kong documentation

You can also follow the instructions in the Kong Plugin Hub to install Traceable's Kong plugin.

Deployment modes

Traceable’s Kong integration provides two modes for exporting request data:

• Synchronous (sync) — In sync mode, the Kong integration makes two calls to the Traceable Platform Agent (TPA): one to authorize the request and another to capture the response. This mode is ideal for deployments that require immediate, step-by-step request-and-response processing.

• Asynchronous (async) — In async mode, available starting with plugin version 2.1.0, offers a streamlined alternative. In async mode, only a single call to TPA is made during the log phase after the response is fully sent back to the client. This approach reduces the number of interactions with TPA, minimizing overhead and potentially improving response times, especially in high-traffic environments.

Note

• In async mode, the log phase does not have access to the request body. To capture the full request in async mode, set the buffer_request_body option to true in the kong-values.yaml file. This buffers the request body during the access phase, making it available for the log phase.

• The default mode is synchronous; however, starting with Traceable’s Kong plugin version 2.3.0, an asynchronous mode is also available for enhanced efficiency.

Deployment

To deploy Traceable's plugin for Kong, complete the following steps:

1. Deploy Traceable Platform agent.

2. Adding the Traceable plugin to Kong.

3. Configure the Traceable plugin.

Step 1 — Deploy Traceable platform agent

To deploy the Traceable Platform agent, go through the steps mentioned in Helm topic. 

Step 2 — Add Traceable's Kong plugin

Complete the following steps to add Traceable's Kong plugin:

1. Download the Traceable plugin from LuaRocks. Specify the following command:

   curl -fLO https://luarocks.org/manifests/traceableai/kong-plugin-traceable-2.1.0-1.src.rock

2. Unpack the luarock. Specify the following command:

   luarocks unpack kong-plugin-traceable-2.1.0-1.src.rock

3. Create a configmap for rock. Specify the following command:

   kubectl create configmap -n kong kong-plugin-traceable --from-file ./kong-plugin-traceable-2.1.0-1/kong-plugin-traceable-2.1.0/kong/plugins/traceable/

You can insert the plugin into Kong using either of the following options:

• Option 1 — Modify the Kong Helm values.

• Option 2 — Apply a deployment patch.

Choosing either option 1 or option 2 makes Kong aware of the Traceable plugin's presence. The following tabs discuss both the options:

# This should be under the env key and should already exist
# Note, if you have additional 3rd party plugins, make sure to keep them present
plugins: bundled,traceable
# Add this section at the very bottom of the file
plugins:
  configMaps:
  - name: kong-plugin-traceable
    pluginName: traceable

helm upgrade quickstart kong/kong --namespace kong --values kong-values.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ingress-kong
  namespace: kong
spec:
  template:
    spec:
      containers:
      - name: proxy
        env:
        - name: KONG_PLUGINS
          value: bundled,traceable
        - name: KONG_LUA_PACKAGE_PATH
          value: "/opt/?.lua;;"
        volumeMounts:
        - name: kong-plugin-traceable
          mountPath: /opt/kong/plugins/traceable
      volumes:
      - name: kong-plugin-traceable
        configMap:
          name: kong-plugin-traceable

kubectl patch deployments.apps --type strategic -n kong ingress-kong --patch-file kong-traceable-patch.yml

Step 4 — Configure Traceable plugin

Choose from DBless or DB mode. Make a note of the following for both modes:

• In async mode, if the Traceable Platform agent is in the same cluster, then ext_cap_endpoint it would be http://agent.traceable:5442. Use the public IP address if the Traceable Platform agent is outside the cluster.

The following tabs discuss the DBless and the DB mode of configuring the Traceable plugin:

Step 5 — Rollout

To execute the rollout start, specify the following command:

kubectl rollout restart deployment -n kong

Step 6 — Verification

To verify, send traffic through the Kong gateway and Kong Proxy, then view the details in the Traceable platform to verify that the installation was successful.

❯ k get svc -n kong 
NAME                      TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)                      AGE
kong-proxy                LoadBalancer   1.12.9.28        1.12.9.28   80:30825/TCP,443:31308/TCP      67m

AI firewall extension

If your Kong deployment routes traffic to AI-powered services, you can extend the Traceable Kong integration to protect that traffic before it reaches your upstream application or your client. Based on the sensitive-data classification and data-protection rules you configure in the Traceable Platform, Traceable can detect, mask, or block matching content. This rule-driven approach means the extension does exactly what your platform rules define, whether that means redacting a value, denying the request outright, or simply monitoring it. This capability builds directly on the base traceable plugin you configured in deployment. For more information, see Step 2 — Configure the base traceable plugin.

You do not need a separate agent or a separate integration to use it. When a rule specifies redaction, Traceable detects the configured data types in the request or response payload and masks them before forwarding the traffic through supported enforcement flows.

Note

Redaction depends on configuration in two places:

• The Traceable Platform Agent (TPA), the Kong gateway plugins, and the Traceable Platform itself. The Traceable Platform must contain sensitive-data classification or data-protection rules that match the traffic being inspected.

• If no platform rule matches, Traceable passes the content through unchanged, this is expected behavior, not a failure.

AI firewall capabilities

AI firewall extension in Traceable Kong integration has the following capabilities:

• Request redaction masks sensitive data before Traceable forwards the request to the upstream application.

• Response redaction masks sensitive data before Traceable returns the upstream response to the client.

• Rule-driven behavior means Traceable only acts on content matched by your configured platform rules. Nothing is redacted, denied, or flagged unless a rule says so.

• A policy can also deny matching traffic outright rather than Redact it.

For full bidirectional coverage, configure the base traceable plugin as you normally would, and attach the traceable-ai-extension plugin to the AI route or service you want to protect. Attaching traceable-ai-extension enables both request and response evaluation for that route; the specific behavior for each is then driven entirely by your platform rules.

Steps to configure

To configure the AI firewall, complete the following steps:

Step 1 — Configure the Traceable Platform Agent (TPA)

Every Kong data plane must load both Traceable-ai as well as the traceable-ai-extension plugins. Specify the following command to configure the same:

KONG_PLUGINS=bundled,traceable,traceable-ai-extension

Make sure these plugin names are appended to any existing KONG_PLUGINS value. You can enable ext-cap, body evaluation, remote configuration, and  evaluation on the TPA:

extCapEnabled: true
evaluateBody: true
remoteConfigEnabled: true

extCapEdgeDecisionService:
   enabled: true
   endpoint: edge-decision-service.<namespace>.svc.cluster.loc:62060
   timeoutMs: 3000

Note

Replace the endpoint and timeoutMs values with the values appropriate for your deployment. The timeout set here is the default for the TPA-to-  call; you can set individual request and response timeouts in the Kong plugin configuration. If you configure them, they must match the request URL being evaluated. When you configure both include and exclude filters, the include list takes precedence.

Step 2 — Configure the base traceable plugin

Configure the base traceable plugin globally where possible. The following settings are relevant to AI firewall redaction. For more information, see the tabs in Step 4 — Configure Traceable plugin.

• ext_cap_endpoint — Set this to the reachable TPA HTTP endpoint, for example, http://<agent-service>:5442.

• mode — Must be sync for requesting an AI evaluation. For more information, see Deployment modes.

• timeout — Controls the ordinary base-plugin TPA call. AI request and response evaluation each have their own separate timeouts, configured on the extension plugin.

• max_body_size_bytes — Controls how much of the request body Traceable includes in evaluation.

• allow_on_failure — This base-plugin setting does not control AI evaluation failures; the extension plugin has its own failure handling.

Step 3 — Configure the traceable-ai-extension plugin

Attach traceable-ai-extension only to the AI services or routes that require redaction. Every request matched by traceable-ai-extension the base plugin must also be matched by the base traceable plugin.

The extension plugin has independent request and response configurations:

• request_config.timeout

• request_config.allow_on_failure

• response_config.timeout

• response_config.allow_on_failure

Choose timeouts that fit your application's latency budget and allow enough time for EDS evaluation.

Note

The extension does not require its own endpoint, token, service name, or environment name. It inherits these values from the matching base traceable plugin.

Step 4 — Attach both plugins to the protected route

The following example attaches both plugins to a Kong Ingress. If traceable it is already configured globally in your cluster, attach only traceable-ai-extension to the Ingress.

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: traceable
plugin: traceable
config:
  ext_cap_endpoint: "http://<agent-service>:5442"
  token: "${TPA_TOKEN}"
  service_name: "my-api"
  environment_name: "prod"
  timeout: 1000
  mode: "sync"
  allow_on_failure: true
  max_body_size_bytes: 131072
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: traceable-ai-extension
plugin: traceable-ai-extension
config:
  request_config:
    timeout: 3000
    allow_on_failure: true
  response_config:
    timeout: 3000
    allow_on_failure: true
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-api
  annotations:
    konghq.com/plugins: "traceable,traceable-ai-extension"
spec:
  # Add your Ingress configuration here.

Verification

Complete the following steps to verify the AI firewall configuration:

1. Confirm that the TPA and  are healthy and reachable.

2. Configure a traceable sensitive data or data protection rule for a test value, such as an email address.

3. Send a request that includes the matching test value via the protected Kong route.

4. Check what the upstream application receives, to verify request redaction.

5. Return matching sensitive data from the upstream application.

6. Confirm that the client receives the redacted response.

7. Confirm that the Traceable Platform reports the matching policy decision.

8. If your policy is configured to deny matching traffic, confirm that the client receives the configured deny response.

Note

A successful passthrough without redaction does not necessarily indicate a problem. It may mean that no configured platform rule matched your test traffic.

Failure behavior

AI evaluation defaults to fail-open:

allow_on_failure: true

If the TPA is unreachable, times out, or returns an invalid response, traffic passes through without redaction. Set allow_on_failure: false only when traffic must be denied during evaluation failures. In this case, the client receives a 403 response.

Response buffering and streaming

The AI extension buffers the complete upstream response before evaluating it. If you attach traceable-ai-extension to a route serving Server-Sent Events (SSE) or other long-lived streaming responses, those responses will not stream while the extension is attached.

Note

Request AI evaluation, redaction, and blocking only run when the base plugin uses mode: sync. For more information, see Deployment modes.

Supported request content types

Traceable evaluates request bodies when the Content-Type contains one of the following:

• json

• xml

• x-www-form-urlencoded

• text/event-stream

Traceable does not evaluate other request body types, including text/plain, protobuf, gRPC, octet-stream, and images.

Body size

max_body_size_bytes limits how much of the request body Traceable includes in the evaluation. Requests exceeding this value are truncated for evaluation purposes. Choose a value large enough for your expected AI request payloads, and validate behavior for oversized requests before rolling out to production.

The response extension buffers the complete upstream response, so large responses can increase latency and memory usage.

Plugin dependency

traceable-ai-extension depends on the base traceable plugin. If you attach the extension without a matching base plugin, AI evaluation cannot obtain the TPA endpoint and shared configuration.

Rule dependency

Redaction only occurs when traffic matches an enabled platform rule. If a payload passes through unchanged and you expected redaction, check the following:

• Confirm that the rule is enabled.

• Confirm that the route is covered by both plugins.

• Confirm that the traffic reaches EDS.

• Confirm that the payload content and content type match the rule.

• Confirm that the configured timeouts are sufficient.

Upgrade

You can upgrade the Traceable plugin by repeating the curl commands in Step 3 with new plugin versions. For example:

Upgrade Traceable plugin

Complete the following steps:

1. Enter the following curl command to upgrade the Traceable plugin. Replace the <new-version-number>in the following commands with the latest version number. For the latest version for AI firewall, see Before you Begin.

   curl -LO https://luarocks.org/manifests/traceableai/kong-plugin-traceable-<new-version-number>.src.rock

2. Unpack the luarock. Specify the following command:

   luarocks unpack kong-plugin-traceable-<new-version-number>.src.rock

3. Delete the old configmap using the following commands: 

   kubectl delete configmap -n kong kong-plugin-traceable
   kubectl delete configmap -n kong kong-plugin-traceable-ai-extension

4. If you previously installed the AI extension under an older name, also delete that configmap:

   kubectl delete configmap -n kong kong-plugin-traceable-ai-plugin

5. Recreate a configmap using the following commands:

   kubectl create configmap -n kong kong-plugin-traceable --from-file ./kong-plugin-traceable-<new-version-number>/kong-plugin-traceable-<new-version-number>/kong/plugins/traceable/
   kubectl create configmap -n kong kong-plugin-traceable-ai-extension --from-file=./kong-plugin-traceable-<new-version-number>/kong-plugin-traceable-<new-version-number>/kong/plugins/traceable-ai-extension/

6. Restart Kong by specifying the following command:

   kubectl rollout restart deployment -n kong

Uninstall

You have to follow different steps to uninstall DBless and DB installations. 

DBless uninstallation

To uninstall Traceable for a DBless installation, run the following command:

kubectl delete kongclusterplugin traceable-plugin

Restart Kong by entering the following command:

kubectl rollout restart deployment -n kong

DB uninstallation

Run the following command to fetch a JSON response listing all installed plugins. Each plugin has a unique UUID.

curl -X GET "http://localhost:8444/plugins"

Following is a sample JSON response for the above command:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
      "name": "traceable-plugin",
      ...
    },
    ...
  ]
}

To delete a plugin, use the UUID of that plugin in the following command:

curl -X DELETE "http://localhost:8444/plugins/<UUID>"

Restart Kong by entering the following command:

kubectl rollout restart deployment -n kong

(Optional) Custom error message

You can optionally configure a custom error code and message for the blocking function by editing the Traceable Platform agent configuration, as shown below. Configure this inside the injector section.

ext_cap:
  blocking_config:
    response_status_code: 403
    response_message: "Access Forbidden"
injector:
  blocking_config:
    response_status_code: 403
    response_message: "Access Forbidden"

If you are using Helm in values.yaml, then you would need to set:

blockingStatusCode: 
blockingMessage:
injector:
  blockingConfig:
    blockingStatusCode: 
    blockingMessage:

Make sure the status code is set to a value between 400 and 499. If you add values outside the 4xx range, then 403 (the default status code) is displayed in the Traceable Platform.