Comprehensive Engineering Guide to Deploying and Managing Kong Gateway via Docker

Published by TechMarmot Editorail Staff on | Category Docker

The deployment of an API layer for managing microservices and APIs requires a foundation that is simultaneously lightweight, fast, and flexible. Kong Gateway emerges as the world's most adopted API gateway, designed specifically to address the complexities of hybrid and multi-cloud environments. By optimizing for distributed architectures and microservices, Kong provides a unified cloud API platform that scales from agile startups to Fortune 500 enterprises. The integration of Kong with Docker allows organizations to maximize developer productivity and accelerate time to market by abstracting the underlying infrastructure and providing a consistent environment for the gateway to operate.

At its core, Kong is built on an open-source DNA, ensuring that the gateway remains accessible and extensible. When deploying via Docker, it is important to recognize that the images provided by Kong Inc. may contain other software under various licenses, such as Bash or other dependencies from the base distribution. This modularity allows Kong to provide advanced routing, load balancing, and health checking—all of which are fully configurable to meet the specific needs of a production environment. Furthermore, the modern evolution of the gateway now includes Kong AI Gateway capabilities, integrating Large Language Model (LLM) and Model Context Protocol (MCP) features. By centralizing these AI and MCP functionalities, engineering teams are freed from the burden of redundant infrastructure and can focus on solving critical business challenges.

Architectural Deployment Modes and Technical Specifications

Kong Gateway offers two primary operational modes when deployed via Docker: a database-backed mode and a DB-less (read-only) mode. The choice between these two depends on the requirements for dynamic configuration and the specific plugins being utilized.

Database-Backed Mode

In this mode, Kong requires a running PostgreSQL instance (version 9.6 or higher) before the gateway can initialize. The database serves as the central repository for all configuration data, including routes, services, and consumer information.

  • Technical Requirement: A PostgreSQL database must be available and reachable.
  • Impact: This mode allows for dynamic configuration via the Admin API, meaning changes take effect immediately without requiring a restart of the container.
  • Context: This is the standard approach for environments requiring full plugin compatibility, such as those using the ACL or OAuth2 plugins, which necessitate central database coordination.

DB-less and Declarative Configuration Mode

For users who prefer a more immutable infrastructure approach, Kong can be run in read-only mode. This is achieved by setting the database configuration to "off" and passing a declarative configuration file.

  • Technical Requirement: The environment variable KONG_DATABASE must be set to off.
  • Impact: The gateway becomes lightweight and stateless, which is ideal for CI/CD pipelines where configurations are versioned in Git and deployed as files.
  • Context: Not all plugins are compatible with this mode; specifically, those requiring dynamic entity creation or central coordination cannot function without a database.

Docker Image Specifications

The official Kong images are maintained by Kong Inc. and are available on Docker Hub.

Attribute Specification
Official Image Path hub.docker.com/_/kong or kong/kong-gateway
Typical Image Size 104.4 MB
Docker Desktop Requirement Version 4.37.1 or later
Primary Function API Gateway for Microservices and AI

Implementing Kong Gateway via Docker Compose

Docker Compose is the recommended method for orchestrating the Kong Gateway and its associated database, as it simplifies the networking and volume management required for persistent data.

The Docker Compose Configuration

To deploy a full stack, a docker-compose.yml file must be created. This file defines the relationship between the gateway and the PostgreSQL database.

```yaml
volumes:
kongdbdata: {} # Named volume to persist Postgres data across container restarts

networks:
kong-ee-net: # Custom bridge network for isolated Kong and Postgres communication
driver: bridge

Common environment variables used by Kong services (bootstrap and CP)

x-kong-config: &kong-env
KONGDATABASE: postgres # Use Postgres as the backing database
KONGPGHOST: kong-ee-database # Hostname of the Postgres service
KONGPGDATABASE: kong # Name of the database to connect to
KONGPGUSER: kong # Database username
KONGPGPASSWORD: kong # Database password
KONGLICENSEDATA: "${KONGLICENSE_DATA}" # Kong Enterprise license passed via environment variable

services:
kong-ee-database:
containername: kong-ee-database
image: postgres:latest # Official Postgres image
restart: on-failure # Restart if the container fails
volumes:
- kongdbdata:/var/lib/postgresql # Mount the volume for persistent data
networks:
- kong-ee-net # Connect to the shared Kong network
environment:
POSTGRESUSER: kong # Set DB user
```

