Provide Feedback

Koko

Koko is the next generation Control Plane (CP) for Kong API Gateway's Hybrid deployment mode.
Koko is designed to simplify Kong Gateway deployments and to decouple CP aspects from the powerful underlying NGINX/OpenResty Data Plane (DP) stack.

Background

Koko is the next generation CP for Kong API Gateway's Hybrid mode deployment. Koko is designed to simplify Kong Gateway deployments and decouple CP aspects from the powerful underlying NGINX/OpenResty DP stack. Kong is an API gateway built on top of Nginx and OpenResty. When Kong was launched in 2015, all Kong nodes were alike and were connected to a database to form a cluster. This made the deployment straightforward enough to deploy anywhere with minimal effort.

In 2020, a new Hybrid mode of operation was introduced - which splits all features of Kong into two broad buckets: the control plane and the data plane. This split has many advantages, including better scalability, ease of operation, a better security posture and improved performance in some cases. The split, however, was organic, i.e., Kong evolved slowly towards such a separation. There is no clear boundary of where the control plane ends and where the data plane begins.

On the other hand, significant progress has been made in the infrastructure landscape in the last decade. The infrastructure products and abstractions have evolved significantly, and Kong's control plane is proving to be a bottleneck in this area. The long-term focus of the Koko project is to replace the existing Lua-based control plane of Kong.

Introduction

Koko is the next-generation control plane for Kong Gateway that aims to replace the existing Lua-based control plane. The project is written in Go.

Koko's current goal is to achieve parity with existing features before new features are added in. Here is a comparison of the progress and future plans.

Comparison with existing Kong's Control Plane

This document provides a high-level comparison of Koko and Kong Gateway's built-in Control-Plane.

The following key is used within the document:

  • : Not supported and isn't likely to be supported.
  • : Supported
  • 📆 : Planned for a future release
Feature Kong's builtin CP Koko
Core API
Existing HTTP Admin-API 📆
All core entities
Auth plugins 📆
decK integration 📆
Tag-based filtering
New versioned Admin-API
gRPC Admin API
Admin API language-specific clients 📆
Storage
Postgres
SQLite
MySQL
MariaDB 📆
SQL Server 📆
CockroachDB 📆
Plugins
Plugins with Lua-schemas
OpenResty-specific schema validations
Plugins with Custom DAOs
Adopting standards
JSON schemas for resources
OpenAPI spec
Observability
Structured logs
Deep Prometheus metrics 📆
Distributed tracing (Admin) 📆
Data-plane
wRPC-based DP communication
Cluster state visibility
mTLS-based Data-Plane auth 📆
Non mTLS-based Data-Plane auth 📆
k8s Gateway API integration 📆
Misc
Secrets referencing 📆
Version compatibility insights

Plugins

All plugins, other than the ones noted below are supported by Koko.

The following plugins are not supported:

  • acl
  • basic-auth
  • hmac-auth
  • jwt
  • key-auth
  • oauth2

Of these, all plugins except the oauth2 plugin are planned for inclusion. oauth2 plugin is not compatible with Hybrid mode of Kong and hence there are no plans to support it.

Have a question?

If you have a question, please open a GitHub Issue in this repository.

Quickstart

Create a new directory

mkdir koko-demo
cd koko-demo

Create certificates for CP-DP authentication

mkdir certs
docker run -u $(id -u ${USER}):$(id -g ${USER}) -v $(pwd)/certs:/certs kong kong hybrid gen_cert /certs/cluster.crt /certs/cluster.key
# make the key readable, required for following containers
chmod +r certs/cluster.key

Docker compose file

Download the docker-compose.yml file:

curl https://raw.githubusercontent.com/Kong/koko/main/docs/assets/docker-compose.yml -o docker-compose.yml

This docker compose file includes two services - Koko and Kong.

version: "3.9"

networks:
kong-net:
external: false

services:
koko:
image: "kong/koko:latest"
command: "serve"
environment:
KOKO_DATABASE_SQLITE_IN_MEMORY: true
KOKO_CONTROL_SERVER_TLS_CERT_PATH: "/certs/cluster.crt"
KOKO_CONTROL_SERVER_TLS_KEY_PATH: "/certs/cluster.key"
restart: on-failure:3
networks:
- kong-net
volumes:
- ./certs:/certs
ports:
- 3000:3000
kong:
image: "kong:3.0"
environment:
KONG_ADMIN_ACCESS_LOG: /dev/stdout
KONG_ADMIN_ERROR_LOG: /dev/stderr
KONG_PROXY_LISTEN: "0.0.0.0:8000"
KONG_PROXY_ACCESS_LOG: /dev/stdout
KONG_PROXY_ERROR_LOG: /dev/stderr
KONG_DATABASE: "off"
KONG_ROLE: data_plane
KONG_CLUSTER_MTLS: shared
KONG_CLUSTER_CERT: /certs/cluster.crt
KONG_CLUSTER_CERT_KEY: /certs/cluster.key
KONG_NGINX_WORKER_PROCESSES: "1"
KONG_CLUSTER_CONTROL_PLANE: kong_clustering:3100
ports:
- 8000:8000
networks:
- kong-net
links:
- koko:kong_clustering
restart: on-failure:3
volumes:
- ./certs:/certs

Start Docker containers

docker compose up

Start using Kong

Configure a service and a route:

curl -X PUT \
http://localhost:3000/v1/services/001156b4-b228-4c15-91a1-2de253f2a95c \
-d '{ "name": "mockbin", "host": "mockbin.org" }' \
-H 'content-type: application/json'

curl -X POST \
http://localhost:3000/v1/routes \
-d '{ "name": "mockbin", "paths": [ "/foo" ], "service": { "id": "001156b4-b228-4c15-91a1-2de253f2a95c" } }' \
-H 'content-type: application/json'

Configure a rate-limting plugin on the service:

curl -X POST \
http://localhost:3000/v1/plugins \
-d '{ "name": "rate-limiting", "config": { "minute": 10 }, "service": { "id": "001156b4-b228-4c15-91a1-2de253f2a95c" }}' \
-H 'content-type: application/json'

Execute a request against Kong:

curl -v http://localhost:8000/foo/status/200

Observe that Kong correctly routes the request to mockbin.org. Kong also enforces appropriate rate-limits and the rate-limits can be found in the HTTP response headers.

# some headers omitted

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 38
Content-Type: application/json; charset=utf-8
RateLimit-Limit: 10
RateLimit-Remaining: 9
RateLimit-Reset: 15
Server: cloudflare
Vary: Accept, Accept-Encoding
Via: kong/3.0.0
X-Kong-Proxy-Latency: 3
X-Kong-Upstream-Latency: 94
X-Powered-By: mockbin
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9
{
"code": "200",
"message": "OK"
}

Check tracked data plane node

Koko tracks each node that connects to it, and you can grab that information using an Admin API call:

curl http://localhost:3000/v1/nodes

You should see one node with its version information as well as compatibility status.

{
"items": [
{
"id": "7bc59b4c-c518-43fc-8c11-1471e893ed5f",
"version": "3.0.0",
"hostname": "e2ed9b62b5ae",
"last_ping": 1663973331,
"type": "kong-proxy",
"created_at": 1663973153,
"updated_at": 1663973331,
"config_hash": "696ac398bd29ed61696ac398bd29ed61",
"compatibility_status": {
"state": "COMPATIBILITY_STATE_FULLY_COMPATIBLE"
}
}
],
"page": {
"total_count": 1
}
}

Next steps

Please explore the OpenAPI v2 spec of the Admin API offered by Koko to configure Kong, or hook up another Kong data plane.

Product

Gateway

Stability

Tech Preview