Migrate from Apigee to Apache APISIX

Migrate from Apigee to Apache APISIX: what the move involves

The move from Apigee to Apache APISIX is a gateway, configuration and traffic cutover that a platform team and an implementation partner usually run together. The trigger is often a renewal, a data residency requirement, or the end of life date of June 30, 2027 for Apigee Edge for Private Cloud 4.53.01, after which Apigee stops providing security updates for that line. Your platform team owns the target runtime, the etcd cluster, the identity integration and the on-call model, while a partner typically carries the proxy inventory, policy translation, test harnesses and cutover runbooks. Apache APISIX is licensed under Apache-2.0 and built on NGINX and etcd, so the team inherits both the gateway and the configuration store it must operate.

Effort and risk depend less on the gateway than on what sits behind it. Count the proxies, shared flows and target servers first, then flag custom JavaScript or Java callouts, Key Value Map lookups, and any developer portal workflows such as app registration and key approval, since those are not covered by a gateway swap. Ask your Apigee administrator which environments, revisions and deployment groups are live, and confirm with the APISIX vendor documentation which Apigee policies have a built-in plugin equivalent. Plan for the work to recur after cutover, because routes, upstreams and plugin versions need the same review and patching discipline as application code.

Start the work by exporting proxy bundles from Apigee and treating them as the source of truth for the translation, as described in the sibling export guide. Then decide the cutover pattern: run APISIX in parallel for one environment, shift a small share of traffic through the load balancer, and keep a rollback path to Apigee until error rates and latency match. Before any production traffic moves, confirm the APISIX deployment mode you need, whether traditional, decoupled or standalone, and what the Admin API exposure looks like in your network. A written scope that lists proxies, policies, portal features and environments in the first milestone is the clearest protection against a cutover that stalls halfway.

Which Apigee capabilities map cleanly to APISIX routes, upstreams and plugins

This table compares common Apigee constructs with their closest Apache APISIX equivalents and marks each as clean, needs rework or gap. Use it to scope the migration before exporting proxy bundles, and treat every gap as a item to confirm with a proof of concept in your own environment.

Apigee capability	Apache APISIX equivalent	Migration status
Proxies and base paths	Routes matched on URI, host and methods, grouped into services where shared settings apply	Clean. Rebuild each proxy's base path and methods as route definitions and check path precedence.
Target endpoints	Upstreams with nodes, load balancing type and health checks	Clean. Confirm health check settings and any TLS or mTLS requirements per target.
Shared flows and policies	Plugins attached to routes, services or plugin configs, with custom logic where no built-in plugin fits	Needs rework. APISIX has more than 100 built-in plugins, but flow logic such as conditional steps must be re-expressed.
Custom Apigee policies (JavaScript, Java callouts, Python)	Custom plugins in Lua, or through plugin runners in Java, Go and Python, or WebAssembly	Needs rework. Each custom policy needs a new plugin, a test suite and a performance check.
OAuth and API key validation	openid-connect plugin for Keycloak, Auth0, Microsoft Entra ID, Google and Okta, plus key authentication plugins	Needs rework. Confirm token formats, scopes and key rotation against your identity provider.
Quotas and spike arrest	Traffic control plugins for rate limiting and request limits, with counters held in the gateway	Needs rework. Quota periods and counter sharing across nodes must be designed and tested.
Logging and API analytics	Logging plugins feeding external collectors, with metrics for Prometheus	Gap to confirm. Business reporting and dashboards need to be rebuilt outside the gateway.
Developer portal, monetization	Not part of the gateway. Confirm whether a separate portal or billing system is required	Gap to confirm. Do not assume parity with Apigee's portal or monetization features.

What to export from Apigee first and what to rebuild

Some Apigee assets can be exported as files and reloaded, while others must be recreated by hand in APISIX. Sort every asset into one of those two groups before any cutover plan is written. The cards below cover what to export first and which parts of the gateway estate need to be rebuilt and verified in the target design.

Export proxy revisions as bundles

Each API proxy revision can be downloaded as a bundle zip file through the Apigee management API, which gives you the policy XML, JavaScript, Java callouts and proxy endpoint definitions in one artifact. The calling identity needs read permission on the organization and environment, so confirm that role with your Apigee administrator before the export starts. Use apigeecli for proxies and products in batches, then follow the dedicated export page for the full procedure. Keep the bundles in version control so each revision can be traced back to the APISIX configuration it produced.

