Kong

Kong is a lightweight, fast, and flexible API Gateway and service mesh platform built on Nginx.

Installation

Docker

# With PostgreSQL database
docker network create kong-net

docker run -d \
  --name kong-database \
  --network kong-net \
  -e POSTGRES_USER=kong \
  -e POSTGRES_PASSWORD=kong \
  -e POSTGRES_DB=kong \
  postgres:13

# Run Kong migrations
docker run --rm \
  --network kong-net \
  -e KONG_DATABASE=postgres \
  -e KONG_PG_HOST=kong-database \
  -e KONG_PG_PASSWORD=kong \
  kong:3.3 kong migrations bootstrap

# Start Kong
docker run -d \
  --name kong \
  --network kong-net \
  -e KONG_DATABASE=postgres \
  -e KONG_PG_HOST=kong-database \
  -e KONG_PG_PASSWORD=kong \
  -e KONG_PROXY_ACCESS_LOG=/dev/stdout \
  -e KONG_ADMIN_ACCESS_LOG=/dev/stdout \
  -e KONG_PROXY_ERROR_LOG=/dev/stderr \
  -e KONG_ADMIN_ERROR_LOG=/dev/stderr \
  -e KONG_ADMIN_LISTEN=0.0.0.0:8001 \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 8001:8001 \
  -p 8444:8444 \
  kong:3.3

# Kong Admin API on http://localhost:8001
# Kong Proxy on http://localhost:8000

Docker Compose

version: '3'
services:
  postgres:
    image: postgres:13
    environment:
      POSTGRES_USER: kong
      POSTGRES_PASSWORD: kong
      POSTGRES_DB: kong
    volumes:
      - kong_data:/var/lib/postgresql/data

  kong-migrations:
    image: kong:3.3
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: postgres
      KONG_PG_PASSWORD: kong
    depends_on:
      - postgres

  kong:
    image: kong:3.3
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: postgres
      KONG_PG_PASSWORD: kong
      KONG_ADMIN_LISTEN: 0.0.0.0:8001
    ports:
      - "8000:8000"  # Proxy
      - "8443:8443"  # Proxy SSL
      - "8001:8001"  # Admin API
      - "8444:8444"  # Admin API SSL
    depends_on:
      - kong-migrations

  konga:
    image: pantsel/konga:latest
    environment:
      NODE_ENV: production
      DB_ADAPTER: postgres
      DB_HOST: postgres
      DB_USER: kong
      DB_PASSWORD: kong
      DB_DATABASE: konga
    ports:
      - "1337:1337"
    depends_on:
      - postgres

volumes:
  kong_data:

Linux Package

# Ubuntu/Debian
curl https://repos.konghq.com/apt/pubkey.gpg | sudo apt-key add -
echo "deb https://repos.konghq.com/apt/ubuntu $(lsb_release -sc) main" | \
  sudo tee /etc/apt/sources.list.d/kong.list

sudo apt update
sudo apt install kong

# Start Kong
sudo /usr/local/bin/kong start

Core Concepts

Services and Routes

# Create upstream service
curl -X POST http://localhost:8001/services \
  -d "name=my-api" \
  -d "url=http://backend-api:3000"

# Create route pointing to service
curl -X POST http://localhost:8001/services/my-api/routes \
  -d "paths[]=/api" \
  -d "methods[]=GET" \
  -d "methods[]=POST"

# Test the route
curl http://localhost:8000/api

Service with Multiple Routes

# Create service
curl -X POST http://localhost:8001/services \
  -d "name=user-service" \
  -d "host=user-api.internal" \
  -d "port=8080" \
  -d "protocol=http"

# Multiple routes to same service
curl -X POST http://localhost:8001/services/user-service/routes \
  -d "paths[]=/users"

curl -X POST http://localhost:8001/services/user-service/routes \
  -d "paths[]=/v2/users" \
  -d "strip_path=false"

curl -X POST http://localhost:8001/services/user-service/routes \
  -d "hosts[]=api.example.com" \
  -d "paths[]=/api/users"

Plugin Management

Authentication Plugins

# Add basic auth to service
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=basic-auth" \
  -d "config.hide_credentials=true"

# Add API key authentication
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=key-auth" \
  -d "config.key_names[]=apikey" \
  -d "config.key_in_header=true"

# Create consumer
curl -X POST http://localhost:8001/consumers \
  -d "username=john_doe" \
  -d "custom_id=user123"

# Add API key to consumer
curl -X POST http://localhost:8001/consumers/john_doe/key-auth \
  -d "key=my-api-key-12345"

Rate Limiting

# Global rate limiting
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=rate-limiting" \
  -d "config.second=10" \
  -d "config.minute=100" \
  -d "config.hour=10000"

# Per consumer rate limiting
curl -X POST http://localhost:8001/plugins \
  -d "name=rate-limiting" \
  -d "config.second=20" \
  -d "config.minute=200" \
  -d "config.limit_by=consumer"

CORS Plugin

# Enable CORS
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=cors" \
  -d "config.origins[]=https://example.com" \
  -d "config.methods[]=GET" \
  -d "config.methods[]=POST" \
  -d "config.allow_headers[]=Content-Type" \
  -d "config.expose_headers[]=X-Total-Count"

