Apache APISIX 2.x to 3.x upgrade

Apache APISIX 2.x to 3.x upgrade: when and why to move

If your Apache APISIX gateway runs on the 2.x line and carries production API traffic, plan a move to a supported 3.x release, and do not attempt a direct jump. The supported path runs through 2.15 first, so the first decision is whether your current 2.x deployment can be brought to 2.15 with a tested, reversible change. The current 3.x release named on the APISIX downloads page is 3.19.0, released September 28, 2026. That page does not mark any release as long-term support, so confirm with the Apache APISIX project which 3.x line your support policy requires before you pick a target version. Record that decision in writing, because it sets how often you must repeat this upgrade work. The reasons to move usually come from the gateway's role, not from the version number alone. A 2.x gateway that sits in front of payment, identity or partner APIs will eventually face security fixes, plugin changes and dependency updates that only land on newer lines. Your security team should map which of your routes depend on authentication, TLS or logging plugins, because those are the areas where 3.x changes are most likely to alter behavior. Your platform team should also confirm which deployment mode you run. Traditional mode uses etcd and listens on port 9080 for client traffic and port 9180 for the Admin API, and the etcd data and configuration file changes described in the sibling sections depend on that mode. Before you commit a date, inventory your routes, plugins, custom Lua code and any automation that calls the Admin API, and compare that inventory against the release notes for every version between your current release and your target. Run the upgrade in a staging copy first, using a configuration export that matches production. Then decide whether a parallel cluster with a controlled traffic cutover and a documented rollback is feasible in your environment. The APISIX deployment modes documentation explains how each mode stores and loads configuration, which informs how you will run both clusters side by side.

What changes in the Apache APISIX 2.x to 3.x upgrade

This table lists each change area in a 2.x to 3.x move, what it affects and what your team must do before cutover. Read it as a checklist: confirm every field name, endpoint and default against the 3.x upgrade guide in the project documentation before you apply any change.

Change area	Impact	Action needed
Config file restructuring	Static configuration in conf/config.yaml is reorganized between the 2.x and 3.x lines, so an existing file may not load or may change behavior silently.	Generate a new 3.x config from the packaged template, port only the settings you need, and confirm each key against the 3.x upgrade guide.
etcd data rebuild	Stored route, upstream and plugin data written by 2.x is not a safe in-place input for 3.x, so the data model must be rebuilt or re-imported.	Export your configuration as code, rebuild the etcd data on a 3.x test cluster, and verify the results before any traffic moves.
Admin API response and endpoint changes	Scripts, CI pipelines and dashboards that call the Admin API on port 9180 may receive different response bodies or hit changed or removed endpoints.	Inventory every Admin API call your automation makes, then test each one against a 3.x instance and update any parsers that read response fields.
Plugin field changes	Plugin configuration keys can be renamed, added or change defaults, so routes that worked on 2.x may fail validation or behave differently on 3.x.	List every plugin in use, compare its 2.x and 3.x schema, and confirm each field and default in the upgrade guide.
Route field changes	Route objects can gain, rename or reinterpret fields, which affects matching, upstream selection and plugin attachment.	Export all routes, validate them against the 3.x schema in a test environment, and run representative requests to compare results with 2.x.
Deployment mode notes	Traditional, decoupled and standalone modes differ in where configuration lives. Standalone mode reloads a YAML or JSON file from conf/ about every second, so a file-driven setup needs its own change control.	Confirm which mode you run today and whether the target design keeps it. Plan the etcd or file-based source of truth before the cutover.

Why etcd data is rebuilt instead of carried over

The 2.x to 3.x move is planned as a rebuild and verification of the gateway's configuration, not an in-place swap of the data store. In APISIX, etcd holds the configuration the gateway acts on: routes, upstreams, consumers, plugin configuration and plugin metadata. Because that data is what the 3.x data plane reads at startup and when it hot-loads changes, the team should treat the 2.x etcd contents as a source to export from, not as a store to keep running under a new version. Any object that does not load cleanly, or that loads with different meaning, changes how traffic is routed or authenticated.

Start by exporting the current configuration from the 2.x Admin API and keeping that export as the reference set. Load it into a non-production 3.x data plane built from the same configuration sources you intend to use in production. Then compare the results against the 2.x source before any traffic moves. Count each object type (routes, upstreams, consumers, plugin metadata) on both sides and investigate every difference. Next, send a fixed set of representative requests to both gateways and compare status codes, response headers and upstream selection for each sample route, including routes that use authentication and rate limiting. Record the checks and their results, since they form the evidence for the cutover decision.

