# Kong API Gateway

> Kong API Gateway with PostgreSQL and Konga admin dashboard for API management.

- Category: Web Servers & Reverse Proxies
- Difficulty: advanced
- Components: kong, konga, postgres
- Tags: kong, api-gateway, microservices, proxy, rate-limiting
- Source: https://docker.recipes/web-servers/kong-gateway-postgres

## Overview

Kong is an open-source, cloud-native API gateway built on top of NGINX that provides traffic control, security, analytics, and transformation capabilities for APIs and microservices. Originally developed by Mashape (now Kong Inc.) in 2015, Kong has become one of the most popular API gateways due to its plugin architecture, high performance, and extensive feature set for managing API traffic at scale.

This deployment creates a complete Kong API management platform using four interconnected services: a PostgreSQL database (kong-database) for storing Kong's configuration, a migration service (kong-migration) that initializes the database schema, the Kong gateway itself handling API traffic, and Konga providing a web-based administrative interface. The stack includes proper health checks and dependency management to ensure services start in the correct order, with Kong's database migrations completing before the gateway starts.

This configuration is ideal for organizations implementing microservices architectures, API-first development strategies, or those needing centralized API management with advanced features like rate limiting, authentication, and request transformation. The inclusion of Konga makes this particularly valuable for teams who prefer visual administration over command-line API management, while the PostgreSQL backend ensures Kong's configuration persists and can handle enterprise-scale API traffic.

## Features

- Plugin-based architecture with over 50 official plugins for authentication, security, traffic control, and analytics
- Declarative configuration support allowing GitOps-style API management through YAML files
- Advanced rate limiting with multiple algorithms including sliding window, fixed window, and leaky bucket
- Built-in support for multiple authentication methods including JWT, OAuth 2.0, LDAP, and API keys
- Request and response transformation capabilities with custom headers, body modification, and routing rules
- Konga web dashboard for visual API management, service discovery, and plugin configuration
- Real-time API analytics and logging with structured output for integration with monitoring systems
- Load balancing with health checks, circuit breakers, and automatic failover for upstream services

## Use cases

- Microservices API gateway for containerized applications requiring centralized traffic management
- Enterprise API management platform with role-based access control and audit trails
- E-commerce platforms needing rate limiting, API key management, and payment gateway integration
- SaaS applications requiring multi-tenant API access with quotas and billing integration
- Mobile backend services with JWT authentication, CORS handling, and request throttling
- Legacy system modernization using Kong as a facade for gradual API migration
- Development and staging environments where teams need visual API testing and configuration management

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for proper health check and dependency support
- Minimum 2GB RAM allocated to Docker (Kong requires 512MB, PostgreSQL 256MB, plus overhead)
- Available ports 8000 (Kong proxy), 8001 (Kong admin), 8443/8444 (HTTPS), and 1337 (Konga)
- Environment variables KONG_PG_PASSWORD and KONGA_TOKEN_SECRET configured in .env file
- Basic understanding of API gateway concepts, HTTP proxying, and PostgreSQL administration
- Familiarity with Kong's plugin system and REST API for advanced configuration management

## docker-compose.yml

```yaml
services:
  kong-database:
    image: postgres:16-alpine
    container_name: kong-database
    environment:
      - POSTGRES_USER=kong
      - POSTGRES_DB=kong
      - POSTGRES_PASSWORD=${KONG_PG_PASSWORD}
    volumes:
      - kong_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kong"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - kong-network

  kong-migration:
    image: kong:3.5
    command: kong migrations bootstrap
    environment:
      - KONG_DATABASE=postgres
      - KONG_PG_HOST=kong-database
      - KONG_PG_USER=kong
      - KONG_PG_PASSWORD=${KONG_PG_PASSWORD}
    depends_on:
      kong-database:
        condition: service_healthy
    networks:
      - kong-network

  kong:
    image: kong:3.5
    container_name: kong
    environment:
      - KONG_DATABASE=postgres
      - KONG_PG_HOST=kong-database
      - KONG_PG_USER=kong
      - 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-migration:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 10s
      retries: 10
    networks:
      - kong-network

  konga:
    image: pantsel/konga:latest
    container_name: konga
    environment:
      - NODE_ENV=production
      - TOKEN_SECRET=${KONGA_TOKEN_SECRET}
    ports:
      - "1337:1337"
    depends_on:
      - kong
    networks:
      - kong-network

volumes:
  kong_data:

networks:
  kong-network:
    driver: bridge
```

## .env

```bash
# Kong API Gateway
KONG_PG_PASSWORD=kong_secure_password
KONGA_TOKEN_SECRET=your-secret-token
```

## Usage notes

- Kong Admin API at http://localhost:8001
- Kong Proxy at http://localhost:8000
- Konga Dashboard at http://localhost:1337
- Connect Konga to http://kong:8001
- Supports plugins for auth, rate-limiting, etc.

## Troubleshooting

- kong-migration fails with connection refused: Ensure kong-database health check passes before migration runs, check KONG_PG_PASSWORD environment variable matches
- Kong admin API returns 404 errors: Verify KONG_ADMIN_LISTEN is set to 0.0.0.0:8001 and container port 8001 is properly exposed
- Konga cannot connect to Kong: Use connection URL http://kong:8001 (internal Docker network name), not localhost:8001
- Kong proxy returns 503 Service Temporarily Unavailable: No upstream services configured yet, add services and routes through Konga or Admin API
- Database migration hangs indefinitely: Check PostgreSQL logs for connection limits or disk space issues, restart kong-database service if needed
- Konga dashboard shows 'Invalid token' errors: Regenerate KONGA_TOKEN_SECRET environment variable and restart konga container

