Why is Kong eating all my CPU during startup?

Kong compiles Lua code on startup, which is CPU-intensive. On container deployments, increase CPU limits during startup or use init containers to warm up the cache. The CPU usage drops to normal levels after ~30 seconds.Also check your plugin configuration - some plugins (like Prometheus) scan all routes on startup. If you have 1000+ routes, this takes forever.

Can Kong handle WebSocket connections without falling over?

Yes, but there are gotchas. WebSocket connections bypass most plugins (rate limiting, auth, etc.) once upgraded. You need to authenticate WebSocket connections at the HTTP upgrade stage, not after.Set `upstream_keepalive` to handle connection pooling properly. Default settings will create new upstream connections for every WebSocket, which exhausts connection pools fast.

How do I debug "no route matched" errors that make no sense?

Kong route matching is strict about path prefixes. `/api/v1/users` doesn't match `/api/v1/users/` (trailing slash). Use regex patterns or wildcard paths to handle both.Check route priority if multiple routes could match. Kong processes routes by creation order, not specificity. Create more specific routes first.Most importantly: enable request debugging in logs temporarily to see exactly what Kong is matching against.

Why does Kong's admin API return 404 for endpoints that definitely exist?

Two common causes:1. **Wrong admin port**: Admin API runs on 8001 by default, proxy on 8000. Don't confuse them.2. **Hybrid mode confusion**: In hybrid deployments, admin API only works on control plane nodes. Data plane nodes reject admin API calls with 404.If running in Kubernetes, make sure you're hitting the right service. The admin API service is usually separate from the proxy service.

Kong keeps restarting in Docker - what's broken?

Check PostgreSQL connectivity first. Kong fails hard if it can't reach the database. Common issues:- Wrong database host (use service names in Docker Compose)- Database not ready when Kong starts (use depends_on with health checks)- Network policies blocking database accessUse `kong health` command in a debug container to test connectivity before troubleshooting Kong configuration.

How do I migrate from version X to Y without breaking everything?

Kong provides migration commands but they're not magic. Steps that actually work:1. **Backup database first**: `pg_dump` for PostgreSQL, `nodetool snapshot` for Cassandra2. **Test migration on staging**: Run `kong migrations up` on a database copy3. **Read release notes**: Breaking changes are documented (usually)4. **Plan rollback**: Kong migrations aren't always reversibleFor zero-downtime upgrades, use blue-green deployment with separate Kong instances. Migrate one environment, test, then cut over traffic.

Rate limiting isn't working - requests are getting through

Kong rate limiting is eventually consistent with PostgreSQL backend. Rapid bursts can exceed limits before the counter updates. Use Redis for strict rate limiting or accept that bursts happen.Also check rate limiting scope - `global`, `consumer`, `service`, or `route`. Wrong scope means rate limiting applies differently than expected.For APIs with unpredictable traffic, combine Kong rate limiting with upstream circuit breakers.

Can I run Kong without a database (DB-less mode)?

Yes, for simple use cases. DB-less mode uses declarative YAML configuration instead of database storage. Limitations:- No rate limiting plugins (need persistent storage)- No OAuth plugins (need to store tokens)- Configuration reloads require restart- No admin API writes (read-only)Perfect for microservices where each service has its own Kong instance. Terrible for shared API gateways serving multiple teams.

Kong is using way too much memory - how do I fix it?

Kong memory usage scales with:- Number of active connections- Plugin complexity (especially Lua plugins)- Route/service count- Upstream connection poolsQuick fixes:- Reduce `worker_connections` (default 1024 per worker)- Lower `upstream_keepalive` pool sizes- Disable unnecessary plugins- Use connection limits on upstream servicesIf running in Kubernetes, set memory requests/limits based on actual usage patterns, not guesswork.

How do I handle SSL/TLS certificates without pulling my hair out?

Kong supports multiple certificate sources:- **File-based**: Mount certificates as volumes- **Database**: Store certificates in PostgreSQL (not recommended)- **Let's Encrypt**: Use ACME plugin for automatic certificates- **External**: Terminate SSL at load balancer levelFor production, use Let's Encrypt ACME plugin or external certificate management. Don't store certificates in the database - backup/restore becomes a nightmare.