Confirm in the 3.x upgrade guide which fields, endpoints and default values changed for each object type before you rely on a direct copy, because a configuration that loads without error can still behave differently. Also confirm how your chosen 3.x release handles sensitive fields in stored data, so that the export and any reference files are handled under your secrets policy.

How the deployment mode changes the upgrade work

In traditional mode, one APISIX deployment runs the data plane and control plane together, so the upgrade replaces the gateway nodes and their configuration path in the same change window. Client requests and Admin API calls are served by the same nodes, so both need checks after the move.

Client traffic on 9080: Confirm the gateway accepts requests on port 9080 and that TLS listeners, upstream selection and status codes match the pre-upgrade baseline.
Admin API on 9180: Confirm the Admin API answers on port 9180 and that scripts or pipelines calling it parse the 3.x responses correctly.
etcd data: Plan the etcd data rebuild for the 3.x line, and export routes, consumers and plugin configuration before cutover so you have a known-good copy.
Main configuration file: Reconcile the 2.x configuration file with the restructured 3.x layout before the new nodes start.
Node replacement: Drain connections from each node before it is replaced, and confirm health checks pass before traffic returns.

After the move, send a sample of known routes through port 9080 and confirm the responses match the exported baseline, then read the same routes through port 9180.

What to back up and inventory before the upgrade

Each card below produces an artifact you need before touching the 2.x gateway. Together they let you roll back if the upgrade fails and prove that routes, authentication and plugins behave the same on 3.x. Treat them as a checklist owned jointly by the platform team and the teams that depend on the gateway.

Full etcd snapshot and config export

Take an etcd snapshot of the 2.x cluster and export routes, upstreams, consumers, plugin configs and SSL objects through the Admin API. The snapshot is your rollback point, and the export is the input you will compare against after the etcd data is rebuilt for 3.x. Store both encrypted, outside the gateway cluster, and confirm you can restore them into a scratch etcd before you start. Ask your platform team who holds the restore procedure.

Custom plugin and runner inventory

List every custom Lua plugin and every plugin registered through a runner in Java, Go, Python or WebAssembly. For each one, record the APISIX version it was built against, the core APIs it calls, and the owner who can fix it. Custom code is the most common source of unplanned upgrade work, so this list sets the size of the test effort. Ask the plugin authors to confirm which core functions they use.

Authentication plugin and secret inventory

Inventory every route that uses openid-connect, jwt-auth or key-auth, including the identity provider settings, client secrets, signing keys and the consumers attached to each key. Record where each secret is stored and who rotates it. Authentication changes are where a 3.x upgrade most often breaks sign-in, so check the consumer records against the source of truth in your identity provider before cutover. Keep the list in your change record, not in the gateway.

Config files and deployment templates

Collect the config file, Helm values or Linux package settings that define each gateway node, including the static configuration and any environment overrides. The 3.x line restructures these files, so you need the current versions in version control to compare against the new layout. Note which deployment mode each environment uses: traditional, decoupled or standalone. Ask your team to confirm that the templates in Git match what is running in production.

Production-like test environment

Build a test environment that mirrors production topology, with a copy of the routes, plugins and consumers from your export, and with the same etcd layout and upstream services or stubs. Use it to run the upgrade, replay representative traffic and test rollback. Synthetic data is acceptable only if it exercises the same plugins and paths. Confirm with your architects which upstream services can be reached from this environment without touching live data.

Latency and error rate baselines

Capture request latency percentiles, upstream response times, and 4xx and 5xx error rates per route group over a period that includes normal peak load. Compare these figures after the upgrade on the test environment and again during the parallel cluster cutover. Without a baseline, a regression after upgrade is hard to separate from ordinary traffic changes. Ask your observability team which dashboards and alert rules you should reuse, and where the data is retained.

How to step through 2.15 and cut over to 3.x

This sequence moves an APISIX 2.x gateway to the 3.x line without changing production until the new cluster has passed testing. It ends with the 2.x cluster kept as a fallback until the observation period closes.

