Skip to main content
Kong

Search

Deploying the Kong integration

© 2024 Cequence Security. All Rights Reserved.

Deploying the Kong integration

  • Updated on
  • ~ minute read
Download PDF

You can deploy the Kong integration for the Cequence Unified API Protection (UAP) platform as a Docker container, in Kubernetes, or directly onto the host.

Before you start

Confirm that you have access to the following configuration variables for your Cequence UAP platform instance.

  • auth_domain is the domain name that checks authentication credentials.
  • edge_domain is the domain name at the API edge.
  • client_id is a unique ID that you generate at the Cequence UAP UI.
  • client_secret is a unique secret associated with the client_id that you generate at the Cequence UAP UI.
  • max_message_size is an integer that defines the maximum size of a single batch in bytes. By default, this value is 10000000.
  • batch_interval is an integer that defines the waiting period between sending batches. By default, this value is 5.
  • debug_mode is a Boolean that specifies whether or not the system operates in debug mode. By default, this value is false.

Generating the client ID and client secret

Several Cequence components must authenticate to the Cequence UAP platform in order to transmit and receive data. Create authentication credentials in the Cequence UAP platform to enable this authentication.

  1. Log in to the UAP management portal UI.
    The URL for the management portal is typically of the form https://ui.<your-tenant-name>.<domain>. Replace <your-tenant-name> with the name of your Cequence tenant organization. Replace <domain> with your domain name.
  2. Select General Settings > User Management.
    The User Management pane appears.
  3. Click the Clients tab.
  4. Click Add New Client.
    The new client dialog box appears.
  5. Type the client name in the Client Name field.
    This name is the client ID. Note the client ID for later use.
  6. Enable the Traffic Ingestion toggle.
  7. (Optional) To change the token lifespan from the default of 1800 seconds, type a whole number of seconds in Token Lifespan.
  8. Click Save.
    A dialog box with the client secret appears.
  9. Click the blue Copy icon to copy the secret to the clipboard, then click Close.
    The client is now set up. Note the client name for future use.
    The client list appears.
  10. Note the value of the client secret for later use. This value will not be shown again later on the UI for security reasons.

Deploying the Docker container

  1. Run the following command.
    % export KONG_VERSION=<kong version>
    This command sets the KONG_VERSION environment variable.
  2. Create a file named docker-compose.yml. There is a sample file at the end of this article.
  3. Choose and run the command appropriate to your operating system.
    Ubuntu
    KONG_LUA_SSL_TRUSTED_CERTIFICATE=/etc/ssl/certs/ca-certificates.crt docker compose --profile database up -d
    Alpine
    KONG_LUA_SSL_TRUSTED_CERTIFICATE=/etc/ssl/cert.pem docker compose --profile database up -d
  4. Run the following command.
    % docker ps
    Check the output for the name in the NAMES column that contains the string gateway. Note this name for future reference.

Installing the Cequence plugin

  1. Run the following command. 
    % mkdir /home/cequence.ai && cd $_
    This command creates a directory named cequence.ai and navigates to that directory.
  2. Download the Cequence plugin compressed archive file to the cequence.ai folder.
  3. Run the following command.
    % unzip kong-api-transactions.zip
    This command extracts the archive.
  4. Run the following commands to install the plugin.
    % cd kong-api-transactions/scripts
    % ./install-cequence.sh
  5. Edit the kong.conf file to add the following line.
    plugins = bundled,cequence-ai-unified
  6. Run the following commands to reload the plugin.
    % kong prepare
    % kong reload

Testing the Cequence plugin

  1. Run the following command to create the service. 
    curl -i -X POST --url http://localhost:8001/services/ --data 'name=mock-service' --data "url=$MOCK_API_URL"
  2. Run the following command to create a route. 
    curl -i -X POST --url http://localhost:8001/services/mock-service/routes --data 'paths[]=/mock-request'
  3. Run the following command to attach the plugin to the service. 
    curl -X POST http://localhost:8001/services/mock-service/plugins/ \
    --data "name=cequence-ai-unified" \
    --data "config.auth_domain=https://auth.common.eng1.int.cequence.ai/auth/realms/defender-1/protocol/openid-connect/token" \
    --data "config.edge_domain=https://edge.defender-1.eng1.int.cequence.ai/api-transactions" \
    --data "config.client_id=defender-1-client" \
    --data "config.client_secret=np56jAWBSGemIWhTtKKzNimuGH8eUNWV"

[@Bhasker/@kaustabh: What does a successful test look like?]

Sample docker-compose.yml file

version: '3.9'

networks:
  kong-net:
    external: false

