When running APISIX without etcd on Kubernetes makes sense
API-driven standalone mode with the APISIX Ingress Controller 2.x removes etcd from the Kubernetes deployment, but the trade-off is that the controller, not the gateway's own store, becomes the source of truth for configuration. If your platform team wants APISIX on Kubernetes and does not want to operate a separate etcd cluster with its own backups, quorum and upgrades, this mode is the option to evaluate. If you need the gateway to accept direct, persistent changes through its Admin API, the etcd-backed model is the better fit, and you should decide that before the design is locked.
The APISIX deployment modes documentation describes API-driven standalone mode as keeping rules in memory, updated through PUT /apisix/admin/configs, and states that it is intended for the Ingress Controller and ADC. The APISIX Ingress Controller overview says the controller supports this mode with APISIX 3.13 or later and recommends 3.13 for its 2.0.0 and 2.1.0 releases. That version floor is a hard gate: confirm the gateway image you plan to run is 3.13 or later before you write any manifests, and check the current controller release notes for the version pairing that applies to your chosen release.
Because configuration lives in memory, a gateway pod that restarts depends on the controller to push its full configuration again. Treat the controller's health, its RBAC access to the Kubernetes resources it reads, and its restart behavior as part of the gateway's availability design. Ask your APISIX contact to confirm how the controller behaves during a controller outage and how long a restarted gateway waits for a full sync before serving traffic, and plan your readiness probes and rollout strategy around the answer.
Choosing between etcd, file-driven standalone and API-driven standalone
In traditional mode, APISIX runs the data plane and control plane together, and both read and write configuration through an etcd cluster. In decoupled mode, the data plane and control plane are split but still share one etcd cluster. In both cases, configuration is stored centrally and the gateway picks up changes from etcd, so the Admin API on port 9180 is the normal way to change routes and plugins. Recovery depends on the etcd cluster itself, which means you also own its backup, upgrades and quorum.
- Delivery path: Admin API calls write to etcd, and gateway nodes read the change from it.
- Who edits: Administrators or tooling calling the Admin API, with changes persisted centrally.
- Recovery: Restore etcd data from its backups, and plan for the etcd cluster as a separate system.
- Operating cost: You run and monitor a stateful cluster in addition to the gateway.
- Port exposure: Admin API on port 9180 must be restricted to trusted administrators.
Confirm with your team which etcd cluster version and topology your chosen APISIX release expects, and who holds responsibility for etcd backups.
In file-driven standalone mode, APISIX has no etcd. It reads its rules from conf/apisix.yaml or conf/apisix.json and checks that file for changes every second, hot-reloading without a restart. The file is the single source of configuration, so the same file can be stored in Git and delivered by a pipeline. Recovery means restoring the file from version control or your artifact store, because the gateway holds no other copy of the configuration.
- Delivery path: The file on the node changes, and APISIX reloads it within about one second of the check.
- Who edits: Whoever changes the file, usually a pipeline run from Git.
- Recovery: Redeploy the last known good file, which works well only if the file is versioned.
- Node consistency: Each node reads its own copy, so your delivery process must put the same file on every node.
- Admin API: Changes made through the Admin API are not the normal path in this mode.
Confirm the file format and the #END marker requirements for your version in the deployment modes documentation, and check how your delivery tool detects and reports a failed reload.
In API-driven standalone mode, APISIX keeps configuration in memory and accepts updates through PUT /apisix/admin/configs. The deployment modes documentation says this mode is intended for the Ingress Controller and ADC. The configuration is not written to etcd, so it is not stored durably by APISIX itself. The controller or tool that pushes the configuration becomes the place where the desired state lives, and recovery depends on that source being intact.
- Delivery path: A client sends the full configuration to the Admin API, which holds it in memory.
- Who edits: The Ingress Controller or ADC, not administrators making manual changes.
- Recovery: After a restart, the configuration must be pushed again from its source of truth.
- Manual changes: Direct edits can be overwritten when the controller next performs a full sync.
- Version dependency: Check that your chosen Ingress Controller release supports this mode with the APISIX version you run.
Confirm with the vendor documentation how a restarted gateway receives its configuration, and test the full-sync behavior before relying on it in production.
Configuration options and when each fits
This table compares the three configuration sources a team weighs for APISIX on Kubernetes: API-driven standalone with the Ingress Controller, file-driven standalone, and keeping etcd. Read each row against your own change process, since the main takeaway is that the source of truth decides who is allowed to edit the running gateway.
| Option | Configuration source | Where edits are made | Admin API port use | Operational fit |
|---|---|---|---|---|
| API-driven standalone with the Ingress Controller | Kubernetes resources translated by the controller, held in APISIX memory | Kubernetes manifests such as Ingress, Gateway API and APISIX CRDs | Controller pushes via PUT /apisix/admin/configs; no etcd to run | Fits clusters that want no etcd and where Git-managed Kubernetes objects are the only change path |
| File-driven standalone | YAML or JSON file, conf/apisix.yaml or conf/apisix.json | The file itself, typically delivered through your GitOps pipeline | Not used for configuration delivery in this model | Fits VM or container gateways with a simple static routing set and a file-based release process |
| Traditional or decoupled mode with etcd | Routes and plugins stored in the shared etcd cluster | Admin API or tooling that writes to etcd, plus Kubernetes resources via the controller | Admin API listens on port 9180 in traditional mode | Fits teams already running etcd with backups, mTLS and upgrades in place, and who need the Admin API for direct edits |
| Manual Admin API edits in standalone mode | Whatever was last written through the Admin API | Direct API calls by operators | Admin API use is possible but not the intended path with the Ingress Controller | Confirm with the vendor docs before relying on it, because the controller overwrites manual changes on the next full sync |
| Change audit and rollback | Git history for files and manifests; etcd revisions for the etcd option | Pull requests, manifest reviews or etcd revision tooling | Depends on option chosen | Confirm how your audit evidence is produced for each option before choosing |
| Failure handling when the config source is unavailable | Last loaded config held by the gateway process in each option | Not applicable to edits | Depends on option chosen | Test restart and reschedule behavior in a staging cluster and record the result |
How to set up standalone mode on Kubernetes
This sequence takes a cluster from a planned APISIX version and Ingress Controller release line to a working API-driven standalone data plane, with each step closed by a check you can run. It also confirms that the controller, not manual Admin API edits, owns the gateway configuration.
Confirm the APISIX and controller versions
Your platform team confirms that the target APISIX release is 3.13 or later, since the Ingress Controller supports API-driven standalone mode only from that version, and selects the Ingress Controller 2.x release line. Check the release notes and compatibility statements for the exact pairing you plan to run, because the researched facts name 3.13 as the recommended version without giving a full compatibility matrix. Record both versions in your change request. Done when the versions are written down and the release notes have been read by the owner of the upgrade path.
Review the standalone model before installing
Before any install, the team reads how API-driven standalone mode differs from etcd: rules are held in memory, changes arrive through the Admin API configuration endpoint, and the controller pushes full state. Decide who owns the Kubernetes manifests and who may write to the Admin API, since the controller will overwrite manual changes. Capture these decisions in a short runbook. Done when the owners of Kubernetes objects, gateway policy and emergency changes are named.
Install the controller with API-driven standalone enabled
The platform engineer installs the APISIX Ingress Controller 2.x and the APISIX data plane through the official Helm chart or your chosen packaging, setting the deployment to API-driven standalone mode rather than the etcd-backed mode. Confirm the chart and image values against the version you recorded in the first step. Check that the controller and gateway pods reach Running and that the Admin API port is reachable only from inside the cluster. Done when both workloads are healthy and no etcd deployment is created.
Create GatewayProxy to connect the data plane
The engineer creates a GatewayProxy resource that tells the controller where the APISIX data plane's Admin API is and which credentials to use. Store the Admin API key in a Kubernetes Secret rather than in the manifest, and restrict who can read that Secret using least-privilege RBAC. Then reference the GatewayProxy from your GatewayClass or ingress class. Done when the controller logs show a successful connection to the data plane and the GatewayProxy status reports ready.
Map Ingress or Gateway API resources
The application team defines routes using Kubernetes Ingress v1, Gateway API resources, or APISIX custom resources where plugin-rich routes are needed. The controller translates these into APISIX configuration and pushes it to the data plane in memory. Apply one test route per resource type, then send a request through the gateway address and confirm the upstream response. Done when each test route returns the expected status code from the upstream and the controller reports the resource as accepted.
Confirm the data plane serves the mapped routes
Before testing overwrite behavior, the team checks that the rules in memory match what the cluster declares. Compare a sample of routes through the gateway with the Kubernetes objects, and confirm that restarting a gateway pod results in the controller reloading its configuration, which you should verify in a non-production cluster first. Record the restart and reload behavior in your runbook. Done when the test routes survive the controlled restart and the team understands what state is lost on pod replacement.
Verify that manual Admin API changes are overwritten
The operator makes a deliberate, labeled test change to a route through the Admin API, such as altering a response header on a test route only, and then waits for the controller's next full sync. Confirm that the change disappears and the route returns to the state declared in Kubernetes. Repeat the check if you rely on a sync interval, and note what triggers a full sync in your version. Done when the manual change is gone and the team agrees that all permanent changes must go through Kubernetes objects.
How full sync changes what you can edit by hand
In APISIX Ingress Controller 2.0 and later, the controller is the source of truth for the gateway's configuration, so any change made directly through the Admin API is overwritten on the next full sync. Teams used to patching a running gateway during an incident need to treat that habit as a risk in this mode. The controller also removed mock-etcd mode and the ApisixClusterConfig CRD, so global behavior that once lived in ApisixClusterConfig now belongs in ApisixGlobalRule, and the data plane connects through a GatewayProxy resource. Before cutover, inventory every place where your team has changed routes, plugins, consumers or global settings by hand and decide which of them must move into Kubernetes manifests.
Everything that used to be an operator edit needs a home in version control: ApisixRoute, ApisixConsumer, ApisixGlobalRule, Ingress or Gateway API resources, and the GatewayProxy settings that hold the Admin API connection. Secrets such as consumer credentials and plugin keys should come from Kubernetes Secrets or an external store rather than from a one-off Admin API call, and you should confirm how your chosen secret handling flows into the controller before go-live. Once these objects are the only inputs, a manual change in the gateway is a drift signal to investigate, not a fix to keep.
Confirm in testing what happens to the in-memory configuration when a gateway pod restarts. The API-driven mode keeps rules in memory, so the gateway must receive a full sync from the controller before it can serve the expected routes again. Measure how long a restarted replica takes to become ready in your environment, whether traffic is held or fails during that window, and whether the readiness probe reflects a fully loaded configuration. Ask your vendor or partner to document this behavior for your chosen controller and APISIX versions, and test it with a rolling restart and a node drain before production traffic depends on it.
What you lose compared with etcd
Standalone mode removes the etcd cluster from the gateway's control path, and the trade-offs show up in daily operations. These cards cover what changes for history, change control, recovery and tooling, so you can plan each one before you remove etcd from production.
No etcd revision history
In API-driven standalone mode, rules live only in the gateway's memory and are replaced through PUT /apisix/admin/configs, so there is no etcd store to query for earlier versions. Confirm where your change history will come from, such as Git, your CI pipeline or cluster audit logs. Then test how you would restore a previous configuration.
Changes flow through Kubernetes
Routes, plugins and consumers must be declared as Kubernetes resources, either Ingress v1, Gateway API resources or APISIX custom resources, because the Ingress Controller translates them into APISIX configuration. Teams used to calling the Admin API directly need to move that work into manifests, review it in pull requests and apply it through the same pipeline as other cluster changes.
Manual Admin API edits get overwritten
The controller is the source of truth. In APISIX Ingress Controller 2.0, a manual change made through the Admin API is overwritten on the next full sync. Emergency fixes therefore belong in the Kubernetes manifests, not on the running gateway. Document which changes are allowed outside Git and how quickly a hotfix is committed back to the cluster definitions.
Restart recovery depends on the controller
Because configuration is held in memory, a restarted gateway pod has no local copy of its rules to fall back on. Recovery waits for the controller to push configuration again. Test pod restarts, node drains and controller outages in a non-production cluster, and measure how long traffic is affected before you accept this trade-off for your availability targets.
Confirm etcd-dependent features
Any plugin, script, backup job or operator tool that reads from or writes to etcd directly may not behave the same way in API-driven standalone mode. The Ingress Controller also removed its mock-etcd mode in version 2.0. Build an inventory of every component that touches configuration, then confirm each one with the vendor or the APISIX documentation before you move a cluster.
Questions buyers ask before running APISIX without etcd
Can our platform team do this migration without a partner?
Yes, if the team already runs Kubernetes in production, has used Helm and understands APISIX routes, plugins and consumers. The work is not exotic, but it touches live traffic. Teams usually need time to learn how the controller becomes the source of truth, which changes how manual Admin API edits behave. Ask your own engineers to list the Kubernetes, Helm and APISIX skills they hold today, then compare that list against the work in the written scope. Gaps in those skills are the main reason teams bring in outside help, and the gap should be named before the decision, not after the first outage.
What drives the effort and cost of moving off etcd?
Cost follows the amount of configuration and the number of environments that must change. The main drivers are:
- Ingress Controller 2.x setup and version alignment with APISIX 3.13 or later
- Conversion of existing Admin API objects into Kubernetes resources and CRDs, including ApisixGlobalRule in place of the removed ApisixClusterConfig
- Testing of full-sync behavior, since the controller overwrites manual Admin API changes on the next sync
- Kubernetes skills across the cluster, identity and secrets
Setup is largely one-time. Ongoing upgrades and support recur. Ask any quote to split these items and to state which environments are included.
How long does the migration take for our route count?
Duration depends mainly on route count, plugin complexity and how many environments must be migrated and tested. No duration is supplied for this work, so it should come from a written scope rather than a general figure. Ask the provider to break the timeline into discovery, conversion, parallel testing, cutover and rollback preparation. A small route set with simple authentication will move far faster than a large estate with custom plugins and many consumers. Confirm whether the timeline assumes a freeze on configuration changes during cutover.
What do we need to provide before the work starts?
The work needs access and decisions from your side before it can be scoped accurately. Typical inputs include:
- Read and deploy access to the target Kubernetes clusters, with a named owner for each
- An inventory of current routes, consumers, plugins and global rules
- Your identity provider details for any OpenID Connect or SSO flows
- A change process that defines who approves cutover and rollback
- A staging environment that mirrors production closely enough for full-sync testing
Agree these inputs in the written scope. Missing access is one of the most common causes of schedule slip.
What breaks if manual Admin API changes are still in use?
In APISIX Ingress Controller 2.0 the controller is the source of truth, so manual changes made through the Admin API are overwritten on the next full sync. Teams that still edit routes by hand during or after migration can lose those edits without warning. Find every place where Admin API calls are made, including scripts, dashboards and runbooks, and route them through Kubernetes resources or the approved change path. Test this explicitly in staging before cutover.
What do we lose compared with running etcd?
API-driven standalone mode keeps configuration in memory on each gateway instance rather than in a shared etcd cluster. Teams should confirm how their own operations depend on etcd, such as backups, change history, or tools that read from it directly. Recovery also changes: rebuilding state comes from Kubernetes resources and the controller rather than from an etcd snapshot. Confirm these trade-offs with the vendor documentation for your exact versions before you commit.
When is etcd still the better choice?
Keep etcd when you run traditional or decoupled deployments across several gateway clusters, when other tools already read or write APISIX state through etcd, or when your team already runs and backs up etcd well. Standalone mode suits teams that want Kubernetes resources as the single source of configuration. If you run a mixed estate with virtual machines and containers, a shared etcd layer may still simplify operations. Ask the provider to compare both options against your actual topology before you choose.
Moving an existing etcd-based APISIX to standalone mode
The safest way to move an existing etcd-based APISIX estate to API-driven standalone mode is to start with an inventory, not a cluster change. Before anything is removed, list every route, upstream, consumer, plugin config and global rule currently in etcd, and separately list every change that someone made by hand through the Admin API. The second list matters most. With the Ingress Controller 2.x, the controller is the source of truth, and a manual Admin API change is overwritten on the next full sync. Any setting that exists only because an operator typed it into the Admin API will disappear during the move unless it is captured as an Ingress, Gateway API or APISIX custom resource first. Map each item to its target: Ingress v1 or Gateway API resources for standard routing, ApisixRoute and ApisixConsumer where plugin-rich routes or credentials need them, and ApisixGlobalRule in place of global rules. Confirm the target controller and APISIX versions against the supported pairing in the APISIX Ingress Controller upgrade guide and the overview, since the controller releases tie to specific APISIX lines.
Next, run the converted configuration in a parallel environment that uses the same upstream services but a separate gateway and load balancer address. Use a test namespace or cluster with API-driven standalone mode enabled, then compare the rendered APISIX configuration and the responses from both gateways for a representative set of requests, including authentication failures, rate-limited calls and error paths. Force a full sync by changing a harmless resource and confirm that the configuration returns to the controller's version, which proves that nothing depends on manual state. Rehearse the rollback as well: keep the etcd-based gateway running and warm, define the DNS or load balancer switch that returns traffic to it, and write down who makes that call and what evidence triggers it. Treat this as an illustrative sequence. The number of stages, the duration of parallel running and the amount of effort depend on how many routes and manual changes the inventory finds, and your team should set those from its own environment rather than from any published figure.
