# Kong API Gateway

> Enterprise API gateway with Kong, PostgreSQL, Konga admin UI, and Prometheus metrics.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: kong, konga, postgresql, prometheus
- Tags: kong, api-gateway, microservices, proxy, plugins
- Source: https://docker.recipes/devops/kong-gateway-stack

## Overview

Kong is a cloud-native API gateway built for high performance and extensibility, originally developed by Mashape (now Kong Inc.) in 2015. It serves as a traffic control layer for APIs and microservices, providing features like rate limiting, authentication, request transformation, and analytics through a robust plugin architecture. Kong's design philosophy centers around declarative configuration and horizontal scalability, making it a popular choice for organizations managing complex API ecosystems.

This deployment creates a complete Kong API gateway environment with five interconnected services: a PostgreSQL database (kong-database) for storing Kong's configuration, a one-time migration service (kong-migration) that initializes the database schema, the main Kong gateway service exposing both proxy and admin APIs, Konga as a web-based administration interface, and Prometheus for metrics collection and monitoring. The stack uses PostgreSQL 15 Alpine for lightweight database operations, while Kong exposes multiple ports for different functions - 8000/8443 for proxy traffic, 8001/8444 for admin API access, and 8100 for status monitoring.

This configuration is ideal for DevOps teams implementing API-first architectures, platform engineers building internal developer platforms, or organizations transitioning from monolithic to microservices architectures. The combination of Kong's powerful plugin ecosystem, Konga's intuitive management interface, and Prometheus monitoring creates a production-ready API management platform that can handle everything from simple request routing to complex authentication workflows and traffic shaping policies.

## Features

- Plugin-based architecture with 50+ official plugins for authentication, rate limiting, logging, and transformations
- Dual-mode operation supporting both proxy traffic (8000/8443) and administrative control (8001/8444)
- Declarative configuration management allowing GitOps workflows and infrastructure-as-code practices
- Konga web UI providing visual service mapping, plugin configuration, and real-time traffic monitoring
- PostgreSQL-backed persistence ensuring configuration consistency across Kong instance restarts and scaling
- Prometheus metrics endpoint exposing detailed API gateway performance and usage statistics
- Health check endpoints on Kong for automated container orchestration and load balancer integration
- gRPC and HTTP/2 support with SSL termination capabilities for modern API protocols

## Use cases

- Microservices API gateway providing single entry point for distributed service architectures
- Legacy system modernization by adding authentication, rate limiting, and monitoring to existing APIs
- Multi-tenant SaaS platforms requiring per-customer rate limiting, authentication, and usage tracking
- Internal developer platforms centralizing API discovery, documentation, and access control
- E-commerce platforms managing payment gateway routing, fraud detection, and transaction monitoring
- IoT device management requiring device authentication, telemetry data transformation, and routing
- Mobile backend services needing request/response transformation and offline-capable caching strategies

## Prerequisites

- Docker Engine 20.10+ with Docker Compose V2 for proper healthcheck and dependency management
- Minimum 2GB RAM allocation (512MB for Kong, 512MB for PostgreSQL, remainder for Konga and Prometheus)
- Ports 1337, 8000-8001, 8443-8444, 8100, and 9090 available on the host system
- Environment variables POSTGRES_USER and POSTGRES_PASSWORD configured for database access
- Basic understanding of API gateway concepts, HTTP proxy behavior, and RESTful API management
- Familiarity with Kong's Admin API or Konga UI for service and route configuration

## docker-compose.yml

```yaml
services:
  kong-database:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: kong
    volumes:
      - kong_db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - kong-net
    restart: unless-stopped

  kong-migration:
    image: kong:latest
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: ${POSTGRES_USER}
      KONG_PG_PASSWORD: ${POSTGRES_PASSWORD}
    depends_on:
      kong-database:
        condition: service_healthy
    networks:
      - kong-net
    deploy:
      restart_policy:
        condition: on-failure
        max_attempts: 3

  kong:
    image: kong:latest
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: ${POSTGRES_USER}
      KONG_PG_PASSWORD: ${POSTGRES_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, 0.0.0.0:8444 ssl
      KONG_STATUS_LISTEN: 0.0.0.0:8100
    ports:
      - "8000:8000"
      - "8443:8443"
      - "8001:8001"
      - "8444:8444"
    depends_on:
      kong-database:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 10s
      retries: 10
    networks:
      - kong-net
    restart: unless-stopped

  konga:
    image: pantsel/konga:latest
    environment:
      DB_ADAPTER: postgres
      DB_HOST: kong-database
      DB_USER: ${POSTGRES_USER}
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      DB_DATABASE: konga
      NODE_ENV: production
    ports:
      - "1337:1337"
    depends_on:
      - kong
    networks:
      - kong-net
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    networks:
      - kong-net
    restart: unless-stopped

volumes:
  kong_db_data:
  prometheus_data:

networks:
  kong-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=kong
POSTGRES_PASSWORD=secure_postgres_password
```

## Usage notes

- Kong Admin at http://localhost:8001
- Kong Proxy at http://localhost:8000
- Konga UI at http://localhost:1337
- Enable plugins via Admin API or Konga

## Troubleshooting

- Kong fails to start with 'database not ready': Verify kong-database container is healthy and accessible, check PostgreSQL credentials match between services
- 502 Bad Gateway on proxy requests: Ensure upstream services are reachable from kong container, verify service and route configuration in Admin API
- Konga cannot connect to Kong Admin API: Confirm Kong admin interface is accessible on port 8001, check kong service health status
- Plugin configuration not applying: Verify plugin is enabled on correct service/route scope, check Kong logs for plugin initialization errors
- Prometheus metrics not collecting: Enable Kong's Prometheus plugin via Admin API, ensure kong status endpoint on port 8100 is accessible
- Database migration failures: Check kong-migration service logs, ensure PostgreSQL accepts connections and has sufficient privileges for schema creation

