Migrate from Kong Gateway to Apache APISIX: what the move involves
The move from self-managed Kong Gateway to Apache APISIX is a mapping and cutover exercise, not a lift-and-shift. Kong's configuration model (services, routes, consumers, plugins and credentials) has to be translated into APISIX's own objects (routes, upstreams, consumers and plugin configurations), and each plugin's behavior has to be checked against the APISIX equivalent. The Kong side of the inventory also depends on which edition you run. The Kong Gateway open-source repository is Apache-2.0 licensed and its newest open-source release line is 3.9, while Kong Gateway Enterprise has moved to newer versions and quarterly releases, and self-hosted Enterprise deployments fall under Kong's commercial terms. Confirm which edition and version you run today, since it determines what your team can export and what support you can still expect.
The effort depends on a short list of counts that cannot be estimated until someone writes them down: the number of services and routes, the plugins attached at each level, the consumers and their credentials, any custom Lua plugins, and the rate limiting state that must carry over. Custom Lua plugins are the largest unknown, because APISIX plugins follow a different structure, priority model and loading path, so each one needs a rewrite or a decision to retire it. Rate limit counters are the second unknown, since APISIX keeps counters in local memory by default and shares them only when you configure Redis or a similar store. Build the inventory first, from deck gateway dump output or your declarative files, and use it to scope the work in writing.
The target is open-source Apache APISIX 3.19.0, released September 28, 2026, unless your team chooses a different version after checking the APISIX downloads page, which also does not mark any release as long-term support. Confirm the supported upgrade path and the release cadence your team is willing to follow before you commit to a version, because that choice shapes how often the gateway will need planned upgrades after cutover.
Which Kong concepts map to APISIX and which need redesign
This table compares the Kong Gateway concepts you run today with their APISIX equivalents and notes where the design changes. Read each row as a checkpoint for your inventory: a direct mapping can still need a configuration change, and a missing equivalent means the design needs a decision before cutover. The main takeaway is that authentication, rate limiting and configuration delivery need the most design work.
| Kong concept | APISIX equivalent | What changes the design |
|---|---|---|
| Services and routes | Service and Route objects, with routes pointing to a service and an upstream | Confirm route matching and priority order in your version, since overlapping Kong routes can resolve differently |
| Upstreams and health checks | Upstream objects with node lists and active or passive health checks | Carry over check intervals, thresholds and retry behavior from your current Kong settings and test failover |
| Consumers and key-auth | Consumers identified by username, with the key-auth plugin | Consumer-level plugins take precedence over route settings, so check for overrides that Kong would not apply |
| JWT and basic auth | jwt-auth and basic-auth plugins attached to consumers | Confirm how existing keys, secrets and password hashes are imported, and whether tokens validate unchanged |
| ACL | No one-to-one ACL plugin; consumer-restriction can allow or deny by consumer | Group-based ACL membership may need redesign; confirm group support in your APISIX version before migrating |
| OAuth2 (Kong plugin) | No direct equivalent; openid-connect works with external identity providers | Token issuance moves to the identity provider, so the client flow and token validation need redesign |
| Rate limiting | limit-count with local memory, or redis, redis-cluster or redis-sentinel for shared counters | Kong cluster-strategy limits need a database; APISIX nodes need a redis-family backend to share counters |
| Transformations | proxy-rewrite and response-rewrite plugins, or custom plugins for complex logic | Rewrite results depend on plugin priority, so test header and body changes in the order they run |
| DB-less configuration | Standalone mode with conf/apisix.yaml or apisix.json, reloaded on change | Kong declarative files and decK do not target APISIX, so the Git-stored configuration must be converted |
Documented tools and APIs for moving configuration
Moving a Kong estate to APISIX runs from an export of what Kong holds to an import into APISIX's documented targets. The cards below cover the starting export, the two APISIX targets and the checks needed before any converter is trusted with production configuration.
decK as the starting export
decK is Kong's Apache-2.0 tool for exporting configuration with deck gateway dump and syncing declarative files. Run it against the self-managed Kong Gateway to capture services, routes, consumers and plugins in one file set, and store that snapshot in Git before any mapping starts. Check that the dump includes every plugin configuration, because the export is the only Kong-side record the migration team will work from.
APISIX Admin API target
The Admin API is the runtime target for routes, upstreams, consumers and plugin settings in traditional and decoupled deployments. In traditional mode it listens on port 9180, so the team must confirm that this port is reachable only from the change pipeline and not from client networks. Map each Kong object to its APISIX resource and record the ID scheme used, since later rollback depends on it.
Standalone YAML or JSON file mode
Standalone mode reads conf/apisix.yaml or conf/apisix.json and reloads changes without a restart, with no etcd cluster. It fits a Git-driven flow similar to Kong's DB-less mode, so the converted file can be reviewed in the same way as the decK snapshot. Confirm that the team is comfortable with the file being the single source of truth before choosing this target over the Admin API.
No documented one-click converter
No official converter from Kong declarative files to APISIX configuration is documented, so the mapping must be built and reviewed by the team. Any third-party converter, script or generated sample should be treated as a draft. Run it against a non-production copy of the Kong export, compare every route, consumer and plugin field with the Kong source, and keep the review record with the change.
Validation before cutover
Each converted configuration needs a test pass before it receives traffic. Compare route matching, authentication outcomes, rate limit responses and upstream selection for a set of representative requests against both gateways. Use the same test set for the canary phase, so any difference found during the traffic split traces back to a specific mapping decision.
How the migration sequence runs from inventory to decommission
The sequence moves Kong state into APISIX in verified stages, so each cutover step has a mapping file, a test result or a traffic-split setting that shows it is safe to continue. Kong stays in place until the final step, which keeps rollback available throughout.
Export and inventory the Kong state
Your platform team exports the running configuration with decK (
deck gateway dump) and records what the export does not cover, such as consumer credentials, plugin settings held outside declarative files, custom Lua plugins on disk and the Kong database if you run traditional mode. Kong Gateway in traditional mode keeps database-dependent state that a declarative export may not show, so confirm this against your own deployment. The step is done when every service, route, consumer, plugin and external dependency is listed in one inventory and the team agrees it is complete.Build the Kong to APISIX mapping workbook
Working from the inventory, the team maps each Kong service to an APISIX upstream and service, each route to an APISIX route, each consumer to an APISIX consumer, and each plugin to its APISIX equivalent with the same precedence checked. Items with no direct equivalent, such as cluster-strategy rate limiting that depends on a shared database, are flagged with a chosen replacement and an owner. The output is a versioned mapping file kept in Git, reviewed by the security and API owners before any APISIX object is created.
Pilot one low-risk route on APISIX
The team picks one route with low traffic and few plugins, creates it in APISIX from the mapping file, and runs it in a non-production environment with the same upstream. Tests compare status codes, response bodies, headers and authentication outcomes between Kong and APISIX for a set of recorded requests. The pilot is complete when the comparison shows no unexplained differences and the team has written down each difference it accepted. This step tests the workbook, so any mapping errors found here are fixed in the file before the next route.
Migrate credentials and rate limit counters
Key-auth and JWT credentials are re-issued or imported into APISIX consumers after the signing keys and key identifiers are confirmed to match, so existing callers keep working. Rate limiting needs a decision: the limit-count plugin keeps counters in local memory by default or shares them through Redis, and routes in the same group share one counter, so the team sets the group and backend deliberately. The output is a credential reconciliation report and a counter test that shows a caller hits the same limit on both gateways.
Port and test custom Lua plugins
Each custom Kong Lua plugin is rewritten as an APISIX plugin with a unique name and priority, loaded from extra_lua_path and added to the plugins list in config.yaml. The plugins list replaces the default list rather than merging with it, so the team lists every built-in plugin they still use. Each plugin is tested with the test-nginx framework, and the artifact is a passing test suite plus a build the platform team can roll back to the previous image.
Run parallel traffic with a traffic-split canary
Both gateways serve production for the same routes while a traffic-split setting sends a small, stated share of requests to APISIX. Dashboards compare error rates, latency, authentication failures and 503 responses from the limit-count plugin on each side. The team increases the APISIX share only when the agreed checks pass for the period they set in advance. The output is a dated log of split settings and the metrics behind each change.
Cut over fully and define rollback criteria
Before the full cutover, the team writes rollback criteria, such as an error rate threshold, a credential failure pattern or a counter mismatch, and names who can trigger the rollback. The traffic split is set to send all requests to APISIX, and DNS or load balancer records are updated to point at APISIX. Kong remains running with its configuration unchanged. The step is done when the rollback test has been rehearsed and the cutover change record is signed off.
Decommission Kong after the agreed hold
After the post-cutover hold agreed in the cutover plan, the team confirms no traffic reaches Kong, archives the final decK export and database backup if one exists, and removes Kong routes, plugins and consumers from production. Access to Kong admin endpoints is revoked, and any secrets held only by Kong are rotated or retired. The output is a decommission record that lists archived artifacts and the date each Kong component was removed.
What drives the effort and duration of a Kong to APISIX move
This table lists the factors that most change the scope, cost and calendar of a Kong Gateway to APISIX migration, who carries each cost, and whether it is one-time or recurring. Use it to check that a quote prices each driver against your own inventory rather than a generic gateway project.
| Driver | Why it changes effort | Who pays and one-time or recurring | What to ask for in a quote |
|---|---|---|---|
| Services, routes and upstreams | Each Kong service and route must be mapped to an APISIX route and upstream, and the count sets the size of the translation and test matrix. | Partner or internal team pays once for inventory and mapping. Route maintenance after cutover is recurring and falls to your platform team. | A written inventory count by service, route and upstream, and the mapping method for each (decK export, script or manual). |
| Plugins per route | Kong plugins that have no one-to-one APISIX equivalent need a redesign, and stacked plugins multiply the configuration and test cases. | One-time design and test cost. Plugin configuration in Git is an ongoing cost for your team. | A plugin-by-plugin table showing the APISIX equivalent, its configuration, and any plugin left unmapped. |
| Custom Lua plugins and dependencies | Custom plugins must be ported to APISIX's plugin model, registered in config.yaml, given a unique name and priority, and tested with test-nginx. Shared libraries and external calls add work. | Often the largest one-time cost. Recurring cost appears when the plugin must be maintained against new APISIX releases. | Source review of each Lua plugin, its dependencies, and whether it is ported, rewritten or retired, with test coverage stated. |
| Consumers and credentials | Kong consumers, key-auth, JWT and other credentials must be recreated as APISIX consumers with matching identifiers, and credential secrets must be moved without exposure. | One-time migration and verification cost. Ongoing credential lifecycle is an operational cost for your security or API team. | Consumer and credential counts by type, the secret transfer method, and a plan for clients that must rotate keys. |
| Rate limit counter sharing | APISIX limit-count keeps counters in local memory by default. Sharing counters across nodes requires redis, redis-cluster or redis-sentinel, which changes the design and the failure behavior. | One-time design and build cost. The shared store is a recurring infrastructure cost that your team operates. | Whether limits must be shared across nodes, the chosen backend, and how counter state is handled during cutover. |
| Authentication and authorization model | Kong ACL, OAuth and JWT patterns may map to different APISIX plugins and consumer precedence rules, which changes how access is tested. | One-time design and test cost. Identity provider changes stay with your identity team. | A mapping of each Kong auth plugin to its APISIX counterpart and a test plan for allowed and denied calls. |
| Deployment topology | A self-managed Kong setup in DB-less, traditional or hybrid mode points to different APISIX modes (traditional, decoupled or standalone), each with its own control plane work. | One-time architecture and build cost. Platform hosting and etcd operation are recurring. | The chosen APISIX deployment mode with reasons, the sizing inputs, and who operates etcd or the file-driven configuration. |
| CI/CD and Git workflow changes | Declarative files exported with decK must be replaced by APISIX configuration in Git and a pipeline that applies it, which changes review, approval and rollback steps. | One-time pipeline build cost. Pipeline upkeep is recurring and sits with your DevOps team. | The target configuration workflow, pipeline ownership, and how existing Kong review gates carry over. |
| Parallel run length and canary traffic split | Both gateways must serve live traffic while traffic is split and compared. The length depends on how many routes change, how many clients are affected and the risk your change board accepts. | Dual-running cost is paid by your team for both gateways during the window. Length is set by your change and risk process, so ask for it in writing. | The parallel run duration you are planning for, the traffic-split steps, the metrics that gate each step, and the rollback trigger. |
Porting custom Kong Lua plugins to APISIX
Custom Lua plugins written for Kong Gateway do not run on APISIX as they are. Each one needs a rewrite to the APISIX plugin model, and the work starts with an inventory of every custom plugin, the Kong handler phases it uses (access, header filter, log and so on), and the configuration fields it reads. Treat that inventory as the scope of the port. Where a plugin only combines built-in behavior, such as header manipulation or simple key checks, first ask whether an existing APISIX plugin already covers it, since that avoids maintaining code at all.
For plugins that must be ported, the mechanics are specific. The plugin module is loaded from the directory named by extra_lua_path, and its name must be added to the plugins list in config.yaml. That list replaces the default list rather than merging with it, so omitting a built-in plugin you still use will silently disable it. Each plugin also needs a unique name and a priority value. Kong's handler phases and APISIX's priority ordering do not map one to one, so the reader must decide where the logic runs relative to authentication, rate limiting and rewrites, and confirm that ordering against the APISIX plugin development documentation before writing code.
Testing should target behavior, not syntax. The APISIX plugin development guidance uses the test-nginx framework, and each ported plugin should have test cases that reproduce the Kong behavior on the same requests: accept and reject paths, header values forwarded upstream, error codes returned and log output. Run the same request set through the Kong instance and the APISIX staging route, and treat any difference as a defect until it is explained. Plan for this check to take longer than the coding for plugins with timing or shared-state logic, and confirm the chosen test approach with your APISIX engineers before the port begins.
Questions teams ask before moving from Kong to APISIX
What does a move from Kong to APISIX cost, and what drives the price?
The price follows from the written scope, and no fixed figure applies to every move. The main drivers are the number of services, routes and consumers, how many Kong plugins need an APISIX equivalent, whether custom Lua plugins must be ported, how many credential types and rate limit policies carry over, and how many environments need parallel running. Costs are mostly one-time (inventory, mapping, build, testing and cutover), while hosting, Redis or etcd operations and any ongoing support recur. When you request a quote, ask for the inventory method, the list of assumed plugin mappings, the cutover and rollback steps, and what is excluded. DeployOpen does not publish a price list.
How long does a Kong to APISIX migration take?
Duration depends on the same drivers as cost: the size of the Kong configuration, the number of custom plugins, and how many production consumers depend on current behavior. Teams that keep configuration in declarative files and have few custom plugins generally have less mapping work than teams with a self-managed database and many Lua plugins. Plan time for a parallel run long enough to observe real traffic through both gateways, because cutover should follow that observation, not the calendar. Ask for a phased timeline in the written scope that names the gates each phase must pass.
What does our internal team need to provide during the move?
Your team owns the facts about traffic and access. Expect to provide a current export of Kong configuration, the list of Kong plugins in use with their settings, the owners of each service and consumer, the upstream health and timeout expectations, the certificates and DNS records involved, and named approvers for the cutover window. Your team also needs access to the Kong and APISIX environments in your own infrastructure and someone who can confirm which API callers are still active. Missing ownership data is one of the most common causes of delay, so confirm it before work starts.
Can our own engineers do the migration without a partner?
Yes, if your team has the skills and time to do it. The work is well defined: export Kong configuration (decK can dump and sync declarative files for Kong), map each Kong plugin to an APISIX plugin with the same behavior, rebuild consumers and credentials, port any custom Lua plugins to APISIX's plugin structure, and test each route in both gateways. The hard parts are behavioral differences that show up only under load or in edge cases, such as precedence of plugins and how counters behave. A partner brings a repeatable test and cutover method. Compare the cost of your team's time with the cost of a written scope, and confirm your skills in Lua testing and APISIX operations first.
How do rate limit counters and API keys carry over from Kong?
API keys do not move automatically because the two gateways store and identify consumers differently. In APISIX, a consumer is identified by username, and authentication plugins such as key-auth and jwt-auth attach the consumer to a request. Your team must map each Kong consumer and credential to an APISIX consumer and credential, and decide whether the same secret values can be reused or must be reissued, which affects client changes. For rate limits, the APISIX limit-count plugin keeps counters in local memory by default or shares them through Redis, Redis Cluster or Redis Sentinel. Counters in local memory do not carry over, so a cutover resets them. If you need shared limits during the move, plan a shared store and confirm how it behaves when routes use the same group. Ask the team to test limit behavior with real credentials in staging.
What happens if the cutover fails?
A safe cutover keeps Kong running and serving traffic until the APISIX path has proven itself, so rollback means shifting traffic back, not rebuilding configuration. Use a traffic split that sends a small share of requests to APISIX, watch error rates, latency, authentication failures and rate limit responses, then increase the share in steps. Rollback should be a rehearsed action with a named owner and a defined trigger. Keep Kong configuration exported and under version control so it can be restored. Confirm in the written scope which parts of the rollback are DeployOpen's responsibility and which remain with your operations team. Note that the Kong open-source line in use is the 3.9 series, and its support window is not published, so plan a path off it that does not depend on that window.
Does the migration plan cover Kong custom Lua plugins?
Custom Lua plugins need separate analysis because Kong and APISIX use different plugin structures. APISIX loads custom Lua plugins from a path set by extra_lua_path, requires each plugin to be added to the plugins list in config.yaml, and needs a unique name and priority. The plugins list replaces the default list rather than merging with it, so omitting a built-in plugin can break traffic. Each ported plugin should be tested with the test-nginx framework that APISIX documents, and its behavior compared against the Kong version under the same requests. Ask for a plugin-by-plugin decision in the scope: port, replace with a built-in APISIX plugin, or retire.
What usually goes wrong in a Kong to APISIX move
Most failed gateway migrations do not fail on the first request. They fail when a consumer's precedence changes, a counter quietly resets, or a rollback has never been run. The cards below cover the risks we see most often in a Kong to APISIX move and the prevention step for each.
Consumer precedence changes which plugin wins
APISIX resolves plugin precedence as Consumer, then Route, then Plugin Config, then Service. Kong resolves the same plugin attached at several levels differently, so a rate limit or auth rule that was overridden at route level in Kong can take effect at consumer level in APISIX. Build a table of every plugin attached at more than one level in Kong, then test each affected route with a request from a consumer that has its own plugin settings.
Rate limit counters diverge across nodes
The limit-count plugin keeps counters in local memory by default, so each APISIX node counts independently and a client can exceed the limit it was given in Kong. Kong's cluster-strategy rate limiting does not carry over, so the shared-counter choice must be made deliberately. Decide whether to use Redis, Redis Cluster or Redis Sentinel, load test with several nodes, and confirm that rejected requests return the status code your clients expect.
Plugins silently missing after list replacement
In config.yaml, the plugins list replaces the default list rather than merging with it. A custom Lua plugin added without copying the default plugins can leave authentication or logging disabled, and the gateway still starts and serves traffic. Keep the full list in version control, diff it against the default list for each APISIX release, and add a test that asserts each required plugin is active on a sample route.
Credentials exported without secret review
Kong key-auth and JWT credentials, and any HMAC secrets, must be exported and imported into APISIX consumers. Export files often carry plaintext secrets in backups, CI logs or shared drives. Agree in writing who may run the export, where the file is stored during the move, and how it is destroyed afterward. Confirm with your security team how APISIX will store consumer secrets at rest before any credential is imported.
Kong database behavior with no equivalent
Kong in traditional mode supports database-dependent plugins such as cluster-strategy rate limiting and OAuth2, and DB-less mode restricts what can be configured. Any plugin in use that depends on Kong's database has no direct APISIX match. Inventory every enabled plugin, mark the ones that rely on Kong's database, and decide for each whether to replace it with a plugin such as openid-connect, rebuild it as a custom plugin or retire it.
Rollback that has never been tested
A canary cutover with traffic-split is only useful if the reverse path works under load. Teams often confirm that APISIX serves traffic but never send live traffic back to Kong, or they discover that Kong's configuration has drifted during the parallel period. Before the first split, rehearse a full rollback in a staging environment, set a traffic percentage that returns to Kong in one change, and keep Kong's declarative configuration exported and current until the cutover is closed.
Decisions to settle before the pilot starts
Settle the deployment mode before anyone writes a route. APISIX offers traditional mode, where data and control planes run together, decoupled mode, where separate data plane nodes share one etcd cluster with the control plane, and standalone mode, which has no etcd and reads configuration from conf/apisix.yaml or conf/apisix.json. Kong's DB-less mode is the closest match to standalone, since both keep configuration in files that can live in Git. Standalone mode reloads the file about every second, which suits GitOps delivery, but it moves change control into your repository rather than into an Admin API workflow. If your Kong estate depends on a database-backed control plane, choose traditional or decoupled mode and plan for etcd backups and access controls. Confirm the mode against the deployment modes documentation before the pilot.
The shared counter backend is the decision most likely to change behavior silently. The limit-count plugin keeps counters in local memory by default, so each gateway node enforces its own limit unless you point it at redis, redis-cluster or redis-sentinel. Kong's cluster-strategy rate limiting and OAuth2 depend on its database, so map each Kong limit to an APISIX backend and test the effective limit across several nodes. Also decide whether routes that share a quota will use a common group, and whether you need the sliding window, which requires APISIX 3.18.0 or later.
Choose the release channel with care. The APISIX downloads page lists APISIX 3.19.0 as released on September 28, 2026, and it does not mark any release as long-term support. Ask who in your organization owns patching, how quickly you will move to each new minor release, and whether you will pin a version in your image and Helm values. Kong's version support policy gives no published support window for its open-source edition, so compare the two products on the basis of your own upgrade capacity, not on a vendor commitment. Also decide which version of the APISIX Ingress Controller, if any, runs beside the gateway.
How DeployOpen scopes and delivers the Kong to APISIX migration
DeployOpen is a Chainscore Labs company that plans, implements, customizes, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. The cards below follow the order of a typical engagement, from the written scope that sets the price to the support that follows cutover.
Written scope before any build
Most engagements are fixed-scope, so the migration starts with a written scope that names the Kong services, routes, consumers, plugins and custom Lua code being moved. Ask for the inventory method in writing, including how plugin configuration is exported and which Kong environments are in scope. A scope that leaves the custom plugin list open will change the quote later.
Deliverables and timelines in writing
The written scope also lists each deliverable, such as the mapped route set, the converted consumer and credential records, the canary runbook and the rollback procedure, with a timeline for each. Check that every deliverable names an owner on both sides. Ask what happens if the source gateway changes during the engagement.
A quote that follows from scope
DeployOpen does not publish a price list. The quote follows from the written scope, so the cost drivers are the number of services, the count and complexity of custom Lua plugins, the credential and counter migration, and the number of environments. Ask the quote to separate one-time migration work from any recurring items.
Implementation inside your infrastructure
DeployOpen builds the APISIX deployment in your cloud accounts, data centers or restricted networks, so traffic and credential material stay under your control. Confirm early which APISIX deployment mode fits your estate, since traditional mode needs etcd and standalone mode reads configuration from a file. Agree who holds the cluster and admin access after handover.
Hardening and documentation at handover
Before cutover, the APISIX environment is hardened and documented, covering admin access, TLS, plugin allow-lists and logging. Handover includes runbooks for day-two tasks such as adding a route or rotating a credential. Ask for the documentation list in the scope so your team can check it against its own operating standards.
Retainers for ongoing support
After cutover, the gateway needs upgrades, plugin updates and incident support. Ongoing support, upgrades and continuous testing are available as retainers, separate from the fixed-scope migration. Ask what a retainer covers, how upgrade windows are agreed, and how security findings are handled.
