# Kong API Gateway Enterprise Stack

> Full Kong Gateway with plugins, Konga admin UI, and PostgreSQL backend.

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

## Overview

Kong is a cloud-native API gateway built on OpenResty and designed to handle millions of API requests for modern architectures. Originally developed by Mashape (now Kong Inc.) in 2015, Kong has become one of the most widely adopted API gateways, offering traffic control, security, analytics, and transformation capabilities through its extensive plugin ecosystem. It serves as a central control point for API traffic, providing rate limiting, authentication, load balancing, and request/response transformation.

This enterprise-grade deployment creates a comprehensive API management platform with six specialized services: a PostgreSQL database (kong-database) for Kong's configuration storage, an initialization service (kong-migrations) to bootstrap the database schema, the main Kong gateway instance, Konga as a web-based administration interface, Prometheus for metrics collection, and Grafana for visualization and monitoring dashboards. The stack uses PostgreSQL as Kong's backing store instead of the simpler DB-less mode, enabling advanced features like clustering and plugin data persistence.

This configuration is ideal for organizations transitioning from monolithic architectures to microservices, platform teams building internal API platforms, and enterprises requiring sophisticated API governance with full observability. The combination of Kong's enterprise-class gateway capabilities with Konga's intuitive management interface and the Prometheus-Grafana monitoring stack provides everything needed to operate APIs at scale with proper visibility into performance and usage patterns.

## Features

- Plugin-based architecture with 50+ community and enterprise plugins for authentication, rate limiting, and transformations
- Konga web interface for visual API gateway management, service configuration, and plugin administration
- PostgreSQL-backed configuration enabling Kong clustering, plugin data persistence, and advanced routing rules
- Prometheus metrics collection with Kong-specific performance indicators and API usage statistics
- Grafana dashboards for real-time API gateway monitoring, traffic analysis, and SLA tracking
- Declarative configuration support for GitOps workflows and infrastructure-as-code deployments
- Multi-protocol support including HTTP/HTTPS, gRPC, WebSocket, and TCP stream proxying
- Database migration automation ensuring proper Kong schema initialization and upgrades

## Use cases

- Microservices API gateway providing unified entry point for distributed service architectures
- Enterprise API management platform with centralized authentication, rate limiting, and analytics
- Developer portal backend offering API discovery, documentation, and self-service onboarding
- Multi-tenant SaaS platforms requiring per-customer rate limiting, authentication, and usage tracking
- Legacy system modernization providing modern API interfaces over existing backend services
- Internal API platform for large organizations standardizing service-to-service communication
- E-commerce platforms managing high-volume API traffic with sophisticated caching and transformation needs

## Prerequisites

- Docker Engine 20.10+ and Docker Compose v2 with at least 4GB RAM available for the complete stack
- Available ports 8000, 8001, 8002, 8443, 8444 for Kong services, plus 1337 for Konga, 9090 for Prometheus, and 3000 for Grafana
- Understanding of API gateway concepts, HTTP routing, and basic Kong plugin configuration
- Prometheus configuration file (prometheus.yml) in the project directory for metrics collection setup
- Environment variables KONG_PG_PASSWORD and GRAFANA_PASSWORD configured for database and admin access
- Basic knowledge of PostgreSQL administration for backup, maintenance, and performance tuning

## docker-compose.yml

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

  kong-migrations:
    image: kong:latest
    command: kong migrations bootstrap
    depends_on:
      kong-database:
        condition: service_healthy
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: ${KONG_PG_PASSWORD}
    networks:
      - kong_net
    restart: on-failure

  kong:
    image: kong:latest
    depends_on:
      kong-database:
        condition: service_healthy
      kong-migrations:
        condition: service_completed_successfully
    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
      KONG_ADMIN_GUI_URL: http://localhost:8002
    ports:
      - "8000:8000"
      - "8443:8443"
      - "8001:8001"
      - "8002:8002"
      - "8444:8444"
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 10s
      retries: 10
    networks:
      - kong_net

  konga:
    image: pantsel/konga:latest
    depends_on:
      kong:
        condition: service_healthy
    environment:
      DB_ADAPTER: postgres
      DB_HOST: kong-database
      DB_USER: kong
      DB_PASSWORD: ${KONG_PG_PASSWORD}
      DB_DATABASE: konga
      NODE_ENV: production
    ports:
      - "1337:1337"
    networks:
      - kong_net

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    networks:
      - kong_net

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - kong_net

volumes:
  kong_db:
  prometheus_data:
  grafana_data:

networks:
  kong_net:
```

## .env

```bash
# Kong Gateway
KONG_PG_PASSWORD=secure_kong_password
GRAFANA_PASSWORD=secure_grafana_password

# Proxy at http://localhost:8000
# Admin API at http://localhost:8001
# Konga at http://localhost:1337
```

## Usage notes

- Proxy at http://localhost:8000
- Admin API at http://localhost:8001
- Konga UI at http://localhost:1337
- SSL proxy at https://localhost:8443
- Configure routes and plugins via Admin API

## Troubleshooting

- Kong container fails with 'database not ready': Ensure kong-database health check passes before Kong starts, check PostgreSQL logs for connection issues
- Konga shows 'Connection to Kong failed': Verify Kong admin API is accessible on port 8001 and kong service is healthy
- kong-migrations service exits with schema errors: Clean kong_db volume and restart to reinitialize database with proper Kong schema
- Prometheus shows no Kong metrics: Configure Kong Prometheus plugin and ensure metrics endpoint is enabled in Kong configuration
- 502 Bad Gateway on proxy port 8000: Check that upstream services are configured correctly in Kong and target backends are reachable
- Grafana dashboards show no data: Verify Prometheus data source configuration and ensure Kong metrics are being scraped successfully