Rebuild the route and upstream inventory

Apigee proxies bind a base path, target endpoints and flow conditions. In APISIX these become routes, upstreams and plugin configuration, so write a table that maps every proxy, basepath and target to its new route ID and upstream node list. Check path matching rules closely, because a proxy that matched by prefix may need an explicit URI pattern in the new gateway. Confirm load balancing and health check behavior against the original target server definitions before you assume parity.

Consumer credentials and rotation

Apigee app keys and secrets are not portable by default. Developer apps, consumer keys and secrets live in Apigee's data store, and the new gateway needs its own consumer objects and credential plugins. Decide whether consumers get new keys, keep existing keys through an import step you test in a non-production environment, or run both sets during a transition window. Document rotation ownership and the date each old key stops working, and confirm the design with the consumers who depend on it.

Identity provider connections

Apigee OAuth policies and any external token validation must be recreated with APISIX plugins. The openid-connect plugin supports Keycloak, Auth0, Microsoft Entra ID, Google and Okta and covers authorization code, client credentials, token introspection and PKCE flows. Re-register each client with the identity provider, record which redirect URIs and scopes change, and test token validation against every flow that Apigee currently serves.

Certificates and TLS

Inventory every certificate that Apigee uses for virtual hosts, northbound TLS, mutual TLS to backends and truststores. Apigee keystores and truststores do not move as-is, so import the private keys through a controlled process and store them in your secrets manager. Confirm certificate chains, expiry dates and the TLS versions and cipher suites each consumer requires, then test the APISIX SSL objects before any DNS change.

Gaps to confirm in the target design

Some Apigee items, such as analytics dashboards, monetization and developer portal content, do not map to gateway objects at all. List them separately so they are not forgotten. Confirm with your architects which of these will be replaced by other tools, which will be retired, and who owns each decision, before you commit to a cutover date.

Migration sequence from inventory to decommission

This sequence moves Apigee traffic to Apache APISIX in controlled stages, so each environment is proven, reversible and documented before Apigee is switched off. It ends with a decommission record that your auditors and operators can check.

Inventory proxies, shared flows, policies and consumers
Your API platform owner and an Apigee administrator list every API proxy, shared flow, target server, environment group, API product, developer app and key in each Apigee environment. For each proxy, record which policies it calls (for example, verify API key, quota, OAuth, JavaScript, service callout) and which downstream systems and certificates it depends on. Export proxy revisions as bundle zip files, following the export guidance for proxies and related configuration. The output is a signed-off inventory spreadsheet with one row per proxy and a policy-to-APISIX mapping column, plus a list of consumers who must be told about any change. The step is done when every proxy in production has a row and a named owner.
Classify policies and flag custom plugin work
Your platform engineers review each policy type found in the inventory against APISIX's built-in plugins, which cover authentication, security, traffic control and observability. Policies with a direct equivalent, such as key authentication or rate limiting, become plugin configuration. Scripted policies, custom Java callouts or Apigee-specific features with no clear match are marked for a custom plugin, written in Lua or through a plugin runner in Java, Go or Python, or WebAssembly. Confirm the behavior of each mapped plugin against the APISIX plugin documentation in your own test environment, not from the mapping alone. The output is a classified backlog in which every item is marked as mapped, custom or unsupported, and each custom item has an estimate agreed by engineering. The step is done when no policy remains unclassified.
Pilot one low-risk API in non-production
Choose one read-only, low-traffic API with a simple policy chain and deploy it to a non-production APISIX environment. Pick a deployment mode against your team's skills: traditional mode runs the control plane with etcd and uses port 9080 for client traffic and port 9180 for the Admin API by default, decoupled mode separates the data plane from the control plane while sharing one etcd cluster, and standalone mode removes etcd and loads routes from conf/apisix.yaml or conf/apisix.json, which APISIX checks every second for changes. Teams without etcd operations experience usually start with standalone mode for a pilot, while teams that run etcd well may prefer traditional or decoupled mode. Replay representative requests and compare responses with Apigee. The output is a documented pilot with the chosen mode, route definitions in version control, and a pass record for functional tests.
Run Apigee and APISIX in parallel
Keep the Apigee proxy live and route a small share of production traffic through APISIX, either by mirroring requests or by splitting them at the load balancer or DNS layer. Capture latency at the 50th and 95th percentile, error rates by status code, authentication outcomes and rate-limit rejections on both gateways over the same window. Investigate every difference, including header changes, response caching and retry behavior, and record the cause. The output is a comparison report signed by the API owner and the security lead, listing each accepted difference and each fix. The step is complete when the report shows no unexplained behavior differences for the pilot API.
Cut over environment by environment with rollback
Move one environment at a time, starting with development and staging, then production, and move one API group at a time within each environment. Use DNS weighting or gateway-level switching so that restoring Apigee takes a configuration change, not a redeploy. Before each switch, confirm that the Apigee route and its certificates remain intact and that the rollback runbook has been rehearsed by the operators on call. Monitor error rates and consumer complaints after each switch and hold the step until the agreed checks pass. The output is a cutover log per environment with timestamps, the rollback tested, and the owner who approved each switch. The step is done when production runs on APISIX and Apigee receives no live traffic for the migrated APIs.
Confirm retained logs and decommission Apigee
Before any Apigee component is removed, confirm with your compliance lead which logs, analytics exports, audit records and proxy bundles must be retained under your policies, and store them in your own archive. Verify that every proxy bundle exported in the first phase is stored with its revision number, and that the APISIX configuration in version control matches what is running. Then disable Apigee proxies, revoke developer keys in line with consumer notice, and remove the Apigee environments and any Apigee-managed or hybrid runtime components you operate. Ask your Apigee contract owner which obligations, such as notice periods or data return requests, apply to your agreement. The output is a decommission record listing each retained artifact, its location and its owner. The step is done when that record is approved and Apigee has no active traffic or open records that depend on it.