Freeze configuration and take backups
Stop route, plugin and consumer changes on the 2.x gateway for the length of the upgrade, and tell every team that publishes configuration through the Admin API or source control. Export the current routes, plugins, consumers and SSL objects, copy the etcd data and the configuration file, and store the copies outside the cluster. Exact export commands and file paths come from the APISIX 2.x to 3.x upgrade guide. Done when a restore has been rehearsed on a non-production copy and a named owner holds the freeze. Rollback point: the untouched 2.x cluster and these backups remain the fallback until cutover is closed.
Upgrade the test cluster to 2.15
Upgrade a copy of the production 2.x gateway to 2.15 in a test environment, matching production plugins, etcd version and deployment mode. Replay the production route and plugin set, then confirm that responses match expected results, that authentication behaves as before, and that logs and metrics still arrive. Record every warning the gateway writes during the upgrade, since these point to configuration fields that need attention before the 3.x work begins. Done when the test cluster serves the same routes as production with no unexpected status codes and the findings are documented. Rollback point: discard the test copy and keep production on its current 2.x version.
Build the 3.x parallel cluster
Stand up a separate 3.x cluster beside the 2.x gateway, on its own nodes and with its own etcd cluster, so that the existing etcd data stays untouched. Select the 3.x release you intend to run, confirm it against the APISIX downloads page, and follow the upgrade guide for the etcd data rebuild. In traditional mode, confirm that the Admin API answers on port 9180 and client traffic listens on port 9080. Done when both clusters are healthy and the 3.x gateway answers a test route. Rollback point: the 3.x cluster carries no live traffic yet, so it can be removed without affecting users.
Rebuild configuration for 3.x
Rewrite the exported 2.x configuration for the 3.x line, following the upgrade guide for config file restructuring, Admin API response and endpoint changes, and plugin and route field changes. Apply the result to the 3.x cluster through its Admin API or configuration files, and keep every change in source control so that each one has a reviewer. Compare the 3.x objects with the 2.x export item by item and document the reason for every difference. Done when each difference is explained and approved. Rollback point: the 3.x configuration can be regenerated from the 2.x export at any time, and production has not changed.
Run automated route and authentication tests
Run an automated suite against the 3.x cluster that covers every route, the expected status code and upstream response, and each authentication path in use, including API keys, tokens and OpenID Connect flows where they apply. Include negative cases such as missing credentials, expired tokens and disallowed methods, because these cases are where differences from 2.x behavior are easiest to miss. Store the results with the configuration version that was tested. Done when the suite passes on the exact configuration that will go live. Rollback point: a failing test stops progression, and cutover waits until the cause is fixed and the suite passes again.
Send shadow or limited traffic
Send a copy of production requests to the 3.x cluster, or route a small share of live traffic to it, using whichever traffic split your load balancer, DNS or upstream gateway supports. Compare responses, latency, error rates and logs with the 2.x gateway. Shadow requests must not trigger side effects in upstream systems, so confirm with service owners which write endpoints are excluded. Done when the comparison shows no unexplained differences and each known difference has an owner and a fix. Rollback point: remove the mirror or set the live share back to zero, and the 2.x cluster continues to serve all traffic.
Cut over traffic in a planned window
Move production traffic to the 3.x cluster in a window agreed with the business owners, with on-call engineers and the rollback procedure in place for the whole window. Shift traffic in stages through the mechanism your edge uses, and run the health tests and key dashboards after each stage before moving to the next. Keep the cutover record current, including times, stage results and who approved each step. Done when all client traffic is served by the 3.x cluster and the record is signed off. Rollback point: return traffic to the 2.x cluster through the same mechanism, which is why the 2.x cluster must stay in place.
Keep the 2.x cluster ready until observation ends
Keep the 2.x cluster running, with its configuration and etcd backups intact, until the observation period agreed before cutover has ended. During that period, monitor error rates, authentication failures, plugin logs and any dashboards that depend on metric labels, and record anything unexpected. Retain backups according to your own retention policy. Done when the observation period closes without open high-severity findings and the 2.x cluster is decommissioned under change control. Rollback point: until decommissioning, traffic can be returned to 2.x in the same way it was moved.

Testing and rollback for the Apache APISIX 2.x to 3.x upgrade

Test the 3.x cluster against the traffic your 2.x gateway serves before any client moves. Build the matrix from what the gateway actually does: route matching for every production URI, host and method combination, including catch-all and priority-sensitive routes; authentication flows for each consumer type, such as key-auth, jwt-auth or openid-connect sessions; and the behavior of each custom plugin you wrote or configured. Add the Admin API scripts and automation in your pipelines, since any job that creates, reads or updates routes must receive the same responses in 3.x. Include observability and log pipelines, confirming that metrics, traces and access logs still arrive with the labels your dashboards and alerts expect. Finally, check client-facing error responses, because status codes and error bodies that clients parse are where silent breakage often appears.

