Kong API Gateway

intermediate

Cloud-native API gateway built on NGINX with plugins ecosystem.

Overview

Kong API Gateway is a cloud-native, high-performance API gateway built on NGINX that serves as the control layer for API traffic management. Originally developed by Kong Inc. and now widely adopted in enterprise environments, Kong provides a plugin-based architecture that enables comprehensive API management including authentication, rate limiting, analytics, and request transformation. This deployment creates a complete Kong environment with three services: a PostgreSQL database (kong-database) for storing Kong's configuration and metadata, a one-time migration service (kong-migration) that initializes the database schema, and the main Kong gateway service that handles all API traffic and administrative functions. The setup provides both proxy endpoints for client traffic and admin APIs for configuration management, making it suitable for production API gateway scenarios. This configuration is ideal for organizations implementing microservices architectures, API-first development strategies, or needing centralized API management with enterprise-grade features. The PostgreSQL backend ensures Kong's configuration is persistent and allows for advanced features like clustering and high availability, while the declarative configuration approach enables infrastructure-as-code practices for API management.

Key Features

Plugin-based architecture with 50+ official plugins for authentication, security, traffic control, and analytics
Declarative configuration supporting both database and DB-less modes for GitOps workflows
Advanced rate limiting with Redis clustering support and multiple algorithms (sliding window, fixed window)
Multi-protocol support including HTTP/HTTPS, gRPC, GraphQL, and WebSocket proxying
Service mesh integration with native Kubernetes ingress controller capabilities
Real-time analytics and monitoring with Prometheus metrics and custom logging plugins
JWT, OAuth 2.0, LDAP, and custom authentication mechanisms with fine-grained access control
Request/response transformation including header manipulation, body transformation, and CORS handling

Common Use Cases

1Enterprise API management for microservices architectures with centralized authentication and rate limiting
2Multi-tenant SaaS platforms requiring per-customer API quotas and usage analytics
3Legacy system modernization with API versioning and gradual migration strategies
4Developer portal backends with API key management and usage tracking
5Kubernetes-native API gateway with service discovery and load balancing
6API security enforcement with WAF capabilities and threat detection
7GraphQL federation gateway combining multiple GraphQL services into unified APIs

Prerequisites

Minimum 1GB RAM for Kong service and 512MB for PostgreSQL database
Ports 8000 (HTTP proxy), 8001 (Admin API), 8443 (HTTPS proxy), 8444 (HTTPS Admin) available
Environment variable KONG_PG_PASSWORD configured for database authentication
Understanding of RESTful API concepts and HTTP routing for service configuration
Familiarity with PostgreSQL for database maintenance and backup procedures
Knowledge of plugin ecosystem and YAML/JSON for declarative configurations

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  kong-database: 
3    image: postgres:15-alpine
4    container_name: kong-database
5    restart: unless-stopped
6    environment: 
7      POSTGRES_USER: kong
8      POSTGRES_PASSWORD: ${KONG_PG_PASSWORD}
9      POSTGRES_DB: kong
10    volumes: 
11      - kong_data:/var/lib/postgresql/data
12    networks: 
13      - kong-network
14
15  kong-migration: 
16    image: kong:latest
17    command: kong migrations bootstrap
18    environment: 
19      KONG_DATABASE: postgres
20      KONG_PG_HOST: kong-database
21      KONG_PG_PASSWORD: ${KONG_PG_PASSWORD}
22    depends_on: 
23      - kong-database
24    networks: 
25      - kong-network
26
27  kong: 
28    image: kong:latest
29    container_name: kong
30    restart: unless-stopped
31    environment: 
32      KONG_DATABASE: postgres
33      KONG_PG_HOST: kong-database
34      KONG_PG_PASSWORD: ${KONG_PG_PASSWORD}
35      KONG_PROXY_ACCESS_LOG: /dev/stdout
36      KONG_ADMIN_ACCESS_LOG: /dev/stdout
37      KONG_PROXY_ERROR_LOG: /dev/stderr
38      KONG_ADMIN_ERROR_LOG: /dev/stderr
39      KONG_ADMIN_LISTEN: 0.0.0.0:8001
40    ports: 
41      - "8000:8000"
42      - "8443:8443"
43      - "8001:8001"
44      - "8444:8444"
45    depends_on: 
46      - kong-database
47      - kong-migration
48    networks: 
49      - kong-network
50
51volumes: 
52  kong_data: 
53
54networks: 
55  kong-network: 
56    driver: bridge

.env Template

.env

1KONG_PG_PASSWORD=changeme

