What an APISIX migration involves
A migration to Apache APISIX is a rebuild of the behavior your current gateway provides, followed by a controlled move of live traffic. The work starts with an inventory of what the existing gateway does: every route, upstream, plugin, consumer, authentication method, TLS certificate and logging destination. Teams that skip this step usually discover missing behavior after cutover, when a partner or internal owner finds a header rewrite or rate limit that nobody wrote down. The inventory becomes the acceptance list for the APISIX build.
Common triggers include licensing changes in the current gateway, a decision to consolidate several gateways onto one platform, Kubernetes adoption that favors a gateway managed alongside the cluster, and performance or cost pressure at the edge. Each trigger shapes scope. A licensing exit may only need feature parity for a known set of routes, while consolidation usually means mapping every team's conventions onto one configuration model.
Most teams split the work. Internal owners should keep route knowledge, business priorities and the cutover decision, since they understand which consumers depend on which behavior. A partner typically handles plugin-level mapping, parallel running, traffic shifting and written runbooks. Ask any partner to show how the split works for your inventory before work starts.
APISIX is an Apache-2.0 project built on NGINX and etcd, so engineers with NGINX or Lua experience will recognize much of the runtime. That knowledge does not replace a plugin-level mapping exercise. Each behavior in the current gateway must be matched to an APISIX plugin, a configuration pattern or a custom plugin, and some mappings will differ in ordering, defaults or error responses. Confirm the plugin inventory against the APISIX documentation for the release line you intend to run.
What the work includes
Each deliverable below is written down before cutover begins, so your team can review, accept or reject it at a defined point. The list reflects what a migration onto APISIX typically produces, not a fixed package.
Route and plugin inventory
We catalog every route, upstream, consumer, and plugin or policy on the source gateway, then produce a mapping table to APISIX routes, upstreams, services, consumers and plugins. Gaps where no direct APISIX equivalent exists are flagged for a decision. Check that the inventory includes routes defined outside the main gateway configuration, such as scripts or ad hoc rules.
APISIX deployment design
We agree with your team whether APISIX runs in traditional, decoupled or standalone mode, since each mode changes how configuration is stored and distributed. The design covers the etcd dependency where it applies, network placement, and the Admin API on port 9180 in traditional mode. Confirm which mode fits your change process before any build starts.
Authentication mapping
Each authentication method on the source gateway is traced to an APISIX equivalent, such as key-auth, jwt-auth, basic-auth, openid-connect or forward-auth, along with how identities map to APISIX consumers. Review token lifetimes, claim names and client credential handling with your identity team, because mismatches here cause the most visible failures after cutover.
Configuration export and conversion
Where the source platform exposes its configuration in a usable form, we write export or conversion scripts that generate APISIX configuration from it. Where it does not, the inventory becomes the input for manual construction. Ask your current vendor or platform team which export formats and admin interfaces are available before scoping this item.
Parallel run and traffic shifting
We plan how both gateways serve the same APIs during the transition, including how traffic is split, which clients move first, and what signals show the new path is healthy. Shifting is usually staged by route or client group. Agree the observation window and acceptance criteria with the API owners before the first shift.
Rollback runbooks
Each cutover step has a written runbook that names the trigger for reverting, the exact traffic change to make, and the person authorized to make it. Runbooks are rehearsed in a non-production environment where possible. Confirm that DNS, load balancer and client-side changes can be reverted within the time your service levels allow.
Handover pack
At the end of the engagement your team receives the final configuration, the mapping table, the authentication design, the runbooks, and operating notes for the APISIX deployment. Ask which items will be in version control and who will own them after handover. Clarify in writing whether any items are excluded from handover.
What drives effort and duration
The table lists the factors that most change how long an APISIX migration takes and how much work it creates, with a way to reduce each one before cutover.
| Driver | Why it raises effort | How to reduce it |
|---|---|---|
| Routes and upstreams | Every route needs an equivalent APISIX route, upstream and test case, so counts drive inventory, mapping and verification work. | Retire unused or duplicate routes first, then group the remaining routes by service so each batch can be migrated and tested together. |
| Custom plugins and Lua scripts on the source gateway | Source-specific logic must be re-implemented, re-tested and sometimes redesigned, because plugin APIs differ between gateways. | List each custom plugin, mark which ones are still called, and replace logic with built-in APISIX plugins where the behavior matches. |
| Authentication methods in use | Each scheme (key auth, JWT, OAuth2/OIDC, LDAP, mTLS) needs a mapping to an APISIX plugin, consumer model and identity provider setting. | Standardize on one or two schemes before the move, and confirm which consumers and credentials must carry over unchanged. |
| Protocols beyond HTTP | gRPC, WebSocket, TCP/UDP and MQTT routes use different matching, timeout and health check settings and need protocol-specific tests. | Count non-HTTP traffic early and move it in its own phase, so HTTP routes are not delayed by stream-level configuration questions. |
| Environments and clusters | Each environment and gateway cluster needs its own configuration, secrets, etcd or standalone setup and validation run. | Build one templated configuration source and promote it through environments, so differences are explicit and reviewed. |
| Traffic volume and tolerance for mixed traffic | High volume and strict latency or error budgets limit how long old and new gateways can run side by side and how fast traffic can shift. | Agree the acceptable error and latency window with the business owners, then choose percentage or per-route shifting to match it. |
| Compliance evidence needs | Assessors may expect records of configuration changes, access controls on the Admin API and test results, all of which must be produced during the move. | Define the evidence list before work starts, such as configuration diffs, test outputs and change approvals, and collect it as each batch is cut over. |
| Data model of the current configuration | Source gateways store routes, consumers, certificates and plugin settings in different structures, so translation often needs scripting and manual review. | Export the current configuration, map each object type to APISIX resources in a written table, and validate a sample of translated objects against live traffic. |
Project phases and outputs
The sequence moves an API estate from the current gateway to APISIX in checked stages, with each phase closing on a defined artifact before the next one starts.
Inventory routes, plugins and consumers
The team catalogs every route, upstream, plugin, consumer and authentication rule on the current gateway, including the traffic each one carries. The phase closes with a complete object and plugin map that both sides sign off on before any design work begins.
Design the target APISIX layout
Decide the deployment mode (traditional, decoupled or standalone), whether etcd or file-driven standalone configuration fits the operating model, and the naming and config-as-code repository layout. The phase closes with a written target design that operations and security review.
Convert and test in a non-production environment
Routes and plugins are rebuilt in APISIX from the inventory, and each mapped behavior is checked against the original gateway with parity tests for status codes, headers, redirects and error responses. The phase closes with converted configuration in version control and a parity test report listing any gaps accepted or fixed.
Design and test the authentication cutover
Map each existing credential, token type and identity source to APISIX consumers and authentication plugins, such as openid-connect, key-auth or jwt-auth, depending on what the inventory found. The phase closes with tested consumer and identity mappings, including rejected-request cases, that the application owners have accepted.
Run both gateways in parallel
Production traffic is mirrored or split between the old and new gateways while the team compares results. The phase closes with comparison reports covering latency, error rates and response bodies, and each difference is either resolved or recorded as accepted.
Shift traffic in staged canary steps
Traffic moves to APISIX in increasing steps, with each step checked against agreed health signals before the next one is approved. The phase closes with a shift log and go/no-go records for every step, including the rollback path that was tested at each stage.
Retire the old gateway
Once the agreed traffic has run on APISIX for the agreed period, the old gateway is switched off and its configuration is archived in a retained backup. The phase closes with a retirement record that names the backup location, the access revoked and the owner of the archive.
Work your team keeps and work a partner can take
This table shows which migration tasks usually stay with your team, which a partner can take, and the skills each task requires, so you can decide where to draw the line before the scope is written.
| Work item | Usual owner | Skills required |
|---|---|---|
| Route ownership and business sign-off | In-house: product and API owners with platform leads | Knowledge of which consumers call each route, change approval, and the business impact of downtime on each API |
| Plugin-by-plugin mapping and behavior testing | Partner, or in-house team with prior APISIX experience | APISIX plugin semantics, plugin execution order, and how each source gateway policy maps to an APISIX plugin or custom plugin |
| Authentication and token flow design | Identity team with partner support | OIDC and OAuth2 flows, token introspection, claim mapping to consumers, and the openid-connect plugin configuration against your identity provider |
| Admin API and config-as-code pipelines | Platform engineering, with partner review of the pipeline design | Admin API usage, declarative configuration files, version control and review workflows, and secret handling in CI/CD |
| Parallel-run analysis and rollback drills | Joint: partner runs the comparison, your team owns the go or no-go decision | Traffic comparison across two gateways, latency and error analysis, NGINX behavior under real traffic, and tested reversal of traffic shifts |
| Post-cutover support | In-house, or a support retainer if your team lacks APISIX depth | On-call coverage for the gateway, plugin troubleshooting, and etcd operations if the traditional or decoupled deployment mode is chosen |
What usually goes wrong
Gateway migrations tend to fail in predictable places: behavior that changes quietly, traffic nobody inventoried, and rollback steps that assume things still work. Each card names one failure and the check that catches it early.
Plugin behavior differs from the old gateway
Header handling, path matching, and retry or timeout defaults often differ between NGINX, Kong, a cloud gateway and APISIX, even when the configuration looks equivalent. Replay captured production traffic through both gateways and diff status codes, response headers, rewritten paths and upstream timings before any route moves.
Undocumented routes and shadow consumers
Some routes, internal callers and service accounts exist only in old gateway config, scripts or access logs and never appear in an API catalog. Build the route inventory from gateway exports and several weeks of access logs, then compare it with the APISIX route list after cutover to find calls that have no owner.
Tokens and API keys that do not carry over
Consumer credentials, JWT signing keys and OAuth client secrets are usually stored in a format the new gateway cannot read directly. Confirm which credentials can be imported, which must be reissued, and how each client will receive its new secret, because a missed key shows up as a production authentication failure.
Admin API left at defaults
During a parallel run, the APISIX Admin API on port 9180 can remain reachable with default keys or from networks that should not reach it. Restrict access to administrators and automation hosts, replace the default admin key, and confirm the setting in every environment before the second gateway goes live.
Rate limit counters that differ across nodes
Limits counted locally on each gateway node behave differently from limits the old gateway enforced across its cluster, so clients can exceed quotas or be throttled early. Decide whether counters must be shared, test with traffic spread across all nodes, and record the chosen behavior in the migration runbook.
Rollback that depends on DNS caches
A rollback plan that only changes a DNS record fails when resolvers and client libraries keep the old address cached for longer than the team expects. Prefer a rollback at a load balancer or traffic split that the old gateway still serves, name one owner who can execute it, and rehearse it with a timed test.
How the work changes by starting point
APISIX is built on NGINX, so teams moving from plain NGINX often find the request model familiar. The work is less about syntax and more about recreating behavior that lives outside the configuration file.
- Configuration translation: Server blocks, location rules, upstreams and rewrite logic are mapped to APISIX routes, upstreams and plugins. Each mapping should be checked against the original behavior, not only the syntax.
- Custom Lua and modules: Inline Lua, third-party NGINX modules and custom headers often need a plugin equivalent, a custom APISIX plugin or a change to the upstream service. Inventory these first, because they set the schedule.
- TLS and certificate handling: Certificates, cipher settings and SNI rules move into APISIX's certificate objects. Confirm how existing renewal processes will feed the new store.
- Logging and metrics: Access log formats and monitoring dashboards must be rebuilt, or existing alerts will go silent at cutover.
- Ask your team to confirm: which NGINX modules are compiled in, and which location blocks depend on request state the gateway does not expose.
Kong users usually have a declarative configuration and a set of plugins that map closely to APISIX concepts. The migration is mostly a mapping exercise, with credential and consumer handling needing the most care.
- Declarative config export: Services, routes and plugin settings can be exported and translated into APISIX resources. Review each translation, because plugin defaults and field names differ.
- Plugin equivalents: For each Kong plugin in use, identify the APISIX plugin that covers the same behavior and record any gaps. Gaps may need a custom plugin or a change to the design.
- Consumers and credentials: Export consumers and credentials carefully. Secrets may need to be re-issued or re-hashed, and clients may need a rotation window.
- Workspaces and multi-tenancy: If Kong workspaces separated teams, decide how APISIX will separate them, through naming, groups or separate deployments.
- Ask your team to confirm: which Kong plugins are in production and which are enabled only in test environments.
Managed cloud gateways bundle authorization, quotas and usage tracking with the provider's identity and billing systems. Moving off them means rebuilding those functions on infrastructure you control, and export options are often limited.
- Vendor-specific authorizers: Native authorizers that call the provider's identity service need an equivalent, such as the openid-connect or JWT plugins, backed by your own identity provider.
- Usage plans and quotas: API keys, plans and quota counters must be rebuilt, and the counting model may change. Confirm how quota state and reset behavior will be carried across.
- Limited export: Many managed services do not export configuration in a usable form. Confirm with the provider which configuration, logs and key material you can obtain, and in what format.
- Traffic from the provider edge: Requests that currently pass through the provider's edge may need DNS, TLS and client address handling reworked.
- Ask your provider to confirm: export formats, data retention for logs and any limits on moving keys or certificates out of the service.
Moving from another Kubernetes ingress controller to the APISIX Ingress Controller changes how routes are declared, and it usually runs in parallel with the old controller for a period.
- Resource mapping: Ingress and related resources are mapped to APISIX Ingress Controller custom resources. Annotations are the most common source of drift, so each one should be listed and matched.
- Running both controllers: Traffic can be split at the load balancer or DNS layer while both controllers serve the same hostnames. Confirm that ingress class selection keeps each controller from claiming the other's routes.
- Certificates and secrets: TLS secrets must be readable by the new controller, and the rotation process must work for both during the transition.
- Observability: Metrics, access logs and health checks must be recreated for the new controller before traffic moves.
- Ask your team to confirm: the ingress class names in use and any controller-specific annotations that have no direct equivalent.
In air-gapped or heavily regulated environments, the technical mapping is only part of the work. Packages, changes and evidence must all move through approved channels before anything reaches production.
- Offline packaging: Images, plugin dependencies and the etcd and PostgreSQL components must be collected, verified and transferred into the isolated network with a recorded bill of materials.
- Change approval: Each stage, from staging to cutover, usually needs a change record, a rollback plan and named approvers. Plan these reviews into the schedule from the start.
- Evidence capture: Configuration exports, test results, traffic-shift records and access reviews should be stored as evidence. DeployOpen prepares this evidence for your assessors, but does not issue audit reports or attestations.
- Access to the Admin API: Restrict administrative access to approved operators during migration, because migration tooling often needs wider rights than normal operation.
- Ask your compliance team to confirm: which controls apply to the change, how evidence is retained, and who signs off each cutover step.
What you need to provide
Your team supplies the facts that shape the migration before any APISIX route is written. Start with read access to the current gateway configuration and its logs, including routes, upstreams, plugins, consumers and credentials references. Confirm early what your source gateway lets you export. Some products restrict configuration export or hide plugin settings behind a management console, and that limits what can be inventoried automatically. Ask your current gateway vendor or administrator which objects can be extracted, in what format, and whether secrets come out in clear text or must be re-entered.
Next, provide a named business owner for each API, a traffic profile covering a representative period that includes peak load, and a list of the upstream services each route calls. Owners approve route mappings and rollback decisions, and traffic metrics drive the parallel-running and traffic-shifting plan. Identify the identity provider that protects each API, and provide client registration details, redirect URIs and scopes for any openid-connect flow. Also name the change windows, the approval contacts for each window, and the people who can stop a shift.
Provide a non-production environment with realistic routing, meaning upstreams, certificates and identity settings that match production closely enough to test authentication and plugin behavior. Decide the deployment mode before the build starts: traditional, decoupled or standalone. The choice affects whether etcd must be provisioned and how configuration reaches the gateway nodes. Decide the edition as well. The Apache-2.0 community release carries no vendor support contract, while a commercial APISIX-based product such as API7 Enterprise adds vendor-supplied features and support. Confirm the edition and support terms with the vendor before scoping.
Finally, define rollback criteria in writing. Specify the error rate, latency threshold, authentication failure level or business signal that triggers a return to the previous gateway, and who has authority to invoke it. Without these criteria, a traffic shift stalls at the first unexpected result. Ask your team to confirm which criteria apply to each API tier, so the quote and test plan reflect them.
Frequently asked questions
How much does it cost to migrate from another API gateway to APISIX?
The cost is set by the written inventory, so no price is given here. The main drivers are the number of routes, the plugins and authentication flows in use, any custom logic that must be rebuilt, and the number of environments. The work is mostly engineering time for inventory, plugin mapping, testing, parallel running, cutover and handover. Running the new gateway alongside the old one during the overlap adds infrastructure cost. Ask for a quote that separates one-time migration work from recurring infrastructure and support. DeployOpen issues a fixed-scope quote after the inventory is agreed in writing.
How long does an APISIX gateway migration take?
No duration is stated here, because the timeline depends on your environment. The biggest inputs are the number of routes, the number of custom plugins, the authentication schemes to map, and how long both gateways must run in parallel under your change process. Custom plugins usually add more time than standard configuration because they need design, testing and compatibility checks. Ask for a timeline that is tied to the inventory size and to named milestones in the written scope.
Can our own team migrate to APISIX without a partner?
Yes, if your engineers already know APISIX configuration and the Admin API, and you can run two gateways in parallel for the overlap period. Teams often struggle with mapping plugins that behave differently, rebuilding authentication flows, testing with real client traffic, and rehearsing rollback. Before deciding, compare your team's time and skills against the inventory. A partner is useful when the gap is in plugin mapping, identity integration or cutover testing rather than in general capacity.
Can APISIX import configuration directly from NGINX, Kong or cloud gateways?
Confirm this for your specific source platform and version, because direct import is not assumed here. In practice, teams export route and plugin definitions, map each plugin to its APISIX equivalent, and test that behavior matches. APISIX stores configuration in etcd in traditional and decoupled modes, or in a YAML or JSON file in standalone mode, so the target format depends on the deployment mode you choose. Ask the vendor of your current gateway what export options it offers, and test any conversion on a copy before production use.
What must our team provide before a migration starts?
Your team provides the existing gateway configuration export, a list of routes with owners, and the plugin and authentication settings in use. You also provide upstream service details, traffic volumes and peak windows, TLS certificate ownership, test environments, change windows, named approvers, and access to both gateways and the identity provider. Missing inventory items usually cause the most rework, so agree on the inventory format early and confirm who signs off each route before cutover.
How is live traffic moved to APISIX without outages?
The usual approach is a staged shift. Both gateways run at once, low-risk routes move first, and traffic share increases in steps while responses, logs and error rates are compared. Rollback means pointing the load balancer or DNS record back to the old gateway, which should be rehearsed before the first shift. The goal is to keep client impact small, but no migration plan can promise zero impact, so agree on the thresholds and rollback triggers in writing before cutover.
What happens to the old gateway after cutover?
The old gateway usually stays on standby for an agreed period so traffic can be returned if needed. Once no traffic reaches it and logs have been reviewed, it is decommissioned. Configuration is archived, credentials and certificates tied to it are revoked, and any subscription or license is ended. The retention period depends on your change and audit policies, so confirm it with your compliance and operations owners before cutover.
How DeployOpen delivers APISIX migrations
DeployOpen plans and runs the move from NGINX, Kong or a cloud API gateway to Apache APISIX inside infrastructure you control. The work follows a written scope, a staged build with parallel running and a documented rollback path, and a handover your team can operate.
How we scope
- Inventory every route, upstream, consumer and plugin in your current gateway before estimating the move
- Map each existing authentication method to an APISIX option such as openid-connect, key-auth, jwt-auth or forward-auth
- Agree the deployment mode for APISIX, traditional, decoupled or standalone, based on your change and availability needs
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts
How we build
- Recreate routes and plugin behavior in APISIX configuration under version control, with a test case per migrated route
- Run APISIX alongside the existing gateway and compare responses, latency and error rates for representative traffic
- Shift traffic in planned steps, with a rehearsed rollback that returns traffic to the original gateway without data loss
- Rebuild any gateway behavior without a built-in APISIX equivalent as a custom plugin, tested before cutover
How we hand over
- Deliver the route inventory, mapping decisions and configuration repository with a record of each change made
- Document the Admin API access model, etcd layout, backup steps and the traffic-shift and rollback runbook
- Walk your operations team through monitoring, alerting and day-two changes, and confirm they can run them unaided
How we support
- Ongoing support, upgrades and testing of APISIX and its Ingress Controller are available as a retainer
- Retained support can cover following the APISIX release line and testing plugin and configuration changes before rollout
- Confirm with us in the quote which support tasks, response expectations and release tracking are included