What drives migration cost and duration

This table lists the factors that move the effort of an Apigee to APISIX migration, why each one matters, and how to reduce it. Read it before requesting a quote, because the scope drivers below determine the fixed-scope proposal far more than the gateway license, which is zero for Apache APISIX.

Driver	Why it changes cost or effort	How to keep it down
Number and complexity of proxies	Each proxy needs its flows, conditional steps, target endpoints and fault handling mapped to APISIX routes, upstreams and plugins. Proxies with many branches take longer to verify than simple pass-through proxies.	Inventory every proxy revision first, retire unused proxies, and group similar proxies into shared route templates before mapping begins.
Custom JavaScript and Java callouts	Apigee JavaScript and Java callout policies have no direct APISIX equivalent and must be rewritten as Lua plugins or as plugin runner code in Java, Go or Python, or as WebAssembly modules.	Count these policies per proxy, prefer built-in plugins where behavior matches, and consolidate duplicated scripts into one shared plugin.
ServiceCallout and external lookups	Policies that call out to other services during a request need a custom plugin or an upstream redesign, and their timeout and failure behavior must be tested under load.	Document the purpose of each callout and check whether the logic can move to the backend service or to an existing auth plugin.
Number of environments and regions	Each Apigee environment and region becomes a separate APISIX deployment or configuration set, so testing, secrets and certificate handling repeat per environment.	Use one configuration repository with per-environment variables and promote the same artifacts through test, staging and production.
Identity integration	Apigee OAuth, API key and JWT verification must be reproduced with APISIX authentication plugins, including the openid-connect plugin for identity providers such as Keycloak, Microsoft Entra ID or Okta.	Confirm which identity provider and grant types each API uses, then test token validation, introspection and PKCE flows once per pattern rather than per API.
Developer portal and analytics scope	APISIX does not include a developer portal or business analytics, so the portal, app registration, key management and reporting are separate build and run items.	Decide early whether the portal is in scope, reuse an existing portal or catalog, and limit the first release to operational metrics and logging.
Traffic volume and cutover risk tolerance	Higher traffic and stricter tolerance for errors require parallel running, canary routing, rollback runbooks and load testing, which add test and operations effort.	Start with low-risk internal APIs, route a small share of traffic to APISIX, and keep Apigee live until error and latency results match.
Team skills in Lua, Go or Java plugin runners	Teams without Lua experience face a learning curve for custom plugins and etcd-backed configuration, which lengthens build and review cycles.	Ask the partner whether plugin development, code review and handover are included, and plan a skills transfer before the migration closes.
One-time versus recurring costs	One-time items include discovery, mapping, plugin development, portal build, testing and cutover. Recurring items include infrastructure, etcd operations, upgrades, support contracts and the staff who run the platform.	Request a quote that separates one-time work from recurring run costs, and ask which items are optional or included in a retainer.

