Kong API Gateway: Enterprise Architecture and Deployment 2026

Introduction

Kong has established itself as the leading open-source API gateway and microservices management platform in 2026. Originally built as an API proxy, Kong has evolved into a comprehensive API management solution that handles traffic routing, authentication, rate limiting, transformation, and analytics for modern cloud-native architectures. With support for Kubernetes, service mesh integration, and an extensive plugin ecosystem, Kong serves as the critical entry point for API-driven applications at thousands of organizations worldwide.

This comprehensive guide covers Kong’s architecture, deployment options, plugin configuration, Kubernetes integration, and production best practices. Whether you’re building a new API platform or migrating from legacy solutions, this article provides the knowledge needed to implement Kong effectively.

What is Kong?

Kong is an open-source, cloud-native API gateway and service platform designed for managing, securing, and orchestrating API traffic. Built on top of Nginx with Lua scripting for extensibility, Kong provides a lightweight, high-performance platform for API management.

Core Capabilities

Traffic Management: Kong handles load balancing, circuit breaking, and traffic routing based on sophisticated rules.

Authentication and Security: Built-in support for API keys, OAuth 2.0, JWT, LDAP, and mTLS.

Transformations: Request and response transformation, including header manipulation, body modification, and protocol translation.

Rate Limiting: Flexible rate limiting with granular control per consumer, service, or route.

Analytics and Monitoring: Detailed request logging, metrics collection, and visualization.

Plugin Ecosystem: 50+ official plugins plus custom plugin support for extended functionality.

Architecture

Understanding Kong’s architecture is essential for effective deployment and scaling.

Deployment Models

Traditional Deployment: Kong runs as a standalone process, typically behind a load balancer, connecting to a database (PostgreSQL or Cassandra) for configuration storage.

DB-less Mode: Configuration stored in YAML files, eliminating database dependency for simpler deployments.

Kubernetes Deployment: Kong runs as a Kubernetes native application, often using the Kubernetes Ingress Controller for seamless integration.

Components

Kong Gateway: The core proxy that handles all API traffic, executes plugins, and manages upstream connections.

Kong Admin API: RESTful API for configuring Kong (should be secured and not exposed publicly).

Kong Manager: Web-based GUI for Kong administration.

Database: PostgreSQL (recommended) or Cassandra for storing routes, services, plugins, and consumer data.

Data Model

Service → Route → Plugin → Consumer
         ↑
    Upstream (Target)

Service: Represents an upstream API or microservice.

Route: Defines rules for matching incoming requests to services.

Plugin: Custom logic that executes on requests/responses.

Consumer: Represents a user or application consuming APIs.

Installation

Docker Installation

# Start PostgreSQL
docker run -d --name kong-database \
  -e "POSTGRES_USER=kong" \
  -e "POSTGRES_PASSWORD=kong" \
  -e "POSTGRES_DB=kong" \
  postgres:15

# Run migrations
docker run --rm \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=kong-database" \
  -e "KONG_PG_USER=kong" \
  -e "KONG_PG_PASSWORD=kong" \
  kong:3.4 kong migrations bootstrap

# Start Kong
docker run -d --name kong \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=kong-database" \
  -e "KONG_PG_USER=kong" \
  -e "KONG_PG_PASSWORD=kong" \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_LISTEN=0.0.0.0:80" \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 8001:8001 \
  -p 8444:8444 \
  kong:3.4

DB-less Mode

# Create declarative config
cat > kong.yml <<EOF
_format_version: "3.0"
services:
- name: my-service
  url: http://example.com
  routes:
  - name: my-route
    paths:
    - /api
plugins:
- name: rate-limiting
  config:
    minute: 100
    policy: local
EOF

# Run Kong in DB-less mode
docker run -d --name kong \
  -v $(pwd)/kong.yml:/usr/local/kong/declarative/kong.yml:ro \
  -e "KONG_DATABASE=off" \
  -e "KONG_DECLARATIVE_CONFIG=/usr/local/kong/declarative/kong.yml" \
  -p 8000:8000 \
  -p 8443:8443 \
  kong:3.4

Kubernetes Installation

# Add Kong Helm repository
helm repo add kong https://charts.konghq.com
helm repo update

# Install Kong with Ingress Controller
helm install kong kong/kong \
  --namespace kong \
  --create-namespace \
  --set ingressController.enabled=true \
  --set ingressController.installCRDs=false \
  --set admin.http.enabled=true \
  --set admin.http.listenPorts=[8001]