services:
  kong-migrations:
    image: kong/kong-gateway:$KONG_VERSION
    command: kong migrations bootstrap
    profiles: ["database"]
    depends_on:
      - kong-database
    networks:
      - kong-net
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_PASSWORD: kongpass
      KONG_PASSWORD: test
    restart: on-failure

  kong-database:
    image: postgres:13
    profiles: ["database"]
    environment:
      POSTGRES_USER: kong
      POSTGRES_DB: kong
      POSTGRES_PASSWORD: kongpass
    networks:
      - kong-net
    ports:
      - 5432:5432

  kong-gateway:
    container_name: kong-gateway_$KONG_VERSION
    image: kong/kong-gateway:$KONG_VERSION
    user: root
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PASSWORD: test
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kongpass
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_PROXY_ERROR_LOG: /dev/stderr
      KONG_ADMIN_ERROR_LOG: /dev/stderr
      KONG_ADMIN_LISTEN: 0.0.0.0:8001
      KONG_ADMIN_GUI_URL: http://localhost:8002
      KONG_LUA_SSL_TRUSTED_CERTIFICATE: /etc/ssl/cert.pem
    command: ["bash", "-c", "if [[ -n $$(echo $KONG_VERSION | grep -E '.*alpine') ]]; then apk update && apk add zip git; else apt-get update && apt-get install -y unzip zip git; fi && kong start --v"]
    networks:
      - kong-net
    ports:
      - 8000:8000
      - 8001:8001
      - 8444:8444
      - 8002:8002
      - 8445:8445
      - 8003:8003
      - 8004:8004
    restart: on-failure

Deploying in Kubernetes

Before you begin, create a Kubernetes namespace, if necessary, and confirm that you have the Kong control plane and data plane installed.

  1. Download the compressed archive file that contains the Cequence plugin files.
  2. Extract the archive.
  3. Remove the /etc/kong/kong.conf file, if present.
  4. From the directory where you extracted the archive, run the following command. 
    kubectl create cm kong-plugin-cequence --from-file=cequence-ai-unified [-n <kong-namespace>]
    When you are installing Kong in a namespace, replace <kong-namespace> with the name of the namespace. Otherwise, omit the [-n ... ] portion of the command.
  5. In a text editor, create a file named ceq-cp.yml with the following contents. 
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: kong-cp-kong
      namespace: kong
    spec:
      template:
        spec:
          securityContext:
            fsGroup: 1001
            runAsUser: 1001
            runAsGroup: 1001
          containers:
            - name: proxy
            env:
              - name: KONG_PLUGINS
                value: "bundled,cequence-ai-unified"
              - name: KONG_LUA_PACKAGE_PATH
                value: "/opt/?.lua;/opt/kong/plugins/cequence-ai-unified/?.lua;;"
            volumeMounts:
              - name: kong-plugin-cequence
                mountPath: "/opt/kong/plugins/cequence-ai-unified/handler.lua"
                subPath: handler.lua
              - name: kong-plugin-cequence
                mountPath: "/opt/kong/plugins/cequence-ai-unified/schema.lua"
                subPath: schema.lua
              - name: kong-plugin-cequence
                mountPath: "/etc/kong/kong.conf"
                subPath: kong.conf
            volumes:
              - name: kong-plugin-cequence
                configMap:
                  name: kong-plugin-cequence
    The value for the KONG_PLUGINS variable must include any additional plugins in use. The value of the name metadata field must match the name of the control plane for your Kong installation. The value of the namespace metadata field must match the name of the Kong namespace.
  6. Run the following command. 
    % kubectl -n <kong-namespace> apply -f ceq-cp.yml
    This command deploys the Cequence plugin to the Kong control plane.
  7. In a text editor, create a file named ceq-dp.yml with the following contents. 
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: kong-dp-kong
      namespace: kong
    spec:
      template:
        spec:
          securityContext:
            fsGroup: 1001
            runAsUser: 1001
            runAsGroup: 1001
          containers:
            - name: proxy
            env:
              - name: KONG_PLUGINS
                value: "bundled,cequence-ai-unified"
              - name: KONG_LUA_PACKAGE_PATH
                value: "/opt/?.lua;/opt/kong/plugins/cequence-ai-unified/?.lua;;"
            volumeMounts:
              - name: kong-plugin-cequence
                mountPath: "/opt/kong/plugins/cequence-ai-unified/handler.lua"
                subPath: handler.lua
              - name: kong-plugin-cequence
                mountPath: "/opt/kong/plugins/cequence-ai-unified/schema.lua"
                subPath: schema.lua
              - name: kong-plugin-cequence
                mountPath: "/etc/kong/kong.conf"
                subPath: kong.conf
            volumes:
              - name: kong-plugin-cequence
                configMap:
                  name: kong-plugin-cequence
    The value for the KONG_PLUGINS variable must include any additional plugins in use. The value of the name metadata field must match the name of the data plane for your Kong installation. The value of the namespace metadata field must match the name of the Kong namespace.
  8. Run the following command. 
    % kubectl -n <kong-namespace> apply -f ceq-dp.yml
    This command deploys the Cequence plugin to the Kong data plane.