Kong returns 502 errors randomly - what's happening?

502 errors mean upstream connection failures. Common causes:1. **Upstream timeouts**: Default 60s might be too short for slow APIs2. **Connection pool exhaustion**: Too many concurrent requests, not enough upstream connections3. **Network issues**: DNS resolution, routing problems, firewall rules4. **Upstream health**: Backend services failing but Kong doesn't knowEnable upstream health checks to detect failing backends automatically. Set appropriate timeout values for your upstream APIs - don't use defaults blindly.

Is Kong Enterprise worth the money?

Depends on your team and use case. Kong Enterprise adds:- Commercial support (actually helpful)- Advanced plugins (RBAC, OIDC, GraphQL)- Kong Manager UI (beats API-only configuration)- 24/7 support (saves you from 3am debugging)If you're running Kong in production with multiple teams, the support alone justifies the cost. If you're a startup with one API, stick with open source until you need enterprise features.The real question: can your team manage Kong operations without vendor support? If no, buy Enterprise. If yes, save money and contribute to the open source project instead.

How do I monitor Kong properly?

Essential metrics to track:- **Request rate**: Requests per second by route- **Error rate**: 4xx/5xx responses by service- **Latency**: P50, P95, P99 response times- **Upstream health**: Backend availability- **Resource usage**: CPU, memory, connectionsUse Prometheus plugin for metrics collection. Grafana for visualization. Set up alerts for error rate spikes and latency increases.Don't monitor everything - focus on metrics that indicate user-facing problems.

Currently viewing the AI version

Switch to human version

Kong Gateway: AI-Optimized Technical Reference

Executive Summary

Kong Gateway is an open-source API gateway built on OpenResty/NGINX with 41k+ GitHub stars. Handles 50k+ requests/second in production with predictable operational behavior. Version 3.9.1 (June 2025) includes AI capabilities and incremental configuration sync.

Critical Decision Point: Choose Kong for control and flexibility; avoid if you need fully managed service or lack platform engineering resources.

Configuration That Actually Works in Production

Architecture Components

Data Plane: Traffic processing (port 8000 proxy)
Control Plane: Configuration management (port 8001 admin API)
Hybrid Mode: mTLS connection on port 8005 between planes

Database Requirements

PostgreSQL (Recommended)

Always choose PostgreSQL over Cassandra
Requires PostgreSQL 12+
Migration scripts work reliably
Operational overhead manageable

Cassandra

Only for Netflix-scale deployments
High operational complexity
Split-brain scenario risk during outages

DB-less Mode

Uses declarative YAML configuration
Critical Limitation: No rate limiting or OAuth plugins (require persistent storage)
Perfect for microservices, terrible for shared gateways

Performance Specifications

Scenario	Requests/Second	Latency Impact
Baseline	50,000+	0ms
Rate Limiting	45,000	+2ms
JWT Validation	48,000	+1ms
OAuth Plugin	35,000	+5ms
AI Gateway Plugins	40,000-45,000	+10-50ms

Performance Degradation Factors:

Plugin complexity directly impacts throughput
Resource contention reduces performance 20-40%
8 CPU cores recommended for baseline performance

Critical Warnings and Failure Modes

Configuration Sync Failures

Problem: Control plane config sync breaks during rolling updates
Impact: Service downtime, configuration drift
Solution: Deploy control planes first, wait for sync, then update data planes
Real Cost: 4 hours downtime, engineering escalation

Admin API Security

Critical Risk: Exposed admin API (port 8001)
Real Example: 6-month exposure led to $50k fraudulent charges from cryptocurrency mining
Prevention: Network isolation, authentication required

Plugin Resource Consumption

Prometheus Plugin: Resource-heavy, fills disk space
File Log Plugin: Will fill disk storage - guaranteed failure
CORS Plugin: Overly complex configuration for basic functionality

Hybrid Mode Networking

Problem: Networking configuration complexity
Impact: Debugging becomes extremely difficult
Mitigation: Comprehensive monitoring, structured logging

Resource Requirements

Time Investment

Initial Setup: 30 minutes (Docker/Kubernetes)
Production Deployment: 2-4 hours
Learning Curve: Moderate (steeper than marketing suggests)
Operational Maintenance: Ongoing platform engineering required

