- 28 Aug 2024
- 6 Minutes to read
- Print
- PDF
Traceable Kong v2
- Updated on 28 Aug 2024
- 6 Minutes to read
- Print
- PDF
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 quickly build robust, high-performance APIs that scale horizontally. Kong also has built-in security, load balancing, and monitoring features to track your system's health and performance in real-time. Traceable provides a plugin for your Kong API gateway deployment. The following diagram provides high-level information about the deployment.
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.
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.
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 OSThe 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.
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
With DB – Install with Kong Gateway using Helm – v3.0x | Kong Docs
Reasonable knowledge about Kong. For more information, see Kong Documentation.
Kong documentation
You can also follow the steps mentioned in Kong documentation to install Traceable’s Kong plugin. For more information, see Overview.
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 plugin to Kong
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 – 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's Kong plugin
Complete the following steps to add Traceable's Kong plugin:
Download the Traceable plugin from LuaRocks. Enter the following command:
ActionScriptActionScript
curl -LO https://luarocks.org/manifests/traceableai/kong-plugin-traceable-2.0.2-1.src.rock
Unpack the luarock. Enter the following command:
ActionScriptActionScript
luarocks unpack kong-plugin-traceable-2.0.2-1.src.rock
Create a configmap for rock. Enter the following command:
YAMLYAML
kubectl create configmap -n kong kong-plugin-traceable --from-file ./kong-plugin-traceable-2.0.2-1/kong-plugin-traceable-2.0.0/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:
# 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:
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
.
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:
kubectl patch deployments.apps --type strategic -n kong ingress-kong --patch-file kong-traceable-patch.yml
Choosing either option 1 or option 2 makes Kong aware of the presence of the Traceable plugin.
Step 4 – Configure Traceable plugin
Choose from DBless or with DB:
DBless – Configure Traceable plugin. Use the following templates to apply both plugins globally using
plugins.yml
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
With DB – 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:ActionScript
curl -X POST --insecure https://localhost:8444/plugins/ \ --data "name=traceable" \ --data config.ext_cap_endpoint=http://localhost:5442
Step 5 - Rollout
Execute rollout start. Enter the following command:
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.
❯ 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 with new plugin versions. For example:
Upgrade Traceable plugin
Complete the following steps:
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
Unpack the luarock. Enter the following command:
ActionScriptActionScript
luarocks unpack kong-plugin-traceable-<new-version-number>.src.rock
Delete the old configmap:
kubectl delete configmap -n kong kong-plugin-traceable
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/
Restart Kong by entering the following command:
ActionScriptActionScript
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
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 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
(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 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.