❗️

This adaptor is currently in beta. Please contact us at [email protected].

Our Observability Adapter for Kong Gateway allows you to monitor your live API traffic from Kong, without configuring API calls manually in the APImetrics platform. By deploying this adapter, APImetrics can read API calls that are routed through Kong, and automatically build your API Inventory. Once integrated, you can compare your live API traffic against your OAS spec, and set up synthetic endpoint monitoring automatically.

This can be done either locally via Docker or in a hosted environment.

📘

Note: The JavaScript plugin server requires the use of Kong 2.3 or higher.

Enable the Kong JavaScript Plugin Server

The APImetrics adaptor is written in JavaScript, so Kong’s JS plugin server must be running. If you don't already have the plugin server, kong-js-pdk can be installed using npm. To install the plugin server binary globally:

npm install kong-pdk -g

Set the JS plugin server using the following environment variables:

# If KONG_PLUGINSERVER_NAMES already has additional values, just add js to the list
ENV KONG_PLUGINSERVER_NAMES js
ENV KONG_PLUGINSERVER_JS_SOCKET /usr/local/kong/js_pluginserver.sock
ENV KONG_PLUGINSERVER_JS_START_CMD "/usr/local/bin/kong-js-pluginserver -v --plugins-directory /usr/local/kong/js-plugins"
ENV KONG_PLUGINSERVER_JS_QUERY_CMD "/usr/local/bin/kong-js-pluginserver --plugins-directory /usr/local/kong/js-plugins --dump-all-plugins"

📘

Note: Throughout this document, we assume JavaScript plugins are stored in: /usr/local/kong/js-plugins. If your deployment has been customised, update the environment variables accordingly.

For more details on configuring Kong's JS plugin server, see Kong’s JavaScript plugin server documentation.

Add the APImetrics Adaptor to the Kong Plugin Directory

Download the APImetrics adaptor, darkspark_kong.js.

Add darkspark_kong.js to the directory /usr/local/kong/js-plugins.

Add the APImetrics adaptor as an environment variable. Find the KONG_PLUGINS environment variable (depending on how your deployment is set up, this may be part of a docker configuration, like the example shown below, or set by a deployment/startup script) and append darkspark to the existing list.

# Allow plugins to be used. The plugin name is not the JS file name e.g. darkspark_kong.js
ENV KONG_PLUGINS "bundled,darkspark"

❗️

Note: Do not remove “bundled,” as the bundled plugins are required by Kong.

If you are unsure whether the environment variable is currently set, simply run the following command:

export | grep KONG_PLUGINS

A typical output from this command would be:

export KONG_PLUGINS='bundled,contxt'
export KONG_PLUGINSERVER_JS_QUERY_CMD='/usr/local/bin/kong-js-pluginserver --plugins-directory /usr/local/kong/js-plugins --dump-all-plugins'
export KONG_PLUGINSERVER_JS_SOCKET='/usr/local/kong/js_pluginserver.sock'
export KONG_PLUGINSERVER_JS_START_CMD='/usr/local/bin/kong-js-pluginserver -v --plugins-directory /usr/local/kong/js-plugins'
export KONG_PLUGINSERVER_NAMES='js'

If the environment variable KONG_PLUGINS does not currently exist, ensure it is added based on the current preferred means of managing environment variables in your infrastructure.

Specify the APImetrics Adaptor as a Service in the Kong YML Configuration File

The Kong configuration file has a services section where URLs/routes are defined - an adaptor entry should be added to any services that require APImetrics capabilities to be enabled.

The Kong configuration file is located by default at /etc/kong/kong.conf.

Open the configuration file, and add a new entry to each service, after the name and URL.

The entry required is:

- name: darkspark
  config:
    api_key: <API-KEY>

Replace with your APImetrics API key. To create a new API Key for APImetrics by following the tutorial here and choosing Ingress as your Access Level.

An example of the configuration file with APImetrics entries added is below:

services:
 - name: londonstockexchange-service
   url: https://www.londonstockexchange.com
   plugins:
     - name: darkspark
       config:
         api_key: <API-KEY>
   routes:
     - name: londonstockexchange-host-route
       hosts:
         - www.londonstockexchange.com
 - name: local-pii
   url: http://host.docker.internal:9090
   plugins:
     - name: darkspark
       config:
         api_key: <API-KEY>
   routes:
     - name: local-pii-route
       paths:
         - /

Now your APImetrics adaptor is configured. Navigate to the Inventory to see data populating.

Install APImetrics Adaptor With Kong Gateway Locally on Docker

Download the Docker Package

The Kong Gateway docker image can be found here.

To use this:

1. Decompress the tarball by using the command: gunzip kong-gateway.tar.gz.
2. Import the image into Docker by using the command: docker load -i kong-gateway.tar.gz.
3. Run the image in Docker, supplying a Kong configuration file by using the command: docker run -v '/path/to/kong-config.yml:/etc/kong/declarative.yml:ro' kong-gateway.

Update the sample Kong configuration file with your variables, and include the APImetrics adaptor in the plugins section for the required services. For more details, see Specify the Darkspark Plugin as a Service in the Kong YML Configuration File.

📘

Note: If you are targeting services running locally, use host.docker.internal instead of localhost.

Now, the Kong Gateway is running, you can make calls to it at http://localhost:8000. The calls you make will populate the Inventory.