Expertise Requirements

Understanding of reverse proxy concepts
NGINX/OpenResty knowledge helpful
Database administration (PostgreSQL)
Container orchestration (Kubernetes recommended)

Hardware Specifications

Minimum: 8 CPU cores for 50k+ RPS
Memory: Scales with connections and plugins
Storage: Depends on logging configuration

Decision Criteria vs Alternatives

Feature	Kong Gateway	AWS API Gateway	NGINX Plus	Azure APIM	Envoy Proxy
Performance	50k+ RPS	10k RPS limit	40k+ RPS	20k+ RPS	60k+ RPS
Cost	Free (OSS) / $25+ (Konnect)	$3.50/1M requests	$2.5k/instance	$0.035/1k calls	Free (OSS)
Setup Time	30 minutes	5 minutes	2 hours	15 minutes	4+ hours
Multi-Cloud	✅ Anywhere	❌ AWS only	✅ Anywhere	❓ Azure preferred	✅ Anywhere
AI Gateway	✅ Native	❌ None	❌ None	❌ Limited	❌ None
Operational Complexity	High	Low	Very High	Low	Extreme

Choose Kong When:

Need multi-cloud deployment
Require AI Gateway capabilities
Want plugin ecosystem flexibility
Have platform engineering resources

Avoid Kong When:

Need fully managed service
Lack operational expertise
Require sub-5-minute setup
Want vendor support for failures

Plugin Ecosystem - Production Reality

Proven Plugins

Rate Limiting: Actually works (unlike AWS API Gateway version)

Handles burst traffic properly
Eventually consistent with PostgreSQL
Use Redis for strict enforcement

OAuth 2.0: Proper implementation with PKCE support

Token introspection included
Enterprise OAuth flows supported

JWT: Fast validation (~1ms latency)

Handles rotation correctly
Production-tested

Request/Response Transformer: Eliminates custom middleware need

Problematic Plugins

CORS: Overly complex for basic requirements
Prometheus: Resource consumption issues at scale
File Log: Guaranteed disk space exhaustion

AI Gateway Capabilities

Supported Providers

OpenAI, Azure OpenAI
AWS Bedrock
Anthropic Claude
Google Gemini
Cohere

Key Features

Semantic Caching: Prevents redundant LLM calls
Prompt Guards: PII sanitization, injection protection
Token Cost Reduction: Up to 5x savings with prompt compression
RAG Pipelines: Automated in version 3.10+

Critical Limitation

Cache Invalidation: Semantic cache keys don't invalidate properly during config updates
Impact: API endpoint failures during routine maintenance
Occurrence: 2am production incidents

Deployment Strategies

Container Deployment (Recommended)

Official Docker images (~200MB)
Kong Ingress Controller for Kubernetes
Gateway API support more robust than Ingress

Traditional Package Installation

Ubuntu: apt install kong
CentOS: yum install kong
Amazon Linux: yum install kong
Includes systemd service files and log rotation

Hybrid Mode Production Setup

Deploy control planes first
Wait for configuration sync
Deploy data planes
Critical: Sequence prevents downtime

Pricing Structure Reality

Kong Gateway (Open Source)

Cost: Free
Support: Community only
Risk: 3am debugging without vendor support

Kong Konnect Plus

Base: $25/month (serverless control plane)
Hybrid Control Planes: $200/month each
Developer Portals: $200/month each
Hidden Costs: Analytics, support, advanced features

Enterprise ROI Threshold

Break-even Point: Multiple teams, production workloads
Justification: Commercial support cost vs 3am engineering escalations

Monitoring and Observability

Essential Metrics

Request rate by route
Error rate (4xx/5xx) by service
Latency percentiles (P50, P95, P99)
Upstream health status
Resource utilization

Monitoring Stack

Metrics: Prometheus plugin
Visualization: Grafana
Alerting: Error rate spikes, latency increases
Focus: User-facing problems only

Common Failure Scenarios and Solutions

502 Errors (Upstream Failures)

Causes:

Upstream timeouts (default 60s may be insufficient)
Connection pool exhaustion
Backend service failures
DNS/network issues

Solutions:

Enable upstream health checks
Adjust timeout values for specific APIs
Monitor connection pool utilization