Enabling the Kong plugin

Enabling the Cequence Kong plugin requires configuration with required parameter values. These values are marked with angle brackets and in italics in the script listing in this section. Refer to Before you start for a full listing.

You can enable the Kong plugin globally, or for a specific service, as shown in the following example.

#!/bin/bash
EDGE_URL=<edge-url>/api-transactions
CLIENT_ID=<client-id>
CLIENT_SECRET=<client-secret>
AUTH_URL=<auth-url>
printf '\n===> Attaching plugin .......................................\n'
curl -X POST http://localhost:8001/services/<client-service-name>/plugins/ \
     --data "name=cequence-ai-unified" \
     --data "config.auth_domain=$AUTH_URL" \
     --data "config.edge_domain=$EDGE_URL" \
     --data "config.client_id=$CLIENT_ID" \
     --data "config.client_secret=$CLIENT_SECRET"

To apply the plugin globally, modify the script in the manner shown.

#!/bin/bash
EDGE_URL=<edge-url>/api-transactions
CLIENT_ID=<client-id>
CLIENT_SECRET=<client-secret>
AUTH_URL=<auth-url>
printf '\n===> Attaching plugin .......................................\n'
curl -X POST http://localhost:8001/plugins/ \ <====== API to enable plugin globally.
     --data "name=cequence-ai-unified" \
     --data "config.auth_domain=$AUTH_URL" \
     --data "config.edge_domain=$EDGE_URL" \
     --data "config.client_id=$CLIENT_ID" \
     --data "config.client_secret=$CLIENT_SECRET"

Verifying plugin installation

To verify that the plugin has installed properly, enable port forwarding to the Kong control-plane pod by running the following commands.

% kubectl get pods
% kubectl port-forward <kong-control-plane-pod-name> 8001 8001

After forwarding the ports, run the following command and check the output.

% curl localhost:8001/plugins

Output for a properly functioning plugin should resemble the following example.

{
  "next": null,
  "data": [
    {
      "consumer_group": null,
      "tags": null,
      "updated_at": 1740158922,
      "created_at": 1740158922,
      "config": {
                  "client_secret": "ceq-client-secret",
                  "edge_domain": "<edge-uril>/api-transactions",
                  "debug_mode": false,
                  "auth_domain": "<auth-url>",
                  "max_message_size": 10000000,
                  "client_id": "ceq-client-id",
                  "batch_interval": 5
                },
      "instance_name": null,
      "service": {
                  "id": "b9fc5ae2-85c6-4455-a1b6-c13c3f88f0e1"
                 },
      "route": null,
      "protocols": [
                    "grpc",
                    "grpcs",
                    "http",
                    "https"
                   ],
      "enabled": true,
      "name": "cequence-ai-unified", <==========
      "id": "8488f458-8450-4b4c-aefb-9c1919328e81",
      "ordering": null,
      "consumer": null
     }
  ]
}

Check the Kong pod logs for output similar to the following example.

2025/02/24 22:02:16 [notice] 2564#0: *326523 [kong] handler.lua:615 Cequence: Token URL is - https://auth.common.eng3.int.cequence.ai/auth/realms/user-kaustubh/protocol/openid-connect/token, context: ngx.timer
2025/02/24 22:02:16 [notice] 2564#0: *326523 [kong] handler.lua:621 Cequence: Unified token request successful. Token will be cached for reuse., context: ngx.timer
2025/02/24 22:02:16 [notice] 2564#0: *326523 [kong] handler.lua:632 Cequence: Value of ttl 36000 - , context: ngx.timer
2025/02/24 22:02:16 [notice] 2564#0: *326523 [kong] handler.lua:727 Total number of txn processed till now - 28, context: ngx.timer
2025/02/24 22:02:16 [notice] 2564#0: *326523 [kong] handler.lua:728 Total number of batches sent - 10, context: ngx.timer
2025/02/24 22:02:16 [notice] 2564#0: *326523 [kong] handler.lua:729 Cequence: Unified event response for entries - 1 is {"status":"OK"}, context: ngx.timer

Traffic Validation

The Cequence plugin captures response and request details for traffic routed to an attached service, then forwards those details to the Cequence UAP platform.

You can further verify correct operation by sending test traffic and confirming that the test traffic is correctly captured.