Run both clusters against the same recorded or mirrored requests and compare responses field by field. Capture status, headers, body shape, latency and upstream selection from each gateway, and store the differences with the test version so reviewers can separate intended changes from defects. Keep the 3.x test cluster on its own hosts with its own etcd, and restrict the Admin API, which listens on port 9180 in traditional mode according to the deployment modes documentation, to the test network. Expect some differences to be intended, such as changed defaults listed in the upgrade notes for each step. Confirm each one against the upgrade guide and sign it off in writing. Treat any unexplained difference as a blocker until your team has explained it.

Decide rollback triggers before the cutover window opens and write them down. Typical triggers include a rise in 5xx responses or latency on routes that passed testing, authentication failures for a consumer group, missing metrics or logs that alerting depends on, and Admin API automation that fails. Agree who may call a rollback and how long the team will watch the 3.x cluster after each traffic step. Switching back means moving DNS records or load balancer weights from the 3.x endpoint to the 2.x endpoint, so keep TTLs short enough for the move to take effect quickly and confirm that clients and intermediate caches respect them. The 2.x cluster, its hosts and its etcd snapshot must stay intact until the cutover is formally accepted, because a rollback is only possible while the 2.x gateway still holds its original configuration. Confirm the snapshot restore procedure with your own team before the window opens.

What makes a 2.x to 3.x upgrade take longer

This table compares the factors that most change the effort of moving an APISIX 2.x gateway to 3.x, and what each one means for planning. Read each row as a question to answer about your own estate before asking for a fixed-scope quote. The main takeaway is that route count alone rarely decides the effort; plugin types, automation that calls the Admin API and compliance evidence usually do.

Driver	Effect on effort	What to check
Number of routes and upstreams	Raises the volume of route exports to review, convert and retest, especially where routes share plugin configuration	Export current routes and upstreams from the Admin API, group them by shared plugin sets, and note which ones depend on 2.x field names
Number and type of custom plugins	Lua plugins written against 2.x internals need review line by line, while plugin runner code in Java, Go or Python depends on the runner version in use	List every custom plugin, its language, its dependencies on core modules, and whether it is still maintained by your team
Depth of authentication integration	Identity provider flows, token claims and consumer definitions each need retesting, and changed defaults can break sign-in without an obvious error	Map each route using key-auth, jwt-auth, openid-connect or LDAP, and confirm the claim, algorithm and TLS settings in use today
Admin API use by automation and CI pipelines	Scripts that rely on 2.x request or response shapes, endpoints or implicit defaults must be found and changed before cutover	Search pipelines and infrastructure code for Admin API calls, and confirm the response fields each script reads
Kubernetes ingress with the APISIX Ingress Controller	Controller versions, custom resource definitions and ingress annotations must line up with the gateway version, which adds a second moving part	Record the controller version, the resources it manages, and whether ingress manifests are generated or hand-written
Number of environments and clusters	Each environment repeats the test and promotion cycle, and drift between etcd clusters can make results differ between staging and production	Confirm how many clusters exist, whether they share etcd, and how configuration reaches each one
Traffic volume and change windows	Limits how long both versions can run side by side and how much rollback time exists during a cutover	Ask the business owners for allowed windows, peak periods and the traffic level that the parallel cluster must absorb
Compliance evidence the change must produce	Change records, test results, access reviews and logging evidence add work that runs alongside the technical upgrade	Confirm with your assessor or compliance lead which evidence the change must produce and where it will be stored

Questions teams ask before a 2.x to 3.x upgrade

How much does a 2.x to 3.x APISIX upgrade cost?

The cost depends on scope, not on a list price. The main drivers are the number of gateway nodes and clusters, how many routes, consumers and plugins need review, how many custom Lua or plugin-runner plugins must be ported, and how much testing your traffic requires. Identity integrations, such as openid-connect or jwt-auth flows, add review and test effort. Some costs are one-time (assessment, configuration conversion, testing, cutover), while others recur if you buy ongoing support or upgrades later. Ask a partner for a written scope that lists each component, who performs it, what is excluded, and which assumptions the quote depends on, including the test environment and change windows.

How long does an APISIX 2.x to 3.x upgrade take?

Duration depends on how much your gateway differs from a default setup and how quickly your organization can approve changes. The largest factors are the number of custom plugins, the volume of route and consumer data that must be converted, the number of environments (development, test, staging, production), and the change windows your operations team allows. Work that often takes the longest is validating authentication flows against your identity provider and proving that clients behave the same after cutover. The upgrade path also matters: the work includes stepping through 2.15 before moving to 3.x. Ask for a timeline with named milestones and gates, not a single end date.