Configuration

Services and Routes

# Create a service
curl -X POST http://localhost:8001/services \
  -d name=my-api \
  -d url=http://backend-service:8080 \
  -d connect_timeout=60000 \
  -d read_timeout=60000 \
  -d write_timeout=60000

# Create a route
curl -X POST http://localhost:8001/services/my-api/routes \
  -d name=my-route \
  -d paths[]=/api \
  -d methods[]=GET \
  -d methods[]=POST \
  -d strip_path=true

Using Declarative Configuration

# kong.yaml
_format_version: "3.0"

services:
  - name: user-service
    url: http://user-service:8080
    routes:
      - name: user-route
        paths:
          - /users
        strip_path: true
    plugins:
      - name: rate-limiting
        config:
          minute: 100
          hour: 10000
          policy: redis
          redis_host: redis-master
          redis_port: 6379

  - name: payment-service
    url: http://payment-service:8080
    routes:
      - name: payment-route
        paths:
          - /payments
        strip_path: true
    plugins:
      - name: jwt
      - name: acl
        config:
          allow:
            - admin-group

Authentication and Security

API Key Authentication

# Create a consumer
curl -X POST http://localhost:8001/consumers \
  -d username=api-client

# Add API key credential
curl -X POST http://localhost:8001/consumers/api-client/key-auth \
  -d key=my-api-key-12345

# Enable plugin
curl -X POST http://localhost:8001/plugins \
  -d name=key-auth

JWT Authentication

# kong.yaml
plugins:
  - name: jwt
    config:
      uri_param_names:
        - jwt
      cookie_names: []
      header_names:
        - Authorization
      claims_to_verify:
        - exp
      maximum_expiration: 3600

OAuth 2.0

# Enable OAuth2 plugin
curl -X POST http://localhost:8001/plugins \
  -d name=oauth2 \
  -d config.scopes=read,write \
  -d config.enable_client_credentials=true \
  -d config.enable_password_grant=true \
  -d config.token_expiration=7200

# Create OAuth application
curl -X POST http://localhost:8001/consumers/oauth-client/oauth2 \
  -d name=my-app \
  -d client_id=my-client-id \
  -d client_secret=my-client-secret \
  -d redirect_uris[]=https://myapp.com/callback

mTLS Authentication

plugins:
  - name: mtls
    config:
     _ca_cert: /usr/local/kong/ssl/ca.pem
      cert: /usr/local/kong/ssl/kong.pem
      key: /usr/local/kong/ssl/kong.key
      verify: true
      vault: null

Rate Limiting

Basic Rate Limiting

plugins:
  - name: rate-limiting
    config:
      minute: 100
      hour: 10000
      policy: local
      hide_client_headers: false

Advanced Rate Limiting with Redis

plugins:
  - name: rate-limiting
    config:
      minute: 1000
      hour: 100000
      day: 1000000
      policy: redis
      redis_host: redis-cluster
      redis_port: 6379
      redis_password: ""
      redis_database: 0
      fault_tolerant: true
      hide_client_headers: false
      limit_by: consumer
      header_name: null

Custom Rate Limiting

-- custom-rate-limit.lua
local function access(conf)
  local key = kong.client.get_forwarded_ip()
  local limit = conf.limit
  local window = conf.window
  
  local current = tonumber(kong.cache:get(key, nil, function()
    return 0
  end))
  
  if current >= limit then
    return kong.response.exit(429, { message = "Rate limit exceeded" })
  end
  
  kong.cache:invalidate(key)
end

return {
  access = access
}

Transformations

Request Transformation

plugins:
  - name: request-transformer
    config:
      add:
        headers:
          - "X-Custom-Header:value"
        querystring:
          - "new_param:value"
        body:
          - "new_field:value"
      remove:
        headers:
          - "X-Remove-This"
        querystring:
          - "old_param"
      replace:
        uri: "/new/path"
        body:
          old_field: "new_value"

Response Transformation

plugins:
  - name: response-transformer
    config:
      add:
        headers:
          - "X-Kong-Upstream-Latency:$(latency.request)"
      remove:
        headers:
          - "X-Powered-By"
      replace:
        body:
          sensitive_data: "***REDACTED***"

Proxy Caching

plugins:
  - name: proxy-cache
    config:
      request_method:
        - GET
        - HEAD
      response_code:
        - 200
        - 301
        - 302
      content_type:
        - text/plain
        - application/json
      cache_ttl: 300
      strategy: memory
      memory:
        cache_percentage: 80