Directly deploying Kong to the host

  1. Run the following command to download the Kong package to your host. 
    % curl -Lo kong-enterprise-edition-3.4.0.0.amd64.deb "https://download.konghq.com/gateway-3.x-ubuntu-$(lsb_release -sc)/pool/all/k/kong-enterprise-edition/kong-enterprise-edition_3.4.0.0_amd64.deb
  2. As the superuser, install the downloaded package by running the following command. 
    % sudo apt install -y ./kong-enterprise-edition-3.4.0.0.amd64.deb
  3. (Optional) Confirm that Kong is properly installed by running the following command. 
    % kong roar
  4. Install PostgreSQL by running the following commands as superuser. 
    % sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
    % wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
    % sudo apt update
    % sudo apt install postgresql-14
    % psql --version
  5. Change the user session to the postgres user by running the following command.
    % sudo -i -u postgres
    % psql
  6. Create the database, assigning appropriate permissions and a password, by running the following PostgreSQL commands. 
    CREATE USER kong;
    CREATE DATABASE kong OWNER kong;
    ALTER USER kong with password 'pss';
  7. As the superuser, copy the sample Kong configuration file to an active version by running the following command. 
    % sudo cp /etc/kong/kong.conf.default /etc/kong/kong.conf
  8. Edit the configuration file to match the following example. 
    admin_listen = 0.0.0.0:8001 reuseport backlog=16384, 0.0.0.0:8444 http2 ssl reuseport backlog=16384
    lua_ssl_trusted_certificate = /etc/ssl/certs/ca-certificates.crt
    #add the following line only if you want logging.
    nginx_http_log_format=show_everything '[$time_local] $remote_addr $remote_port $uri $request_uri $status $body_bytes_sent "$http_user_agent" $request_time "$upstream_connect_time" "$upstream_header_time" "$upstream_response_time" "$upstream_status" "$connection" "$connection_requests" "$upstream_addr" "$http_host"'
    database = postgres 
    pg_host = 127.0.0.1 
    pg_port = 5432
    pg_user = kong
    pg_password = pss
    pg_database = kong
  9. Run the following command to set the Kong password as an environment variable. 
    % export KONG_PASSWORD=pss
  10. Migrate data by running the following command as the superuser. 
    % sudo kong migrations bootstrap -c /etc/kong/kong.conf
  11. As the superuser, start kong by running the following command. 
    % sudo kong start -c /etc/kong/kong.conf
  12. (Optional) Confirm that Kong is operating by running the following command. 
    % curl -i localhost:8001/status
  13. In the home directory of each Kong node, create a subdirectory named cequence.ai by running the following command. 
    % mkdir /home/cequence.ai && cd$_
  14. Download the kong-api-transactions.zip compressed archive file to each Kong node.
  15. On each Kong node, extract the archive file and navigate to the kong-api-transactions/scripts directory.
  16. As the superuser, run the installer script. 
    % sudo ./install-cequence.sh
  17. In a text editor, add the cequence-ai-unified plugin name to the list of plugins in the Kong configuration file located at /etc/kong/kong.conf.
  18. (Optional) As the superuser, run the following commands to reload Kong to test the changes. 
    % sudo kong prepare
    % sudo kong reload
  19. Only perform this step when your service and routes are not already created in Kong. Run the following command to create a service. 
    curl -i -X POST --url http://localhost:8001/services/ --data 'name=<SERVICE_NAME>' --data "host=<HOST>" --data 'path=<PATH>'
  20. Only perform this step when your service and routes are not already created in Kong. Run the following command to create routes. 
    curl -i -X POST --url http://localhost:8001/services/<SERVICE_NAME>/routes --data 'paths[]=<PATH>'
  21. Run the following command on each running Kong Gateway node to register the Cequence plugin with the Kong service. 
    curl -X POST http://<kong-domain>:<kong-port>/services/<your-kong-service-name>/plugins/ \
         --data "name=cequence-ai-unified" \
         --data "config.auth_domain=<cequence_auth_domain>" \
         --data "config.edge_domain=<cequence_edge_domain>" \
         --data "config.client_id=<cequence_client_ID>" \
         --data "config.client_secret=<cequence_client_secret>"
    This registration enables the plugin to run asynchronously every time a given Kong service receives an API request.

Uninstalling the Kong plugin

To uninstall the Cequence Kong plugin, run the uninstall script, then remove the kong-api-transactions directory.

% cd kong-api-transactions/scripts
% ./uninstall-cequence.sh
% cd ../..
% rm -rf kong-api-transactions

In a text editor, open the kong.conf configuration file and remove the entries for cequence-ai-unified.

Was this article helpful?