Kong API Gateway — Plugin-Based Gateway for Microservices

In this tutorial, you will learn about Kong API Gateway. We cover key concepts, practical examples, and best practices to help you master this topic.

Kong is an open-source API gateway built on Nginx and Lua, offering a plugin-based architecture for authentication, rate limiting, caching, logging, and traffic control without modifying backend services.

What You'll Learn

• Kong architecture: proxy, admin API, and database
• Configuring services, routes, and upstreams
• Installing and configuring plugins: key-auth, rate-limiting, proxy-cache

Why It Matters

Building a gateway from scratch is complex and error-prone. Kong provides battle-tested implementations for common gateway features as plugins, reducing development time from months to hours while maintaining production-grade performance.

Real-World Use

Durga Antivirus Pro uses Kong as its primary API gateway. A partner integration team can self-service configure a new API route with rate limiting and API key authentication through Kong's Admin API, without involving the infrastructure team.

flowchart LR
    Client["Client"] --> Kong["Kong\nProxy Port 8000"]
    Kong --> DB["PostgreSQL /\nCassandra"]
    Kong --> Service1["Service A"]
    Kong --> Service2["Service B"]
    Admin["Admin API\nPort 8001"] --> Kong
    style Kong fill:#dbeafe,stroke:#2563eb

Basic Kong Setup with Docker

version: "3.8"
services:
  kong-database:
    image: postgres:13
    environment:
      POSTGRES_DB: kong
      POSTGRES_USER: kong
      POSTGRES_PASSWORD: kong_pass

  kong:
    image: kong:3.5
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
    ports:
      - "8000:8000"
      - "8001:8001"
    depends_on:
      - kong-database

Start with docker-compose up -d and Kong is ready on port 8000 (proxy) and 8001 (admin).

Adding a Service and Route via Admin API

# Add a service
curl -s -X POST http://localhost:8001/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-service",
    "host": "user-srv.internal",
    "port": 8080,
    "protocol": "http"
  }'

# Add a route to the service
curl -s -X POST http://localhost:8001/services/user-service/routes \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/users"],
    "methods": ["GET", "POST"]
  }'

Now GET http://localhost:8000/users forwards to http://user-srv.internal:8080.

Enabling Plugins

Plugins add functionality to services or routes:

# Rate limiting plugin: 100 requests per minute
curl -s -X POST http://localhost:8001/services/user-service/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rate-limiting",
    "config": {
      "minute": 100,
      "policy": "local"
    }
  }'

# Key authentication plugin
curl -s -X POST http://localhost:8001/services/user-service/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "key-auth"
  }'

# Create a consumer with API key
curl -s -X POST http://localhost:8001/consumers \
  -H "Content-Type: application/json" \
  -d '{"username": "partner-1"}'

curl -s -X POST http://localhost:8001/consumers/partner-1/key-auth \
  -H "Content-Type: application/json" \
  -d '{"key": "sk-live-a1b2c3"}'

Now requests to /users require the header apikey: sk-live-a1b2c3 and are limited to 100 per minute.

Common Mistakes

1. Using the Default Admin API Port in Production

Kong's Admin API (8001) has no authentication by default. Change the port, bind to localhost, or enable RBAC in production.

2. Forgetting Database Migrations

Kong requires kong migrations bootstrap before first run and kong migrations up after upgrades. Skipping these causes startup failures.

3. Not Tuning Nginx Worker Settings

Kong's default worker count may not suit your hardware. Set KONG_NGINX_WORKER_PROCESSES to match CPU cores and tune worker_connections.

4. Overloading with Too Many Plugins

Each plugin adds processing time. 10+ plugins on every request can double latency. Use plugin ordering and route-specific plugin scoping.

5. Ignoring Upstream Health Checks

Without health checks, Kong routes traffic to dead upstreams. Configure active health checks on each upstream.

Practice Questions

1. What are the three main components of Kong's architecture?
2. How does Kong's plugin system benefit API gateway operations?
3. What is the purpose of Kong's Admin API?
4. Why should the Admin API be secured in production?
5. How do you configure rate limiting for a specific route in Kong?

Answers:

1. Proxy (handles traffic), Admin API (configuration), and Database (stores config — PostgreSQL or Cassandra).
2. Plugins add features without modifying backend code. New capabilities are enabled via API calls, not code changes.
3. The Admin API (port 8001) is used to configure services, routes, upstreams, and plugins dynamically without restarting Kong.
4. The Admin API has no default authentication. An attacker could reconfigure Kong to expose or block services.
5. POST a plugin configuration to the route's plugin endpoint with name: "rate-limiting" and the desired config.minute or config.hour.

Challenge: Set up Kong with three services, each with different plugins. User service: key-auth + rate-limiting (100/min). Order service: JWT auth only. Product service: public but cached (proxy-cache plugin, 5 min TTL).

FAQ

Mini Project

Set up Kong with Docker Compose. Configure two services (user-service and product-service) with routes. Add key-auth plugin to user-service and rate-limiting (200 req/min) to product-service. Create a consumer with an API key and verify both auth and rate limiting work.

What's Next

Continue with AWS API Gateway for a cloud-managed gateway, or explore Nginx as API Gateway for a lightweight alternative.