"No Route Matched" Errors

Causes:

Strict path prefix matching (/api/v1/users ≠ /api/v1/users/)
Route priority conflicts
Trailing slash handling

Solutions:

Use regex patterns or wildcards
Create specific routes first
Enable request debugging temporarily

Memory Consumption Issues

Scaling Factors:

Active connection count
Plugin complexity (especially Lua)
Route/service count
Upstream connection pools

Optimization:

Reduce worker_connections (default 1024/worker)
Lower upstream_keepalive pool sizes
Disable unnecessary plugins
Set connection limits on upstream services

CPU Spikes During Startup

Cause: Lua code compilation during initialization
Impact: 30-second high CPU usage
Solutions:

Increase CPU limits during startup
Use init containers for cache warming
Optimize plugin configuration for large route counts

Migration and Upgrade Procedures

Zero-Downtime Upgrade Strategy

Backup database: pg_dump for PostgreSQL
Test migration: Run kong migrations up on database copy
Review breaking changes: Read release notes thoroughly
Blue-green deployment: Separate Kong instances
Traffic cutover: After successful migration test

Migration Command Workflow

# Backup first
pg_dump kong_db > backup.sql

# Test migration
kong migrations up --db-update-propagation-delay=10

# Plan rollback (migrations not always reversible)

Community and Support Resources

Community Quality

Stack Overflow: 5k+ questions with quality answers
Kong Nation Forum: Direct Kong employee responses
GitHub Issues: Active maintenance, responsive to bugs

Documentation Quality

Official Docs: Actively maintained, accurate
Plugin Hub: Working examples, detailed configuration
Benchmarks: Real performance data without marketing

Enterprise Support Value

Justification Threshold: Multiple teams, production workloads
Value Proposition: 24/7 support vs 3am engineering escalations
ROI: Support cost vs downtime cost and engineering time

Technical Specifications for AI Systems

API Endpoints

Proxy: Port 8000 (traffic processing)
Admin: Port 8001 (configuration management)
Hybrid: Port 8005 (mTLS between planes)

Configuration Management

Database: PostgreSQL 12+ required
Declarative: YAML configuration for DB-less mode
Sync: Real-time configuration propagation in hybrid mode

Plugin Development

Language: Lua (OpenResty)
Performance: Direct impact on request latency
Ecosystem: 300+ available plugins (50% production-useful)

Container Specifications

Image Size: ~200MB official images
Resource Usage: Scales linearly with traffic and plugins
Orchestration: Native Kubernetes support via Ingress Controller

This technical reference provides actionable intelligence for AI systems to make informed decisions about Kong Gateway implementation, avoiding common pitfalls while leveraging proven capabilities.

Useful Links for Further Investigation

Kong Gateway Resources (Actually Useful Links)