What usually goes wrong and how to prevent it

Most failed Apigee to APISIX cutovers trace back to a few gaps that surface late: policies with no direct plugin equivalent, state that never made it across, and environments that drifted apart. Each card below names the risk and the step that prevents it.

Policies without a plugin match

Apigee policies such as JavaScript callouts, Java callouts, certain message transformations and custom Service Callout logic may not map one to one onto an APISIX plugin. Inventory every policy in every shared flow and proxy revision before design starts, mark each as mapped, rewritten or needs a custom plugin, and build those custom plugins in Lua, a plugin runner, or WebAssembly before the first environment is scheduled for cutover.

Consumer keys and quota state

API keys, app credentials, product entitlements and the current quota counters live in Apigee, not in the proxy bundle. Export consumer records and their secrets through your own process, then decide whether consumers rotate keys or keep them. Without this step, partner applications fail on the first request and rate limits reset to zero, which can briefly open traffic beyond agreed limits.

Portal and analytics assumed covered

Teams often assume the Apigee developer portal, API Analytics and monetization reports will be replaced automatically by the gateway. APISIX provides logging and metrics plugins, not a portal or business reporting. List every portal page, report and billing feed your stakeholders use, assign an owner for each replacement, and confirm the gap before the cutover date is set.

Configuration drift between environments

Routes, upstreams and plugin settings can differ between dev, test and production when they are edited by hand after import. Store APISIX configuration as code, choose a deployment mode deliberately (traditional with etcd, decoupled, or standalone with a YAML file), and promote the same artifact through each environment. In standalone mode, a file change is picked up within a second, so review changes as you would any production code change.

TLS and certificate gaps at cutover

Certificates, private keys, SNI bindings and mutual TLS trust stores must exist on the APISIX side before DNS or load balancer traffic moves. Check certificate chains, expiry dates and client certificate validation against each Apigee virtual host, and confirm that backends accept the gateway's client certificate. A missing intermediate certificate often shows up only in a subset of client libraries, so test with the clients your partners actually use.

Skipping the rollback test

A cutover plan without a tested route back to Apigee leaves the team guessing under pressure. Before each environment moves, shift a small share of traffic through a weighted route or DNS change, confirm error rates and latency, and rehearse the reverse change with the same runbook. Keep the Apigee environment running in read-only mode until the rollback window you agree with the business closes.

How the move differs by estate size and starting point

A small estate is usually a handful of API proxies, a few shared flows and one or two environments on Apigee X. In this case the migration is mostly a rewrite exercise that can be done by one platform team in a short series of cut-overs. Most of the effort goes into translating each proxy's flow logic into APISIX routes, upstreams and plugins, and into testing each consumer rather than building shared infrastructure.

Inventory first: List every proxy, its revisions, target endpoints, shared flows and the consumers that call it, then decide which ones move in the first wave.
Start with stateless proxies: Proxies that only route and transform requests are the quickest to map to APISIX routes and plugins.
Plan a single APISIX deployment: Traditional or standalone mode is often enough for a small set of routes, so confirm which mode fits your operating model before you build.
Keep the Apigee environment running: Leave the Apigee proxies active until each consumer has been verified against the new gateway.
Rebuild, do not copy, the logic: Custom JavaScript and Java callouts need a decision on whether they become APISIX plugins or move to the backend.

Before you start, confirm with your team which consumers hold long-lived credentials and how quickly you can rotate them.

Questions teams ask before moving from Apigee to APISIX

How much effort does moving from Apigee to APISIX take?

The effort depends mostly on how many proxies, shared flows and custom policies you run, and how many of them use Apigee features that APISIX handles through a different mechanism. A portfolio of simple routing and key-validation proxies is a much smaller job than one with heavy JavaScript, Java callouts or stateful quota logic. Costs fall into four groups: the internal time spent inventorying and exporting proxy bundles, the engineering time to rebuild routes, upstreams and plugins, the testing and security review of each environment, and the people who operate the gateway afterward. APISIX itself is Apache-2.0 licensed, so the license line is zero, but the infrastructure, implementation and support lines are real. Ask any implementation partner for a fixed-scope quote built from a proxy-by-proxy inventory, with the custom plugin work priced separately.

How long does an Apigee to APISIX migration usually take?

