--- title: "Traceable Kong" slug: "kong" description: "Learn how to integrate Traceable AI with Kong for robust API security and observability. This guide covers deploying the Traceable Kong agent, configuring synchronous and asynchronous modes, setting up essential parameters, and optimizing performance. Discover how to monitor API traffic, detect threats, and gain deep insights into your API ecosystem using Traceable AI’s Kong integration." updated: 2024-12-12T05:11:20Z published: 2024-12-12T05:11:20Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. The following diagram provides high-level information about the deployment. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_kong_deployment_architecture_v2.png) #### Traceable Module Extension (TME) Traceable module extension (TME) is a sidecar container the Traceable Platform agent can inject into the application pod. It can be considered a miniature Traceable Platform agent. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_tme_injection(1).png) TME has ext_cap as a component. This synchronously receives requests from the applications, such as a gateway. The Traceable module extension also houses `libtraceable` which has the request-blocking logic. TME is used when native instrumentation or a native plugin is not available. In such cases, TME captures data inline and asynchronously sends the data to the Traceable Platform agent. TME also blocks the requests inline. > [!NOTE] > Note > > If you are integrating Traceable in an asynchronous (`async`) mode, you do not need to use TME. --- ## Before you begin Make sure that the following prerequisites are met before deploying Traceable's Kong tracing agent or Kong agent: - The instructions provided are specifically for the Kong Ingress Controller on Kubernetes. - Make sure that you have access to the `kong-values.yml` file. The changes are made to this file. - `unzip` installed on the host OS - The traceable agent is installed and configured. For more information on Traceable agent installation, see [Traceable agent](/v1/docs/tpa). - Lua Rocks CLI is installed. If it is not already installed, enter the following command to install Lua Rocks: ActionScriptActionScript ```actionscript sudo apt-get install -y luarocks ``` - IP address of the machine where the Traceable agent is running. - **Port number**— Make sure that port number 5442 is available. The Traceable Module Extension (TME) uses this port. - Make sure that Kong is installed. For more information on installing Kong, see: - **DBless –**Kong[Kubernetes Ingress Controller as an API Gateway: Tutorial](https://konghq.com/blog/kubernetes-ingress-api-gateway) - **With DB –**Install[with Kong Gateway using Helm – v3.0x | Kong Docs](https://docs.konghq.com/gateway/latest/install/kubernetes/helm-quickstart/) - Reasonable knowledge about Kong. For more information, see [Kong Documentation](https://docs.konghq.com/). #### Kong documentation You can also follow the steps in the Kong documentation to install Traceable’s Kong plugin. For more information, see [Overview](https://docs.konghq.com/hub/traceableai/traceableai/). --- ### Deployment modes Traceable’s Kong integration provides two modes for exporting request data: synchronous (sync) and asynchronous (async). The default mode is synchronous; however, starting with Traceable’s Kong plugin version 2.1.0, an asynchronous mode is also available for enhanced efficiency. In **sync mode**, the Kong integration makes two calls to the Traceable Platform Agent (TPA)—one for request authorization and another for response capture. This mode is ideal for deployments that require immediate, step-by-step request and response processing. **Async mode**, available from plugin version 2.1.0 onward, 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] > 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. | Parameter | Description | Allowed values | Default | | --- | --- | --- | --- | | `mode` | Toggles between sync and async mode. | `sync`, or `async` | `sync` | | `buffer_request_body` | Buffers the request body during the access phase for `async` mode. Required to capture request data in `async` mode. | `true`, or `false` | `true` | --- ## Deployment Deploying Traceable's plugin for Kong has the following high-level steps: 1. Deploy Traceable Platform agent 2. Inject TME (Traceable module extension) into Kong Proxy 3. Adding the Traceable plugin to Kong 4. Configure the Traceable plugin --- ### Step 1 – Deploy Traceable Platform agent To deploy the Traceable Platform agent, go through the steps mentioned in [Helm](/docs/helm) topic. --- ### Step 2 – Inject Traceable module extension (TME) Complete the following steps to inject the Traceable module extension: > [!NOTE] > Note > > Skip this step if you are using `async` mode. 1. Enter the following command to identify the name of Kong deployment: ActionScript ```actionscript ❯ kubectl get deployments -n kong NAME              READY   UP-TO-DATE   AVAILABLE   AGE quickstart-kong   1/1     1            1           45m ``` 2. Label the Kong namespace to allow injection: ActionScript ```actionscript kubectl label ns kong traceableai-inject-tme=enabled ``` 3. Patch the deployment to add TME. Enter the following command: ActionScript ```actionscript kubectl patch deployment.apps/quickstart-kong -p '{"spec": {"template": {"metadata": {"annotations": {"tme.traceable.ai/inject": "true"}}}}}' -n kong ``` #### Verification Enter the following command to verify that TME was successfully injected: ```actionscript ❯ kubectl get pods -n kong NAME                                               READY   STATUS      RESTARTS      AGE quickstart-kong-59d55b78cc-qc2h8                   3/3     Running     2 (12m ago)   13m ``` --- ### Step 3 — Add Traceable's Kong plugin Complete the following steps to add Traceable's Kong plugin: 1. Download the Traceable plugin from LuaRocks. Enter the following command: ActionScriptActionScript ```actionscript curl -LO https://luarocks.org/manifests/traceableai/kong-plugin-traceable-2.1.2-1.src.rock ``` 2. Unpack the luarock. Enter the following command: ActionScriptActionScript ```actionscript luarocks unpack kong-plugin-traceable-2.1.2-1.src.rock ``` 3. Create a configmap for rock. Enter the following command: YAMLYAML ```yaml kubectl create configmap -n kong kong-plugin-traceable --from-file ./kong-plugin-traceable-2.1.2-1/kong-plugin-traceable-2.1.2/kong/plugins/traceable/ ``` You have the following two options to insert the plugin into Kong: - **Option 1 —** Modify the Kong Helm values - **Option 2 —** Apply a deployment patch #### Option 1 (with DB only) Traceable recommends modifying Kong Helm values as the preferred option, as minimal changes are required. In your Kong Helm values file, add the following: ```yaml # 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 ``` Enter the following command to upgrade the deployment using the modified `kong-values.yml` file: ```actionscript helm upgrade quickstart kong/kong --namespace kong --values kong-values.yaml ``` #### Option 2 – Applying a deployment patch To apply a deployment patch, copy the following content into a new file named `kong-traceable-patch.yaml`. ```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 ``` Enter the following command: ```actionscript kubectl patch deployments.apps --type strategic -n kong ingress-kong --patch-file kong-traceable-patch.yml ``` Choosing either option one or option 2 makes Kong aware of the presence of the Traceable plugin. --- ### 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` would be `http://agent.traceable:5442`. Use the public IP address if the Traceable Platform agent is outside the cluster. #### **DBless mode** Configure Traceable plugin. Use the following templates to apply both plugins globally using `plugins.yml` file. Use the template based on the mode: - **Sync mode** ```yaml apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata:  annotations:    kubernetes.io/ingress.class: kong  name: traceable-plugin  labels:    global: "true" config:  ext_cap_endpoint: http://localhost:5442  mode: "sync" plugin: traceable ``` - **Async mode** ```yaml plugins:  - name: traceable    config:      ext_cap_endpoint: "http://traceable-agent:5442"      mode: "async"      buffer_request_body: true ``` #### **DB mode** When you run Kong with DB, you must use the Admin API to enable plugins. Access the Kong Admin API. By default, this is available only on `localhost:8444`. Depending on your setup, you may or may not need the `--insecure `flag. Send the following CURL requests to enable the Traceable plugin. Enter the following to enable Traceable plugin based on your mode: - **Sync mode** ActionScript ```actionscript curl -X POST --insecure https://localhost:8444/plugins/ \  --data "name=traceable" \  --data config.ext_cap_endpoint=http://localhost:5442 \  --data config.mode=sync ``` - **Async mode** ```actionscript curl -X POST --insecure https://localhost:8444/plugins/ \  --data "name=traceable" \  --data config.ext_cap_endpoint=http://traceble-agent:5442 \  --data config.mode=async \  --data config.buffer_request_body=true ``` --- ### Step 5 - Rollout Execute rollout start. Enter the following command: ActionScript ```actionscript kubectl rollout restart deployment -n kong ``` --- ## Verification Send traffic through Kong gateway and Kong Proxy, then view the details in Traceable Platform to verify that the installation was successful. ```actionscript ❯ 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 ``` --- ## Upgrade You can upgrade the Traceable plugin by repeating the curl commands in [Step 3](/v1/docs/traceable-kong-v2#step-3-—-add-traceables-kong-plugin) 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 `<new-version-number>`in the following commands with the latest version number. ActionScriptActionScript ```actionscript curl -LO https://luarocks.org/manifests/traceableai/kong-plugin-traceable-.src.rock ``` 2. Unpack the luarock. Enter the following command: ActionScriptActionScript ```actionscript luarocks unpack kong-plugin-traceable-.src.rock ``` 3. Delete the old configmap: ```actionscript kubectl delete configmap -n kong kong-plugin-traceable ``` 4. Recreate a configmap. Enter the following command: ```actionscript kubectl create configmap -n kong kong-plugin-traceable --from-file ./kong-plugin-traceable-/kong-plugin-traceable-/kong/plugins/traceable/ ``` **Restart** Kong by entering the following command: ActionScriptActionScript ```actionscript 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: ActionScriptActionScript ```actionscript kubectl delete kongclusterplugin traceable-plugin ``` **Restart** Kong by entering the following command: ```actionscript kubectl rollout restart deployment -n kong ``` #### DB uninstallation Run the following command to fetch a JSON response that lists all the installed plugins. Each plugin has a unique UUID associated with it. ```actionscript curl -X GET "http://localhost:8444/plugins" ``` Following is a sample JSON response for the above command: ```json {  "data": [    {      "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",      "name": "traceable-plugin",      ...    },    ...  ] } ``` To delete a plugin, use the UUID of that plugin in the following command: ```json curl -X DELETE "http://localhost:8444/plugins/" ``` **Restart** Kong by entering the following command: ```actionscript 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. ```yaml 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: ```yaml blockingStatusCode: blockingMessage: injector:  blockingConfig:    blockingStatusCode:    blockingMessage: ``` Make sure that the status code is set between 400 and 499. If you add values outside the 4xx range, then 403 (the default status code) is displayed in the Traceable Platform.