Deployment Execution Flow

To initiate the environment using the provided configuration, the following operational steps are required:

  1. Create the docker-compose.yml file using the cat command.
  2. Execute the deployment command:
    bash docker compose up -d

Alternatively, for those using the GitHub distribution, the process involves cloning the official repository:

bash git clone https://github.com/Kong/docker-kong cd docker-kong/compose/ KONG_DATABASE=postgres docker-compose --profile database up

Manual Container Orchestration and Port Mapping

For developers who prefer using the docker run command for testing or specific manual configurations, Kong provides a variety of environment variables to control the gateway behavior.

Database-Enabled Manual Start

When starting Kong with a database, the container must be linked to the database service, and the connection parameters must be explicitly passed.

bash docker run -d --name kong \ --link kong-database:kong-database \ -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, 0.0.0.0:8444 ssl" \ -p 8000:8000 \ -p 8443:8443 \ -p 8001:8001 \ -p 8444:8444 \ kong/kong-gateway

DB-Less Manual Start

In a scenario where no database is used, the configuration is shifted to a declarative file. The startup command changes to reflect the absence of a database:

bash docker run -d --name kong \ -e "KONG_DATABASE=off" \ -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, 0.0.0.0:8444 ssl" \ -p 8000:8000 \ -p 8443:8443 \ -p 8001:8001 \ -p 8444:8444 \ kong/kong-gateway

Port Allocation and Interface Management

The Kong Gateway utilizes specific ports for different types of traffic. Understanding these mappings is critical for network configuration and security.

  • Port 8000: Used for standard Proxy traffic.
  • Port 8443: Used for Proxy traffic over SSL.
  • Port 8001: Used for the Admin API (non-SSL).
  • Port 8444: Used for the Admin API (SSL).

It is a critical security requirement that the Admin API ports (8001 and 8444) must be secured when running on a public system. For local testing, exposing these ports on localhost is acceptable, but in production, they should be protected by firewalls or authentication layers.

Configuration Management and Advanced Operations

Kong allows for flexible configuration, where any property in the configuration file can be overridden using environment variables by prepending the KONG_ prefix.

Declarative Configuration Initialization

When running in DB-less mode, a skeleton configuration file is required to define the behavior of the gateway. This can be generated using the following commands:

  1. Initialize the skeleton file inside the container:
    bash docker exec -it kong/kong-gateway kong config init /home/kong/kong.yml
  2. Extract the configuration file to the host machine:
    bash docker exec -it kong/kong-gateway cat /home/kong/kong.yml >> kong.yml

Interaction with the Admin API

Once the gateway is running, the Admin API serves as the control plane for the system. This API can be used to configure the gateway or to load declarative configurations using tools like HTTPie. Additionally, the management Web UI, known as Kong Manager, is accessible on localhost:8002 when using specific distributions.

Analysis of Gateway Capabilities and Performance

The technical architecture of Kong, when deployed via Docker, enables a high-performance environment for API management. The use of a lightweight image (approximately 104.4 MB) ensures that the gateway can be spun up rapidly in a containerized environment, supporting the agility required for modern DevOps practices.

The ability to choose between PostgreSQL and DB-less mode provides a strategic advantage. The PostgreSQL integration ensures that the gateway can handle complex, stateful requirements such as advanced authentication and access control lists (ACL). Conversely, the DB-less mode transforms the gateway into a stateless component, which is essential for scaling in Kubernetes or other orchestrators where the "infrastructure as code" paradigm is paramount.

The integration of AI Gateway features represents a shift toward intelligent traffic management. By supporting LLM and MCP features, Kong allows developers to implement AI-driven logic at the edge, reducing the latency associated with routing AI requests to various backend providers. This centralization of AI functionality ensures that security, rate limiting, and observability are applied uniformly across all AI-enabled services.

Sources

  1. Kong Hub
  2. Kong Developer Documentation - Docker Install
  3. Docker Hub - Kong
  4. Kong Installation Video
  5. Kong GitHub Repository
  6. Kong Gateway Docker Guide

Related Posts