The timeline is set by the number of environments, the count of Apigee policies that need custom plugins, your change-approval cycle and how much traffic validation you require before cutover. Teams usually finish the inventory and mapping first, then build and test APISIX in a non-production environment, then move production one environment or API group at a time. Your own change windows and security sign-offs often take longer than the technical work. We do not publish durations. Ask for a written schedule that lists each phase, the environments it covers and the client decisions it depends on, and confirm how that schedule changes if Apigee contracts or Edge for Private Cloud support dates affect your plan.

What does the client team need to provide during the migration?

The client team must provide access to the Apigee organization and environments, the IAM permissions needed to download proxy revisions, and a named owner for each API and its consumers. Engineers should be ready to explain undocumented behavior in shared flows, backend authentication details, and the rate limits and quotas that partners depend on. Security and operations teams need to supply the identity provider configuration for OpenID Connect, the target hosting model for APISIX (traditional, decoupled or standalone), and the logging and monitoring destinations. Confirm these items with your Apigee administrator before work starts, because missing permissions are a common cause of delay.

Can our in-house team migrate from Apigee to APISIX alone?

An in-house team can do it alone if it already runs Kubernetes or Linux infrastructure, has engineers comfortable with NGINX-based gateways and etcd, and has capacity to learn the APISIX Admin API and plugin model. The harder parts are usually mapping Apigee policies that have no direct equivalent, writing and maintaining custom plugins in Lua or a supported plugin runner, and running the gateway after cutover. APISIX supports the traditional, decoupled and standalone deployment modes, so the team must also choose one and understand its operational trade-offs. Decide on a skills assessment first. A partner can cover the parts your team lacks under a written scope, or review your design before you commit.

Does APISIX replace Apigee analytics and the developer portal?

Not out of the box. APISIX covers gateway functions such as authentication, traffic control and observability plugins, and its documentation lists more than 100 built-in plugins across those areas. Apigee's API Analytics add-on, its developer portal and its monetization features are separate products, so they need their own replacements. For traffic and latency reporting, you can feed APISIX logs and metrics into a self-hosted stack such as Prometheus and Grafana or ClickHouse. For documentation, app registration and key approval, you will need a developer portal chosen separately, such as one from WSO2 API Manager, Gravitee or a Backstage API catalog. Confirm which business reports and portal workflows your partners rely on before you accept the scope.

Is a parallel run needed when cutting over from Apigee?

A parallel run is not strictly required, but it is the safest pattern for production APIs with external consumers. In a parallel run, APISIX serves a copy of the traffic or a subset of consumers while Apigee remains the source of truth, so you can compare responses, latency and error rates before switching DNS or client configuration. The length of the run and the traffic split are decisions for your change board, based on your risk tolerance and rollback plan. Keep Apigee available until the rollback path is tested and every environment has been signed off. Ask your implementation partner to document the cutover runbook and the criteria that trigger a rollback.

How DeployOpen scopes and runs the Apigee to APISIX migration

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, and an Apigee to Apache APISIX move follows the same pattern. The work runs in your cloud accounts, data centers or air-gapped network, so the APISIX gateway nodes, the etcd cluster (in traditional or decoupled mode), the Admin API on port 9180 and the client traffic on port 9080 all sit where your security team already controls access. Before any engagement starts, confirm with us which deployment mode fits your environment, since traditional, decoupled and standalone modes differ in where configuration lives and how it is distributed.

Most engagements are fixed-scope. Scope, deliverables and timelines are agreed in writing before work starts, and that written scope is the basis for a quote. DeployOpen does not publish a price list, so the quote follows from the inventory of proxies, shared flows, target servers, environments, custom Apigee policies and the number of portal or identity integrations you need. Ask for the scope document to list which proxy bundles are exported, which policies map to standard APISIX plugins, which need a custom plugin in Lua or a plugin runner, and which are excluded. Also confirm who owns the cutover calendar and rollback decisions on your side.

Ongoing support, upgrades and continuous testing are available as retainers, which suits teams that will keep running APISIX after the cutover. A retainer can cover APISIX version upgrades, plugin maintenance, etcd operations, backup and restore testing and security testing of the gateway. Check with the APISIX project which releases your team should target, since the downloads page does not mark any release as long-term support. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications; your independent auditor or certification body makes that determination.

Migrate from Apigee to Apache APISIX