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. 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 3.0.0.0 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:
  ActionScriptActionScript

  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:
  • DBless – Kong Kubernetes Ingress Controller as an API Gateway: Tutorial
  • With DB – Install with Kong Gateway using Helm – v3.0x | Kong Docs
• 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.

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

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:
   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

   kubectl label ns kong traceableai-inject-tme=enabled

3. Patch the deployment to add TME. Enter the following command:
   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:

❯ 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:

1. Download the Zipkin plugin. Enter the following command:
   ActionScriptActionScript

   curl -LO https://luarocks.org/manifests/kong/kong-plugin-zipkin-1.4.1-1.src.rock

2. Unpack the luarock. Enter the following command:
   ActionScriptActionScript

   luarocks unpack kong-plugin-zipkin-1.4.1-src.rock

3. Create a configmap for rock. Enter the following:
   ActionScriptActionScript

   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:
   ActionScriptActionScript

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

   Note:

   Rock version 1.0.14 does not support Kong 3.0.0.0. Rock version 1.0.15 and later includes support for Kong 3.0.0.0
5. Unpack the luarock. Enter the following command:
   ActionScriptActionScript

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

6. Create a configmap for rock. Enter the following command:
   YAMLYAML

   kubectl create configmap -n kong kong-plugin-traceable --from-file ./kong-plugin-traceable-1.0.16-1/kong-plugin-traceable-1.0.16/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
plugins:
  configMaps:
  - 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
metadata:
  name: ingress-kong
  namespace: kong
spec:
  template:
    spec:
      containers:
      - name: proxy
        env:
        - name: KONG_PLUGINS
          value: bundled,traceable,zipkin
        - name: KONG_LUA_PACKAGE_PATH
          value: "/opt/?.lua;;"
        volumeMounts:
        - name: kong-plugin-traceable
          mountPath: /opt/kong/plugins/traceable
        - name: kong-plugin-zipkin
          mountPath: /opt/kong/plugins/zipkin
      volumes:
      - name: kong-plugin-traceable
        configMap:
          name: kong-plugin-traceable
      - name: kong-plugin-zipkin
        configMap:
          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.
  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
  plugin: traceable
  
  ---
  apiVersion: configuration.konghq.com/v1
  kind: KongClusterPlugin
  metadata:
    name: globalzipkin
    annotations:
      kubernetes.io/ingress.class: kong
    labels:
      global: "true"
  config:
    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:
    ActionScript

    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:
    ActionScriptActionScript

    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"

Step 5 - Rollout

Execute rollout start. Enter the following command:

kubectl rollout restart deployment -n kong

Verification

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   1.12.9.28        1.12.9.28   80:30825/TCP,443:31308/TCP      67m

Upgrade

You can upgrade the Traceable plugin and Zipkin plugin by repeating the curl commands in Step 3 with new versions of the plugin. 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

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

2. Unpack the luarock. Enter the following command:
   ActionScriptActionScript

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

3. Delete the old configmap: 

   kubectl delete configmap -n kong kong-plugin-traceable

4. Recreate a configmap. Enter the following command:

   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/

Upgrade Zipkin plugin

Enter the following commands. Replace <new-version-number> in the following commands with the latest version number.

1. Enter the following curl command to upgrade the Zipkin plugin.
   ActionScriptActionScript

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

2. Unpack the luarock. Enter the following command:

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

3. Delete the old configmap: 
   ActionScriptActionScript

   kubectl delete configmap -n kong kong-plugin-zipkin

4. Recreate the configmap.
   ActionScriptActionScript

   kubectl create configmap -n kong kong-plugin-zipkin --from-file ./kong-plugin-zipkin-<new-version-number>/kong-plugin-zipkin-<new-version-number>/kong/plugins/zipkin/

Restart Kong by entering 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 and Zipkin plugin for a DBless installation, run the following commands:

• Uninstall Traceable plugin - Run the following command:
  ActionScriptActionScript

  kubectl delete kongclusterplugin traceable-plugin

• Uninstall Zipkin plugin - Run the following command:
  ActionScriptActionScript

  kubectl delete kongclusterplugin zipkin

Restart Kong by entering the following command:

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.

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