Can our own team upgrade APISIX without a partner?

Yes, a capable internal team can do the upgrade, provided it has the skills and time for the work. You need people who understand APISIX configuration and Admin API use, etcd operations and backup, Lua or plugin-runner development for any custom plugins, and TLS and identity configuration. Someone must own the inventory of routes, plugins and consumers, and someone must design the parallel cluster and rollback steps. Many teams underestimate testing: regression tests for each route, authentication path and metric or log consumer are the bulk of the effort. A partner is useful when the team lacks these skills or capacity, or when it wants an independent review before production cutover.

What do we need to provide for the upgrade?

The work needs access and decisions from your side. Typically this includes read access to the current gateway configuration and etcd data, a test environment that resembles production, the ability to send representative traffic to it, and change windows for cutover and rollback. You also need named owners: one for identity and authentication (for example, your identity provider, such as Keycloak, Entra ID or Okta, if openid-connect or jwt-auth is in use), one for each custom plugin, one for observability and logging pipelines, and one for approval of cutover. Ask the partner to list these requirements in the written scope so that gaps are visible before work starts.

Can 2.x and 3.x APISIX run side by side during cutover?

A parallel cluster is the usual way to limit risk, but the details must be confirmed for your version path. APISIX supports traditional, decoupled and standalone deployment modes, and each has different ports and data stores: in traditional mode the gateway listens on port 9080 for client traffic and port 9180 for the Admin API. Plan the 3.x cluster on separate nodes and, unless the upgrade guide says otherwise, a separate etcd cluster, so that changes made to the old gateway do not reach the new one unexpectedly. Routing traffic gradually from the old to the new cluster at a load balancer or DNS layer gives you a rollback path. Confirm the data migration steps and any synchronization needs in the upgrade guide before you choose the design.

Does the upgrade produce audit evidence for compliance?

The upgrade itself produces evidence you can use, but it does not produce an audit opinion. Evidence typically includes the pre-upgrade inventory of routes, plugins and consumers, configuration kept in version control, a documented change plan, test results for authentication, TLS and rate limits, cutover and rollback records, and a post-upgrade review of logging and access control settings. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue audit reports and attestations. Ask the partner to name which evidence it will deliver, in what format, and who signs off on each item, so your compliance lead can map it to your control framework.

Which configuration and plugin changes are most likely to break traffic?

The most common breakage comes from changes to how configuration is stored and read, and from plugin behavior that changed between versions. Check the config file layout, Admin API request and response shapes, and any route or plugin fields that your automation writes. Authentication plugins need particular care, because a change in claim checks, token handling or TLS verification can reject traffic that previously passed. Custom plugins must be retested against the 3.x plugin interface. Run each route against the new gateway in a test environment, compare responses and logs with the old gateway, and keep a rollback option until the new cluster has carried production traffic for an agreed period. The upgrade guide lists the specific changes to check.

How DeployOpen scopes, delivers and supports the upgrade

DeployOpen plans and carries out Apache APISIX 2.x to 3.x upgrades inside your own infrastructure, starting from a written scope. The work covers the 2.15 step, etcd data rebuilding, configuration file changes, Admin API and plugin field changes, and a parallel-cluster cutover with a rollback path.

How we scope

Inventory every APISIX 2.x node, plugin, route, consumer and custom plugin before agreeing dates or deliverables.
Confirm the deployment mode (traditional, decoupled or standalone) and map each 3.x breaking change to the configuration you actually run.
Agree the written scope, deliverables and timeline in writing before any change is made, since most engagements are fixed-scope.

How we build

Stand up a parallel 3.x cluster in your environment, leaving the 2.x gateway serving traffic until cutover is approved.
Step through 2.15 first, then migrate etcd data and rewrite configuration files and Admin API calls against the 3.x schema.
Test routes, authentication flows, custom plugins and dashboards against the 3.x behavior, and record each result as evidence.

How we hand over

Document the new configuration layout, Admin API usage, plugin field changes and the cutover and rollback runbook.
Walk your platform and security engineers through the change log so they can operate the 3.x gateway after handover.
Deliver test results, known gaps and open decisions in writing so your team can confirm each item before go-live.

How we support

Offer ongoing support, upgrades and continuous testing for the 3.x line as a retainer, scoped separately from the upgrade.
Plan later 3.x upgrade steps, such as moving from 3.2 LTS or from 3.10 onward, as separate written scopes.
Ask your own team to confirm release notes and vendor support terms for any version you plan to run long term.

Apache APISIX 2.x to 3.x upgrade