Copy page

Migration Guides

Migrate from Kong Gateway to Zuplo

This guide walks through migrating from Kong Gateway (Community Edition or Enterprise) to Zuplo. Whether you're running Kong OSS on Kubernetes, Kong Konnect, or a self-hosted Kong cluster, this guide covers the key differences, concept mapping, and step-by-step migration process.

Why teams migrate from Kong

Kong Gateway is a powerful, plugin-driven API gateway built on NGINX and Lua. However, teams frequently encounter challenges that drive them to seek alternatives:

• Community Edition stagnation — Kong's open-source Community Edition receives fewer updates and lacks critical features like the developer portal, RBAC, and advanced rate limiting that are reserved for Enterprise tiers.
• Kubernetes complexity — Running Kong in production requires managing Postgres or Cassandra databases, configuring the Kong Ingress Controller, and maintaining Kubernetes clusters across environments.
• Lua plugin development — Kong's plugin architecture requires Lua, a niche language that few developers know. This limits who on your team can extend the gateway and makes AI-assisted code generation less effective.
• Cost escalation — Kong Konnect pricing starts at ~$105/month per gateway service plus ~$34/million API requests, with additional charges for analytics, portals, and mesh management. Self-hosted Kong requires significant SRE investment.
• Global scaling challenges — Scaling Kong globally requires deploying and synchronizing clusters across regions manually, each with its own database and configuration state.

Concept mapping: Kong to Zuplo

Kong concept	Zuplo equivalent
Service	Backend URL configured in a route handler
Route	Route in your OpenAPI spec
Plugin (Lua)	Policy (TypeScript) or built-in policy
Consumer	API key consumer
Consumer group	API key metadata with custom rate limit logic
Upstream	URL forward handler target
Workspace (Enterprise)	Environment
Kong Manager / Konnect UI	Zuplo Portal or local development with Git
DB-less declarative config	OpenAPI route config in Git
Admin API	Zuplo API or git push
Kong Dev Portal	Zuplo Developer Portal

Step-by-step migration

Step 1: Export your API definitions

If you have OpenAPI specs for your APIs, export them from Kong. If you're using Kong's declarative configuration, convert your service and route definitions to an OpenAPI spec.

From Kong declarative config (deck):

Code
# kong.yml - Your existing Kong config
services:
  - name: my-api
    url: http://backend-service:8080
    routes:
      - name: get-users
        paths:
          - /users
        methods:
          - GET
      - name: create-user
        paths:
          - /users
        methods:
          - POST

Equivalent OpenAPI spec for Zuplo:

Code
{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "operationId": "get-users",
        "summary": "Get users",
        "x-zuplo-route": {
          "corsPolicy": "none",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "http://backend-service:8080"
            }
          },
          "policies": {
            "inbound": []
          }
        }
      },
      "post": {
        "operationId": "create-user",
        "summary": "Create user",
        "x-zuplo-route": {
          "corsPolicy": "none",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "http://backend-service:8080"
            }
          },
          "policies": {
            "inbound": []
          }
        }
      }
    }
  }
}

Step 2: Map Kong plugins to Zuplo policies

The following table maps common Kong plugins to their Zuplo policy equivalents:

Kong plugin	Zuplo policy
key-auth	API Key Authentication
jwt	Open ID JWT Authentication
basic-auth	Basic Authentication
rate-limiting	Rate Limiting
rate-limiting-advanced	Complex Rate Limiting
request-transformer	Transform Body
response-transformer	Transform Body Outbound
cors	Built-in CORS configuration
ip-restriction	IP Restriction
request-size-limiting	Request Size Limit
request-validation	Request Validation
acl	ACL Policy
Custom Lua plugin	Custom Code Policy (TypeScript)

Step 3: Translate plugin configuration

Here is an example of translating a Kong rate limiting plugin to a Zuplo rate limit policy.

Kong plugin configuration:

Code
plugins:
  - name: rate-limiting
    config:
      minute: 100
      policy: local
      limit_by: consumer

Zuplo policy configuration:

Code
{
  "name": "rate-limit-inbound",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "user",
      "requestsAllowed": 100,
      "timeWindowMinutes": 1
    }
  }
}

Step 4: Migrate authentication

Kong key-auth to Zuplo API Key Authentication:

Kong uses consumers with key credentials stored in its database. In Zuplo, API keys are managed through the built-in API key management system, which includes a self-serve developer portal for key creation and rotation.

1. Add the api-key-inbound policy to your routes.
2. Create API key consumers through the Zuplo Portal or API.
3. Optionally, enable the Developer Portal for self-serve key management.

Kong jwt to Zuplo JWT Authentication:

Replace Kong's JWT plugin with one of Zuplo's JWT authentication policies:

• Auth0 JWT
• AWS Cognito JWT
• Firebase JWT
• Open ID JWT (generic OIDC)

Step 5: Set up your project and deploy

1. Create a new project in the Zuplo Portal or using the Zuplo CLI.
2. Import your OpenAPI spec as the route configuration file.
3. Add policies to your routes.
4. Connect your project to source control.
5. Push to deploy — Zuplo deploys globally in under 20 seconds.

Step 6: Migrate traffic

Run Zuplo alongside Kong during migration:

1. Point a subset of traffic to Zuplo using DNS or a load balancer.
2. Monitor both gateways for correctness and performance.
3. Gradually shift more traffic to Zuplo.
4. Decommission Kong once all traffic is migrated.

Custom Lua plugins to TypeScript

If you have custom Kong plugins written in Lua, rewrite them as Zuplo custom code policies in TypeScript.

Kong Lua plugin example:

Code
local MyPlugin = {}

function MyPlugin:access(conf)
  local header_value = kong.request.get_header("x-custom-header")
  if not header_value then
    return kong.response.exit(403, { message = "Missing required header" })
  end
end

return MyPlugin

Equivalent Zuplo TypeScript policy:

Code
import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";

export default async function (
  request: ZuploRequest,
  context: ZuploContext,
  options: never,
  policyName: string,
) {
  const headerValue = request.headers.get("x-custom-header");
  if (!headerValue) {
    return HttpProblems.forbidden(request, context, {
      detail: "Missing required header",
    });
  }
  return request;
}

Kong DB-less mode to Zuplo GitOps

If you use Kong's DB-less declarative mode, you're already familiar with configuration-as-code. Zuplo takes this further with native GitOps:

Kong DB-less	Zuplo GitOps
Single kong.yml file	OpenAPI spec + policy configs in Git
deck sync to apply changes	git push triggers automatic deployment
Manual environment management	Automatic branch-based environments
No PR-based review workflow	PR reviews with preview environments
Manual rollback	git revert and push

Next steps

• Set up your first Zuplo gateway
• Add rate limiting
• Add API key authentication
• Configure your developer portal
• Set up source control