Request/Response Transformation

# Add request header
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=request-transformer" \
  -d "config.add.headers[]=X-Forwarded-By=kong" \
  -d "config.add.headers[]=X-Service-Name=my-api"

# Modify response
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=response-transformer" \
  -d "config.add.headers[]=X-Response-Time=123ms"

Logging Plugins

# HTTP log plugin
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=http-log" \
  -d "config.http_endpoint=http://logging-service:8080/logs" \
  -d "config.method=POST"

# Syslog plugin
curl -X POST http://localhost:8001/services/my-api/plugins \
  -d "name=syslog" \
  -d "config.log_level=info" \
  -d "config.facility=local0"

Upstream Load Balancing

Create Upstream with Targets

# Create upstream
curl -X POST http://localhost:8001/upstreams \
  -d "name=backend-pool" \
  -d "algorithm=least-connections"

# Add targets (backend servers)
curl -X POST http://localhost:8001/upstreams/backend-pool/targets \
  -d "target=backend-1:8080" \
  -d "weight=100"

curl -X POST http://localhost:8001/upstreams/backend-pool/targets \
  -d "target=backend-2:8080" \
  -d "weight=100"

# Create service using upstream
curl -X POST http://localhost:8001/services \
  -d "name=load-balanced-api" \
  -d "host=backend-pool" \
  -d "port=8080" \
  -d "protocol=http"

# Create route
curl -X POST http://localhost:8001/services/load-balanced-api/routes \
  -d "paths[]=/api"

Health Checks

# Create upstream with health checks
curl -X POST http://localhost:8001/upstreams \
  -d "name=healthy-pool" \
  -d "algorithm=round-robin" \
  -d "healthchecks.active.type=http" \
  -d "healthchecks.active.http_path=/health" \
  -d "healthchecks.active.interval=10" \
  -d "healthchecks.active.healthy.interval=10" \
  -d "healthchecks.active.healthy.successes=2" \
  -d "healthchecks.active.unhealthy.interval=10" \
  -d "healthchecks.active.unhealthy.http_failures=3"

Admin API

Service Management

# List services
curl http://localhost:8001/services

# Get service details
curl http://localhost:8001/services/my-api

# Update service
curl -X PATCH http://localhost:8001/services/my-api \
  -d "retries=3" \
  -d "connect_timeout=6000"

# Delete service
curl -X DELETE http://localhost:8001/services/my-api

Route Management

# List routes
curl http://localhost:8001/routes

# List routes for service
curl http://localhost:8001/services/my-api/routes

# Get route details
curl http://localhost:8001/routes/route-id

# Update route
curl -X PATCH http://localhost:8001/routes/route-id \
  -d "strip_path=true" \
  -d "preserve_host=false"

Consumer Management

# List consumers
curl http://localhost:8001/consumers

# Create consumer
curl -X POST http://localhost:8001/consumers \
  -d "username=alice" \
  -d "custom_id=cust_123"

# Get consumer
curl http://localhost:8001/consumers/alice

# Delete consumer
curl -X DELETE http://localhost:8001/consumers/alice

Declarative Configuration

Kong Configuration File

# kong.yml
_format_version: "3.0"
_transform: true

services:
  - name: my-api
    url: http://backend-api:3000
    routes:
      - name: api-route
        paths:
          - /api
    plugins:
      - name: rate-limiting
        config:
          minute: 100

  - name: user-service
    host: user-api
    port: 8080
    routes:
      - name: users
        paths:
          - /users
      - name: user-detail
        paths:
          - /users/:id
    plugins:
      - name: cors
        config:
          origins:
            - https://example.com

consumers:
  - username: john_doe
    custom_id: user123
    key_auths:
      - key: sk_12345

upstreams:
  - name: backend-pool
    algorithm: least-connections
    targets:
      - target: backend-1:8080
        weight: 100
      - target: backend-2:8080
        weight: 100

Deploy Configuration

# Apply declarative config
curl -X POST http://localhost:8001/config \
  -H "Content-Type: application/yaml" \
  -d @kong.yml

# Get current config
curl http://localhost:8001/config

# Validate configuration
kong config parse kong.yml

Troubleshooting

Debug Requests

# Enable debug logging
export KONG_LOG_LEVEL=debug
kong start

# Check Kong status
curl http://localhost:8001/status

# View Kong logs
tail -f /usr/local/kong/logs/error.log

Common Issues

# Service returns 404
# Check if route exists
curl http://localhost:8001/services/my-api/routes

# Check if upstream is healthy
curl http://localhost:8001/upstreams/backend-pool/health

# Verify plugin configuration
curl http://localhost:8001/services/my-api/plugins

Best Practices

• Use declarative configuration for infrastructure as code
• Implement authentication on sensitive endpoints
• Configure rate limiting based on usage patterns
• Monitor upstream health and set appropriate thresholds
• Use meaningful service and route naming conventions
• Implement comprehensive logging for audit trails
• Set up alerts for high error rates or latency
• Regularly update Kong and plugins for security patches
• Test plugin configurations in staging before production
• Document custom plugin configurations and usage

Resources

• Kong Official Documentation
• Kong Admin API Reference
• Kong Plugin Hub
• GitHub Repository

---

Last updated: 2025-03-30