• 13 Mar 2023
  • 5 Minutes to read
  • PDF


  • PDF

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

Traceable provides a plugin for your Kong API gateway deployment. As part of the deployment process, we will also deploy a Zipkin plugin. Traceable supports Kong's 1.4 and later, 2.x, and and later versions. The following diagram provides high-level information about the deployment. 

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 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
  • Traceable agent is installed and configured. For more information on Traceable agent installation, see Traceable agent.
  • Lua Rocks CLI is installed. If it is not already installed, enter the following command to install Lua Rocks:
    sudo apt-get install -y luarocks
  • IP address of the machine where the Traceable agent is running.
  • Make sure that Kong is installed. For more information on installing Kong, see:
  • Reasonable knowledge about Kong. For more information, see Kong Documentation.

In addition, make a note of the following:

  • In Kong 3.0, Zipkin is part of the default bundled plugins. You only need to configure Zipkin for Kong 3.0 or later. If you are using a Kong version which is earlier than 3.0, you need to install and configure Zipkin.
  • Kong db and dbless requires a slightly different configurations, for example:
    • Use the KongClusterPlugin if you are running Kong in dbless mode.
    • Use the Kong admin API if you are running Kong in db mode.


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 and Zipkin plugin to Kong
  4. Configure the Zipkin and Traceable plugin

Complete the following steps:

Step 1 – Deploy Traceable Platform agent

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

Step 2 – Inject Traceable module extension (TME)

Complete the following steps to inject the Traceable module extension:

  1. Enter the following command to identify the name of Kong deployment:
    ❯ 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:
    kubectl label ns kong traceableai-inject-tme=enabled
  3. Patch the deployment to add TME. Enter the following command:
    kubectl patch deployment.apps/quickstart-kong -p '{"spec": {"template": {"metadata": {"annotations": {"tme.traceable.ai/inject": "true"}}}}}' -n kong


Enter the following command to verify that TME was successfully injected:

❯ 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 and Zipkin's Kong plugin

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

If you are deploying Traceable for Kong 3.0 and later, then skip the Zipkin instructions to step 3. Zipkin is available as part of bundled plugins in Kong 3.0 and later.
  1. Download the Zipkin plugin. Enter the following command:
    curl -LO https://luarocks.org/manifests/kong/kong-plugin-zipkin-1.4.1-1.src.rock
  2. Unpack the luarock. Enter the following command:
    luarocks unpack kong-plugin-zipkin-1.4.1-src.rock
  3. Create a configmap for rock. Enter the following:
    kubectl create configmap -n kong kong-plugin-zipkin --from-file ./kong-plugin-zipkin-1.4.1-1/kong-plugin-zipkin-1.4.1/kong/plugins/zipkin/
  4. Download the Traceable plugin from LuaRocks. Enter the following command:
    curl -LO https://luarocks.org/manifests/traceableai/kong-plugin-traceable-1.0.14-1.src.rock
    Rock version 1.0.14 does not support Kong Rock version 1.0.15 adds the support for Kong
  5. Unpack the luarock. Enter the following command:
    luarocks unpack kong-plugin-traceable-1.0.14-1.src.rock
  6. Create a configmap for rock. Enter the following command:
    kubectl create configmap -n kong kong-plugin-traceable --from-file ./kong-plugin-traceable-1.0.14-1/kong-plugin-traceable-1.0.14/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 it requires minimal changes. In your Kong Helm values file, add the following:

# 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,zipkin

# Add this section at the very bottom of the file
  - name: kong-plugin-traceable
    pluginName: traceable
  - name: kong-plugin-zipkin
    pluginName: zipkin

Enter the following command to upgrade the deployment using the modified kong-values.yml file:

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-path.yml.

apiVersion: apps/v1
kind: Deployment
  name: ingress-kong
  namespace: kong
      - name: proxy
        - name: KONG_PLUGINS
          value: bundled,traceable,zipkin
        - name: KONG_LUA_PACKAGE_PATH
          value: "/opt/?.lua;;"
        - name: kong-plugin-traceable
          mountPath: /opt/kong/plugins/traceable
        - name: kong-plugin-zipkin
          mountPath: /opt/kong/plugins/zipkin
      - name: kong-plugin-traceable
          name: kong-plugin-traceable
      - name: kong-plugin-zipkin
          name: kong-plugin-zipkin

Enter the following command:

kubectl patch deployments.apps --type strategic -n kong quickstart-kong --patch-file kong-deployment-patch.yaml

Choosing either option 1 or option 2 makes Kong aware of the presence of Traceable plugin.

Step 4 – Configure Traceable and Zipkin plugin

Choose from DBless or with DB:

  • DBless – Configure both Zipkin and Traceable plugin. Use the following templates to apply both the plugins globally using plugins.yamlthe file.
    apiVersion: configuration.konghq.com/v1
    kind: KongClusterPlugin
        kubernetes.io/ingress.class: kong
      name: traceable-plugin
        global: "true"
      ext_cap_endpoint: http://localhost:5442
    plugin: traceable
    apiVersion: configuration.konghq.com/v1
    kind: KongClusterPlugin
      name: globalzipkin
        kubernetes.io/ingress.class: kong
        global: "true"
      http_endpoint: http://agent.traceableai.svc.cluster.local:9411/api/v2/spans
      sample_ratio: 1
      include_credential: true
      traceid_byte_count: 16
      header_type: preserve
      default_header_type: b3
    plugin: zipkin
  • With DB – When you run Kong with DB, you need to use 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 plugins for Traceable and Zipkin.
    • Enter the following to enable Traceable plugin:
      curl -X POST --insecure https://localhost:8444/plugins/ \
        --data "name=traceable" \
        --data config.ext_cap_endpoint=http://localhost:5442
    • Enter the following to enable the Zipkin plugin:
      curl -X POST --insecure https://localhost:8444/plugins/ \
          --data "name=zipkin"  \
          --data "config.http_endpoint=http://agent.traceableai.svc.cluster.local:9411/api/v2/spans" \
          --data "config.sample_ratio=1.0" \
          --data "config.include_credential=true" \
          --data "config.traceid_byte_count=16" \
          --data "config.header_type=preserve" \
          --data "config.default_header_type=b3"


Execute rollout start. Enter the following command:

kubectl rollout restart deployment -n kong


Send traffic through Kong gateway and Kong Proxy and view the details in 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   80:30825/TCP,443:31308/TCP   67m

Was this article helpful?

What's Next