Kubernetes Integration

Kong Ingress Controller

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp-ingress
  annotations:
    konghq.com/strip-path: "true"
    kubernetes.io/ingress.class: kong
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: myapp-service
            port:
              number: 80

KongPlugin CRD

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limit-plugin
plugin: rate-limiting
config:
  minute: 100
  policy: redis
  redis_host: redis-master
---
apiVersion: v1
kind: Service
metadata:
  name: myapp-service
spec:
  selector:
    app: myapp
  ports:
  - port: 80
    targetPort: 8080
---
apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: myapp-kong-ingress
proxy:
  connect_timeout: 10000
  read_timeout: 10000
  write_timeout: 10000
  buffer_size: 16384
route:
  methods:
    - GET
    - POST
  strip_path: true

Service Mesh Integration

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mesh-app
  annotations:
    konghq.com/preserve-host: "true"
   konghq.com/plugins: "mesh-auth"
spec:
  rules:
  - host: mesh-app.example.com
    http:
      paths:
      - path: /
        backend:
          service:
            name: mesh-app
            port:
              number: 8080
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: mesh-auth
plugin: mtls
config:
  ca_cert: /etc/certs/ca.pem
  cert: /etc/certs/kong-client.pem
  key: /etc/certs/kong-client.key
  verify: true

Monitoring and Analytics

Prometheus Metrics

plugins:
  - name: prometheus
    config:
      per_consumer: true

Key metrics exposed:

kong_bandwidth_bytes: Total bandwidth in bytes
kong_latency_request: Request latency in milliseconds
kong_latency_upstream: Upstream latency in milliseconds
kong_requests_total: Total requests
kong_nginx_http_requests_total: Nginx HTTP requests
kong_nginx_connections_active: Active connections

Logging

plugins:
  - name: http-log
    config:
      http_endpoint: https://logging.example.com/kong
      method: POST
      content_type: application/json
      timeout: 5000
      flush_interval: 2
      retry_count: 10
      queue_size: 100

Performance Optimization

Connection Pooling

upstream my-service:
  name: my-service
  algorithm: round-robin
  healthchecks:
    passive:
      healthy:
        successes: 3
      unhealthy:
        http_failures: 3
        tcp_failures: 3
  slots: 10000
  hash_on: none

Worker Processes

# Environment variable
KONG_NGINX_WORKER_PROCESSES: "auto"

# Or in nginx.conf
worker_processes auto;
worker_rlimit_nofile 65536;

Database Optimization

-- PostgreSQL tuning
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
ALTER SYSTEM SET work_mem = '16MB';
ALTER SYSTEM SET maintenance_work_mem = '128MB';

Best Practices

Security

Never expose Admin API publicly
Enable TLS on all endpoints
Use OAuth 2.0 for third-party APIs
Implement mTLS for service-to-service
Regularly rotate API keys and secrets
Use Kong Vault for secrets management

Reliability

Deploy multiple Kong instances behind load balancer
Configure health checks for all upstreams
Use circuit breaker plugins
Implement proper timeouts
Enable request buffering for large payloads

Monitoring

Collect all Prometheus metrics
Set up alerts for error rates
Monitor upstream latency
Track API usage per consumer
Implement distributed tracing

Conclusion

Kong API Gateway provides a comprehensive solution for API management in modern cloud-native architectures. Its extensive plugin ecosystem, Kubernetes integration, and proven scalability make it the choice for organizations building API-first applications. By understanding Kong’s architecture and best practices outlined in this guide, teams can implement robust API management that secures, optimizes, and observes API traffic at scale.

Introduction

What is Kong?

Core Capabilities

Architecture

Deployment Models

Components

Data Model

Installation

Docker Installation

DB-less Mode

Kubernetes Installation

Configuration

Services and Routes

Using Declarative Configuration

Authentication and Security

API Key Authentication

JWT Authentication

OAuth 2.0

mTLS Authentication

Rate Limiting

Basic Rate Limiting

Advanced Rate Limiting with Redis

Custom Rate Limiting

Transformations

Request Transformation

Response Transformation

Proxy Caching

Kubernetes Integration

Kong Ingress Controller

KongPlugin CRD

Service Mesh Integration

Monitoring and Analytics

Prometheus Metrics

Logging

Performance Optimization

Connection Pooling

Worker Processes

Database Optimization

Best Practices

Security

Reliability

Monitoring

Conclusion

Resources

Comments

Share this article

👍 Was this article helpful?