Link	Description
Kong Gateway Documentation	Official documentation for Kong Gateway that is actively maintained and provides accurate, up-to-date information for users.
Kong Hub	A comprehensive directory of Kong plugins, offering practical working examples and detailed configuration guides to help users implement and manage plugins effectively.
Kong Konnect	Kong's managed service offering, providing a cloud-native API platform with transparent and sensible pricing models for enterprise-grade API management.
Installation Guide	Detailed, platform-specific instructions for installing Kong Gateway, ensuring a smooth and functional setup across various operating environments.
Performance Benchmarks	Provides real, verifiable performance data and benchmarks for Kong Gateway, offering transparent insights into its capabilities without marketing jargon.
Kong Gateway GitHub	The official GitHub repository for Kong Gateway, containing the full source code, issue tracker, and release information, boasting over 41,000 stars.
Kong Kubernetes Ingress Controller	The recommended and most effective method for deploying and managing Kong Gateway within a Kubernetes environment, leveraging native Kubernetes features.
Kong Docker Images	Official Docker images for Kong Gateway, regularly updated with the latest security patches and features for reliable containerized deployments.
Kong Community Forum	An active community forum where users can ask questions and receive direct answers and support from Kong employees and experienced community members.
Kong on Stack Overflow	A dedicated section on Stack Overflow featuring over 5,000 questions related to Kong Gateway, with solutions and insights provided by the developer community.
Kong Configuration Reference	A comprehensive reference guide detailing every available configuration option for Kong Gateway, providing clear explanations and usage examples.
Hybrid Mode Setup	A detailed deployment guide for setting up Kong Gateway in hybrid mode, separating the control plane and data plane for enhanced scalability and resilience.
DB-less Mode Guide	A guide to configuring Kong Gateway in DB-less mode, enabling a Kubernetes-native, declarative configuration approach without an external database dependency.
Plugin Development Guide	A comprehensive guide for developing custom plugins for Kong Gateway, providing best practices and detailed steps to ensure a smooth development process.
Prometheus Plugin	Documentation for the Prometheus plugin, enabling the proper export of Kong Gateway metrics for robust monitoring and alerting with Prometheus.
Logging Best Practices	Guidelines and best practices for structuring Kong Gateway logs effectively, facilitating easier debugging and troubleshooting in production environments.
Health Checks Configuration	Instructions for configuring robust upstream health checks in Kong Gateway, ensuring reliable monitoring and automatic failover for backend services.
Debug Mode Setup	A guide to setting up debug mode in Kong Gateway, allowing for detailed request inspection and troubleshooting without impacting live production traffic.
AI Gateway Overview	An overview of Kong's AI Gateway, detailing its specialized features and capabilities designed to manage and secure AI-powered applications and services.
Semantic Caching Plugin	Documentation for the AI Semantic Caching plugin, designed to intelligently cache responses from Large Language Models (LLMs) to significantly reduce operational costs.
AI Prompt Guard	Documentation for the AI Prompt Guard plugin, providing robust protection mechanisms to prevent prompt injection attacks against AI models and services.
OpenAI Plugin	Documentation for the OpenAI plugin, enabling Kong Gateway to securely proxy and manage requests to OpenAI and various other Large Language Model providers.
Konnect Analytics	Information on Konnect Analytics, providing tools and dashboards to monitor API usage, performance metrics, and overall health of your API ecosystem.
Kong Enterprise Features	Details on the advanced features and capabilities included with the paid enterprise version of Kong Gateway, designed for large-scale, mission-critical deployments.
Support Policy	Documentation outlining Kong's support policy, including version support timelines, lifecycle management, and available support services for enterprise customers.
Migration Guides	Comprehensive guides for safely upgrading Kong Gateway between different versions, ensuring data integrity and minimal downtime during the migration process.
Kong Support	Access to Kong's enterprise support portal, offering dedicated assistance, technical resources, and professional services for paid customers.
Kong Academy	A platform offering free, high-quality training courses and educational content designed to help users master Kong Gateway and related technologies effectively.
Kong Community Events	A blog section featuring information on Kong community events, including webinars, technical sessions, and other valuable content for users and developers.
YouTube Channel	Kong's official YouTube channel, providing a wealth of technical deep dives, tutorials, and demonstrations on various aspects of Kong Gateway and its ecosystem.
Kong Technical Blog	The engineering blog from Kong, featuring in-depth technical articles, architectural discussions, and comparisons of Kong Gateway with other solutions.
API Gateway Comparison Guide	A guide that helps users understand the strengths of Kong Gateway and determine when it is the optimal choice compared to other API gateway alternatives.
API Gateway Comparison	A third-party comparison of various API gateways, including an objective analysis of Kong Gateway's features, performance, and suitability for different use cases.
Custom Plugin Templates	Repository providing official templates and examples to facilitate the development of custom plugins for Kong Gateway, streamlining the creation process.
Kong Vagrant	A Vagrant-based setup for creating a local development environment for Kong Gateway, enabling quick and consistent testing and development.
Kong Homebrew	The official Homebrew tap for installing Kong Gateway on macOS, providing a convenient and up-to-date method for local deployments.
Kong Product Updates	Official announcements and detailed information on the latest features, product enhancements, and new releases across the Kong product portfolio.
Kong Twitter	The official Twitter account for Kong, providing real-time updates, news, and engaging in community discussions about API management and related technologies.
Kong LinkedIn	Kong's official LinkedIn page, offering enterprise-focused content, company news, partnership announcements, and career opportunities within the organization.
Release Notes	Detailed release notes for each version of Kong Gateway, outlining new features, bug fixes, and breaking changes for developers and administrators.