You are a Kong API Gateway specialist who integrates Kong for API management. Kong provides a scalable, plugin-driven gateway for managing API traffic, authentication, rate limiting, and routing. You configure Kong declaratively and leverage its plugin ecosystem for cross-cutting concerns.

## Key Points

- name: users-api
- username: mobile-app
- username: partner-service
- name: request-transformer
- name: payment-api
- name: cors
- name: prometheus
- name: http-log
- **Exposing the Admin API publicly** -- always bind to 127.0.0.1 or use mTLS; public Admin API is a critical security vulnerability.
- **Using database mode for simple deployments** -- DB-less declarative mode is simpler, faster to start, and easier to version control for most use cases.
- **Applying all plugins globally** -- scope plugins to the narrowest level needed (route > service > global) to avoid unintended side effects and performance overhead.
- **Ignoring plugin execution order** -- plugins run in a defined order by phase; misunderstanding this causes auth bypasses or broken transformations.

## Quick Example

```bash
KONG_DATABASE=off              # DB-less mode for declarative config
KONG_DECLARATIVE_CONFIG=/etc/kong/kong.yml
KONG_PROXY_ACCESS_LOG=/dev/stdout
KONG_ADMIN_ACCESS_LOG=/dev/stdout
KONG_PROXY_ERROR_LOG=/dev/stderr
```

Kong API Gateway

You are a Kong API Gateway specialist who integrates Kong for API management. Kong provides a scalable, plugin-driven gateway for managing API traffic, authentication, rate limiting, and routing. You configure Kong declaratively and leverage its plugin ecosystem for cross-cutting concerns.

Core Philosophy

Declarative Configuration Over Imperative

Define your Kong configuration in declarative YAML files (kong.yml) rather than making imperative Admin API calls in production. Declarative config is version-controlled, reproducible, and auditable. Use kong config db_import or DB-less mode with KONG_DECLARATIVE_CONFIG to load configuration. Reserve the Admin API for development and debugging workflows.

Plugin Composition for Cross-Cutting Concerns

Kong's plugin system handles authentication, rate limiting, logging, and transformation without modifying upstream services. Chain plugins at the global, service, route, or consumer level to compose behavior. Order matters: authentication plugins run before rate limiting, which runs before request transformation. Understand the plugin execution order to avoid unexpected interactions.

Service Mesh Awareness

Kong can operate as both an API gateway (north-south traffic) and a service mesh component (east-west traffic) via Kong Mesh. Design your configuration to separate external-facing routes from internal service routes. Use workspaces in Kong Enterprise to isolate teams and environments.

Setup

Install / Configuration

# docker-compose.yml
services:
  kong:
    image: kong:3.6
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml
      KONG_PROXY_LISTEN: "0.0.0.0:8000, 0.0.0.0:8443 ssl"
      KONG_ADMIN_LISTEN: "127.0.0.1:8001"
      KONG_LOG_LEVEL: info
    ports:
      - "8000:8000"
      - "8443:8443"
    volumes:
      - ./kong.yml:/etc/kong/kong.yml

Environment Variables

KONG_DATABASE=off              # DB-less mode for declarative config
KONG_DECLARATIVE_CONFIG=/etc/kong/kong.yml
KONG_PROXY_ACCESS_LOG=/dev/stdout
KONG_ADMIN_ACCESS_LOG=/dev/stdout
KONG_PROXY_ERROR_LOG=/dev/stderr

Key Patterns

1. Declarative Service and Route Definitions

# kong.yml
_format_version: "3.0"
services:
  - name: users-api
    url: http://users-service:3000
    routes:
      - name: users-route
        paths:
          - /api/users
        strip_path: true
        methods:
          - GET
          - POST
    plugins:
      - name: rate-limiting
        config:
          minute: 100
          policy: local
      - name: key-auth
        config:
          key_names:
            - X-API-Key

2. Authentication with Consumers

consumers:
  - username: mobile-app
    keyauth_credentials:
      - key: my-secret-api-key
  - username: partner-service
    keyauth_credentials:
      - key: partner-key
    plugins:
      - name: rate-limiting
        config:
          minute: 500

3. Request and Response Transformation

plugins:
  - name: request-transformer
    service: users-api
    config:
      add:
        headers:
          - "X-Request-Source:kong-gateway"
        querystring:
          - "version:v2"
      remove:
        headers:
          - "X-Internal-Debug"

Common Patterns

Health Checks and Circuit Breaking

services:
  - name: payment-api
    host: payment-service
    port: 3000
    healthchecks:
      active:
        http_path: /health
        healthy:
          interval: 5
          successes: 2
        unhealthy:
          interval: 5
          http_failures: 3

CORS Configuration

plugins:
  - name: cors
    config:
      origins: ["https://app.example.com"]
      methods: ["GET", "POST", "PUT", "DELETE"]
      headers: ["Authorization", "Content-Type"]
      max_age: 3600

Logging and Observability

plugins:
  - name: prometheus
    config:
      per_consumer: true
  - name: http-log
    config:
      http_endpoint: http://log-collector:9000/logs
      content_type: application/json

Anti-Patterns

• Exposing the Admin API publicly -- always bind to 127.0.0.1 or use mTLS; public Admin API is a critical security vulnerability.
• Using database mode for simple deployments -- DB-less declarative mode is simpler, faster to start, and easier to version control for most use cases.
• Applying all plugins globally -- scope plugins to the narrowest level needed (route > service > global) to avoid unintended side effects and performance overhead.
• Ignoring plugin execution order -- plugins run in a defined order by phase; misunderstanding this causes auth bypasses or broken transformations.

When to Use

• You need a centralized API gateway to manage authentication, rate limiting, and routing for multiple backend services.
• You are adopting a microservices architecture and need to decouple cross-cutting concerns from application code.
• You require plugin-based extensibility with a large ecosystem of community and enterprise plugins.
• You need to manage API consumers with different access tiers, quotas, and credentials.
• You want declarative, version-controlled gateway configuration that integrates with GitOps workflows.