Deploying Kong

Introduction

Kong is a cloud-native, platform-agnostic API gateway built for managing, securing, and scaling APIs and microservices. Originally built on top of NGINX and now available with optimized performance layers, Kong provides enterprise-grade features for routing, authentication, rate limiting, and observability.

As one of the most popular open source API gateways, Kong powers organizations ranging from startups to Fortune 500 companies. It can run in DB-less mode with declarative configuration or with a PostgreSQL database for dynamic configuration through its Admin API.

Key features of Kong:

• High Performance: Built on NGINX with LuaJIT, handling millions of requests per second
• Plugin Architecture: Extend functionality with 100+ plugins for auth, logging, rate limiting, and more
• DB-less Mode: Run with declarative YAML configuration without a database
• Multi-Protocol Support: HTTP, gRPC, GraphQL, WebSocket, and TCP/UDP proxying
• Load Balancing: Built-in load balancing with health checks and circuit breakers
• Service Discovery: Integration with Consul, DNS, and Kubernetes service discovery
• Rate Limiting: Protect your APIs from abuse with configurable rate limits
• Authentication: Support for OAuth 2.0, JWT, Basic Auth, API Keys, and more
• Observability: Built-in logging, metrics, and tracing integrations
• Developer Portal: Optional portal for API documentation and onboarding

This guide walks through deploying Kong on Klutch.sh using Docker, configuring it for production use, and setting up common plugins.

Why Deploy Kong on Klutch.sh

Deploying Kong on Klutch.sh provides several advantages for API management:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kong without complex orchestration. Push to GitHub, and your API gateway deploys automatically.

Persistent Storage: Attach persistent volumes for configuration and logs. Your gateway setup survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure connections to your API gateway.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your traffic needs. Scale horizontally as API usage grows.

Environment Variable Management: Securely store sensitive configuration like database credentials and API keys.

Custom Domains: Assign custom domains to your Kong instance for professional API endpoints.

Always-On Availability: Your API gateway remains accessible 24/7 with high availability.

Prerequisites

Before deploying Kong on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Kong configuration
• Basic familiarity with Docker and API gateway concepts
• Your upstream services ready to proxy
• (Optional) A PostgreSQL database for dynamic configuration

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and Kong configuration for Klutch.sh.

Repository Structure

kong-deploy/
├── Dockerfile
├── kong.yml
├── README.md
└── .dockerignore

Creating the Dockerfile (DB-less Mode)

Create a Dockerfile for declarative configuration mode:

FROM kong:latest

# Copy declarative configuration
COPY kong.yml /etc/kong/kong.yml

# Set environment variables
ENV KONG_DATABASE=off
ENV KONG_DECLARATIVE_CONFIG=/etc/kong/kong.yml
ENV KONG_PROXY_ACCESS_LOG=/dev/stdout
ENV KONG_ADMIN_ACCESS_LOG=/dev/stdout
ENV KONG_PROXY_ERROR_LOG=/dev/stderr
ENV KONG_ADMIN_ERROR_LOG=/dev/stderr
ENV KONG_ADMIN_LISTEN=0.0.0.0:8001
ENV KONG_PROXY_LISTEN=0.0.0.0:8000

# Expose ports
EXPOSE 8000 8001

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD kong health || exit 1

Creating the Declarative Configuration

Create kong.yml for your services and routes:

_format_version: "3.0"
_transform: true

services:
  - name: example-service
    url: https://httpbin.org
    routes:
      - name: example-route
        paths:
          - /api
        strip_path: true

plugins:
  - name: rate-limiting
    config:
      minute: 60
      policy: local
  - name: cors
    config:
      origins:
        - "*"
      methods:
        - GET
        - POST
        - PUT
        - DELETE
      headers:
        - Accept
        - Content-Type
        - Authorization

Environment Variables Reference

Variable	Required	Default	Description
KONG_DATABASE	No	postgres	Set to off for DB-less mode
KONG_DECLARATIVE_CONFIG	DB-less	-	Path to declarative config file
KONG_PG_HOST	DB mode	-	PostgreSQL host
KONG_PG_USER	DB mode	-	PostgreSQL username
KONG_PG_PASSWORD	DB mode	-	PostgreSQL password
KONG_PROXY_LISTEN	No	0.0.0.0:8000	Proxy listener address
KONG_ADMIN_LISTEN	No	127.0.0.1:8001	Admin API listener address

Deploying Kong on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile kong.yml .dockerignore README.md
git commit -m "Initial Kong deployment configuration"
git remote add origin https://github.com/yourusername/kong-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kong” or “api-gateway”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Kong Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8000 (Kong proxy port)

Set Environment Variables

For DB-less mode, the Dockerfile sets most variables. For database mode, add:

Variable	Value
KONG_DATABASE	postgres
KONG_PG_HOST	Your PostgreSQL host
KONG_PG_USER	Your database user
KONG_PG_PASSWORD	Your database password
KONG_PG_DATABASE	kong

Attach Persistent Volumes

For logging and custom plugins:

Mount Path	Recommended Size	Purpose
/usr/local/kong/logs	5 GB	Kong logs
/usr/local/share/lua/5.1/kong/plugins	1 GB	Custom plugins

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Start the Kong container
• Provision an HTTPS certificate

Access Kong

Once deployment completes, access your Kong proxy at https://your-app-name.klutch.sh.

Configuring Kong Plugins

Rate Limiting

Protect your APIs from abuse:

plugins:
  - name: rate-limiting
    config:
      minute: 100
      hour: 1000
      policy: local
      fault_tolerant: true

JWT Authentication

Secure your APIs with JWT tokens:

plugins:
  - name: jwt
    config:
      claims_to_verify:
        - exp

Key Authentication

Simple API key authentication:

plugins:
  - name: key-auth
    config:
      key_names:
        - apikey
        - x-api-key

Request Transformation

Modify requests before sending upstream:

plugins:
  - name: request-transformer
    config:
      add:
        headers:
          - "X-Custom-Header:value"

Troubleshooting Common Issues

Kong Won’t Start

• Validate your kong.yml syntax with kong config parse
• Check environment variables are set correctly
• Review startup logs for specific errors

Routes Not Matching

• Verify path configuration in declarative config
• Check that services are accessible from Kong
• Review proxy access logs for routing decisions

Performance Issues

• Increase memory allocation for high-traffic scenarios
• Enable caching plugins for frequently accessed endpoints
• Review and optimize plugin chain

Additional Resources

• Official Kong Website
• Kong Documentation
• Kong GitHub Repository
• Kong Plugin Development

Conclusion

Deploying Kong on Klutch.sh gives you a powerful, enterprise-grade API gateway with automatic builds, persistent storage, and secure HTTPS access. Whether you’re managing a few microservices or building a complex API platform, Kong on Klutch.sh provides the foundation for reliable, scalable API management.