Migrating from Kong Gateway to Gatez

Overview

This guide walks through migrating a Kong Gateway deployment to Gatez. Gatez uses Apache APISIX as its L1 API gateway layer, which means most Kong concepts have direct equivalents.

Estimated migration time:

• 50 routes, no custom plugins: 2-3 weeks (with translator tool)
• 50 routes, no custom plugins, manual: 6-10 weeks
• Add 2-4 weeks per custom Kong plugin

Prerequisites

• Gatez stack running (docker-compose up -d)
• Kong deck CLI installed (brew install kong/deck/deck)
• Python 3 with PyYAML (pip3 install pyyaml)

Step 1: Export Kong Configuration

# Export your Kong config to YAML
deck gateway dump -o kong-config.yaml

# Verify the export
cat kong-config.yaml | head -50

Step 2: Run the Translator

# Translate Kong config to APISIX routes
./scripts/kong-to-gatez.sh kong-config.yaml ./migration-output

# Review the migration report
cat ./migration-output/migration-report.md

The translator will:

• Convert each Kong service/route to an APISIX route JSON file
• Map Kong plugins to APISIX equivalents (see plugin mapping)
• Flag plugins that need manual migration
• Generate an apply-routes.sh script

Step 3: Review and Adjust

Before applying, review each generated route file:

# List generated files
ls ./migration-output/route-*.json

# Review a specific route
cat ./migration-output/route-my-api.json | jq

Common adjustments needed:

• Update upstream addresses (Kong service hosts → Docker service names)
• Add tenant-rate-limit plugin (Gatez multi-tenancy)
• Add clickhouse-logger plugin (Gatez request logging)
• Configure Keycloak OIDC if migrating from Kong OAuth2

Step 4: Apply Routes to APISIX

# Apply all routes
./migration-output/apply-routes.sh

# Verify routes were created
curl http://localhost:9180/apisix/admin/routes \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" | jq '.list | length'

Step 5: Parallel Run

Run both Kong and Gatez simultaneously, routing a percentage of traffic to Gatez:

# Test each route against Gatez
curl http://localhost:9080/your-api/endpoint -H "Host: your-api.example.com"

# Compare response with Kong
diff <(curl -s kong:8000/your-api/endpoint) <(curl -s localhost:9080/your-api/endpoint)

Step 6: Migrate AI/Agent Features

If you're using Kong AI Gateway plugins, these are handled at L2/L3 in Gatez:

Kong AI Feature	Gatez Equivalent	Configuration
AI Proxy	L2 /v1/chat/completions	Set OPENAI_API_KEY, ANTHROPIC_API_KEY in .env
AI Rate Limiting	L2 token budgets	POST /v1/budget/{tenant_id}
AI Semantic Cache	L2 two-tier cache	Automatic (Redis + Qdrant)
AI PII Sanitizer	L2 PII redaction	Automatic (regex-based, pre-request)
MCP Proxy	L3 MCP server registry	POST /v1/mcp/servers

Step 7: Cutover

Once all routes are verified:

1. Update DNS/load balancer to point to Gatez (port 9080)
2. Monitor via Grafana dashboards (http://localhost:3002)
3. Monitor via Operator Portal (http://localhost:3003)
4. Keep Kong running for 1 week as rollback option

Concept Mapping

Kong Concept	Gatez Equivalent
Service	APISIX Upstream
Route	APISIX Route
Consumer	APISIX Consumer
Plugin	APISIX Plugin
Workspace	Tenant (tenant_id in JWT)
Admin API	APISIX Admin API (:9180)
Kong Manager	Operator Portal (:3003)
Dev Portal	Developer Portal (:3004)
Konnect	Control Plane API (:4001)
decK	kong-to-gatez.sh translator

What You Gain

After migrating, you get features Kong charges $50K+/year for:

• Per-tenant rate limiting — every tenant, not just Enterprise Workspaces
• Token budgets — pre-request enforcement, not just billing analytics
• Full on-premises AI stack — no Konnect SaaS dependency
• Agent session governance — HITL, tool allowlists, blast radius (Kong doesn't have this)
• Cross-layer tracing — L1→L2→L3 in one OTel trace (Kong is single-layer)
• No per-service licensing — Kong charges ~$105/month per Gateway Service