Usage Notes

1Docs: https://docs.konghq.com/gateway/latest/
2Admin API at http://localhost:8001 - manage routes, services, plugins
3Proxy ports: 8000 (HTTP), 8443 (HTTPS) - client traffic here
4Add service: curl -X POST http://localhost:8001/services --data name=myapp --data url=http://backend:80
5Add route: curl -X POST http://localhost:8001/services/myapp/routes --data paths[]=/api
6Install Konga or Kong Manager for web UI management

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

kong-database

kong-database:
  image: postgres:15-alpine
  container_name: kong-database
  restart: unless-stopped
  environment:
    POSTGRES_USER: kong
    POSTGRES_PASSWORD: ${KONG_PG_PASSWORD}
    POSTGRES_DB: kong
  volumes:
    - kong_data:/var/lib/postgresql/data
  networks:
    - kong-network

kong-migration

kong-migration:
  image: kong:latest
  command: kong migrations bootstrap
  environment:
    KONG_DATABASE: postgres
    KONG_PG_HOST: kong-database
    KONG_PG_PASSWORD: ${KONG_PG_PASSWORD}
  depends_on:
    - kong-database
  networks:
    - kong-network

kong

kong:
  image: kong:latest
  container_name: kong
  restart: unless-stopped
  environment:
    KONG_DATABASE: postgres
    KONG_PG_HOST: kong-database
    KONG_PG_PASSWORD: ${KONG_PG_PASSWORD}
    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
  ports:
    - "8000:8000"
    - "8443:8443"
    - "8001:8001"
    - "8444:8444"
  depends_on:
    - kong-database
    - kong-migration
  networks:
    - kong-network

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  kong-database:
5    image: postgres:15-alpine
6    container_name: kong-database
7    restart: unless-stopped
8    environment:
9      POSTGRES_USER: kong
10      POSTGRES_PASSWORD: ${KONG_PG_PASSWORD}
11      POSTGRES_DB: kong
12    volumes:
13      - kong_data:/var/lib/postgresql/data
14    networks:
15      - kong-network
16
17  kong-migration:
18    image: kong:latest
19    command: kong migrations bootstrap
20    environment:
21      KONG_DATABASE: postgres
22      KONG_PG_HOST: kong-database
23      KONG_PG_PASSWORD: ${KONG_PG_PASSWORD}
24    depends_on:
25      - kong-database
26    networks:
27      - kong-network
28
29  kong:
30    image: kong:latest
31    container_name: kong
32    restart: unless-stopped
33    environment:
34      KONG_DATABASE: postgres
35      KONG_PG_HOST: kong-database
36      KONG_PG_PASSWORD: ${KONG_PG_PASSWORD}
37      KONG_PROXY_ACCESS_LOG: /dev/stdout
38      KONG_ADMIN_ACCESS_LOG: /dev/stdout
39      KONG_PROXY_ERROR_LOG: /dev/stderr
40      KONG_ADMIN_ERROR_LOG: /dev/stderr
41      KONG_ADMIN_LISTEN: 0.0.0.0:8001
42    ports:
43      - "8000:8000"
44      - "8443:8443"
45      - "8001:8001"
46      - "8444:8444"
47    depends_on:
48      - kong-database
49      - kong-migration
50    networks:
51      - kong-network
52
53volumes:
54  kong_data:
55
56networks:
57  kong-network:
58    driver: bridge
59EOF
60
61# 2. Create the .env file
62cat > .env << 'EOF'
63KONG_PG_PASSWORD=changeme
64EOF
65
66# 3. Start the services
67docker compose up -d
68
69# 4. View logs
70docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/kong-gateway/run | bash

Troubleshooting

kong-migration service fails with connection refused: Ensure kong-database container is fully started and accepting connections before migration runs
Admin API returns 404 on localhost:8001: Verify KONG_ADMIN_LISTEN environment variable is set to 0.0.0.0:8001 and port mapping is correct
Kong service shows 'database not ready' errors: Check PostgreSQL logs in kong-database container and ensure KONG_PG_PASSWORD matches POSTGRES_PASSWORD
Proxy returns 404 for configured routes: Verify services and routes are properly created via Admin API and check Kong's error logs for routing issues
High memory usage in kong container: Monitor plugin usage and consider disabling unused plugins or increasing memory limits for heavy traffic loads
PostgreSQL connection pool exhausted: Tune KONG_PG_MAX_CONCURRENT_QUERIES and PostgreSQL max_connections settings for high-throughput scenarios

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

kongpostgresql

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download