- 13 Mar 2023
- 5 Minutes to read
-
PDF
Kong
- Updated on 13 Mar 2023
- 5 Minutes to read
-
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 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:ActionScript
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:
- Deploy Traceable Platform agent
- Inject TME (Traceable module extension) into Kong Proxy
- Adding the Traceable and Zipkin plugin to Kong
- 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:
- 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
- Label the Kong namespace to allow injection:ActionScript
kubectl label ns kong traceableai-inject-tme=enabled
- 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:
- Download the Zipkin plugin. Enter the following command:ActionScript
curl -LO https://luarocks.org/manifests/kong/kong-plugin-zipkin-1.4.1-1.src.rock
- Unpack the luarock. Enter the following command:ActionScript
luarocks unpack kong-plugin-zipkin-1.4.1-src.rock
- Create a configmap for rock. Enter the following:ActionScript
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/
- Download the Traceable plugin from LuaRocks. Enter the following command:ActionScript
curl -LO https://luarocks.org/manifests/traceableai/kong-plugin-traceable-1.0.14-1.src.rock
Note:Rock version 1.0.14 does not support Kong 3.0.0.0. Rock version 1.0.15 adds the support for Kong 3.0.0.0 - Unpack the luarock. Enter the following command:ActionScript
luarocks unpack kong-plugin-traceable-1.0.14-1.src.rock
- Create a configmap for rock. Enter the following command:YAML
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
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.yaml
the file.YAMLapiVersion: 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:ActionScript
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"
- Enter the following to enable Traceable plugin:
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