Which APISIX deployment mode fits your team
Choose traditional mode unless you have a specific reason to separate the planes or remove etcd. Traditional mode runs the data plane and control plane together on each node, uses etcd as the configuration center, serves user traffic on port 9080 and the Admin API on port 9180. It is the simplest single-tier path, and it fits a team that wants one set of instances to operate. Before you go live, decide whether the Admin API should stay on. The deployment modes documentation says it must be turned off manually with enable_admin if you do not need it, so make that a deliberate step in your hardening checklist rather than a default you inherit.
Choose decoupled mode when the Admin API should sit on different infrastructure from public traffic. Control plane nodes serve Admin API requests on port 9180, data plane nodes serve user requests, and both read configuration through the same etcd cluster. This suits organizations that want configuration changes confined to a restricted network segment while gateways face the internet. The cost is a second tier to deploy, scale, patch and monitor, and etcd becomes a shared dependency for both tiers. Confirm the exact network and role settings for your version with the APISIX deployment modes documentation before you draw your topology.
Choose standalone mode when you want no etcd and configuration to live in version control, typically on Kubernetes with GitOps. Standalone nodes read full declarative configuration. The file-driven variant loads conf/apisix.yaml or conf/apisix.json with role data_plane, checks for changes every second and requires a #END marker at the end of the YAML file. The API-driven variant keeps rules only in memory, starts empty and replaces the full configuration on each update through the Standalone Admin API. The docs position that variant for the APISIX Ingress Controller and ADC, and warn against using it directly unless you understand its internals. Treat the two variants as different products for planning purposes, and test failure and restart behavior before you rely on either.
Traditional, decoupled and standalone compared
This table compares the three documented Apache APISIX deployment modes on configuration storage, node roles, Admin API placement, etcd dependency, Kubernetes and GitOps fit, and the cautions in the docs. Read each row across to see which mode matches your change process and where you would need to run extra components. The main takeaway is that only standalone mode removes etcd, and its API-driven variant carries an explicit warning against direct use.
| Aspect | Traditional mode | Decoupled mode | Standalone mode |
|---|---|---|---|
| Configuration storage | etcd as the config_provider | etcd shared by data and control plane | YAML or JSON file, or the Standalone Admin API |
| Node role | Data plane and control plane on one instance | Separate data plane and control plane instances | Data plane role only, configured from file or API |
| Admin API location | Port 9180 on the combined instance | Port 9180 on control plane nodes | Standalone Admin API, intended for API-driven use |
| Dependency on etcd | Required | Required | Not used |
| Kubernetes fit | Possible, but etcd remains a dependency to run | Possible, with etcd remaining a dependency | Documented as targeting Kubernetes with full declarative YAML |
| GitOps fit | Indirect, since changes go through etcd and the Admin API | Indirect, since changes go through etcd and the Admin API | Direct for file-driven mode, since the file lives in version control |
| Change propagation | Written to etcd and picked up by nodes | Written to etcd and picked up by data plane nodes | File-driven: checked every second and hot-reloaded. API-driven: full replacement per update |
| Documented cautions | Admin API should be disabled with enable_admin if not needed | Confirm the control and data plane split in your own network design | Requires a #END marker in the YAML file. Do not use API-driven mode directly unless you fully understand its internals |
What each mode runs and where the Admin API sits
Apache APISIX splits its work across a few parts: nodes that serve traffic, nodes that serve the Admin API, a configuration store, and file or API inputs in standalone mode. Each part decides who can change routes and where a compromise could reach, so map them before you pick a mode.
Traditional mode node
In traditional mode, one APISIX instance runs the data plane and control plane together, with etcd as the config_provider. User traffic arrives on port 9080 and the Admin API listens on port 9180 on the same node. Because the Admin API is exposed wherever the node is reachable, the docs say to disable it with enable_admin when you do not need it. Check which networks can reach port 9180 before you go live.
Decoupled control plane
In decoupled mode, control plane instances serve Admin API requests on port 9180 and write configuration through the shared etcd cluster. Keeping the Admin API off the traffic-facing nodes narrows the path an attacker would take to change routes. The cost is a second deployment to run, monitor and upgrade. Confirm who holds Admin API keys and how etcd access is restricted.
Decoupled data plane
Data plane nodes in decoupled mode serve user requests on port 9080 and read configuration from etcd without exposing the Admin API. This is the boundary most security teams want: internet-facing nodes hold no write path to routing rules. Verify that data plane nodes have read-only etcd credentials, and that a failed control plane does not stop traffic already being served.
etcd as the config center
etcd is the shared store in traditional and decoupled modes, so every node that reads it trusts its contents. Anyone who can write to etcd can change routes and plugins across the fleet, regardless of Admin API controls. Ask your platform team to confirm etcd authentication, TLS between members and backup procedures before you commit to these modes.
File-driven standalone loader
In file-driven standalone mode, the node runs with role data_plane and reads conf/apisix.yaml or conf/apisix.json, checking for changes every second and hot-reloading without a restart. The YAML file must end with a #END marker, so a truncated file is a real failure mode. Because there is no etcd and no Admin API write path, changes flow through Git and your deployment pipeline. Confirm who can write the file and how file integrity is verified.
API-driven standalone store
In API-driven standalone mode, rules live only in memory, the node starts empty, and each update replaces the full configuration through the Standalone Admin API. A partial update cannot be applied, and a restart discards the state unless the controller that pushes it re-sends it. The docs position it for the APISIX Ingress Controller and ADC, and warn against direct use unless you understand its internals. Plan for an upstream controller to own this state.
Why turning off the Admin API matters in traditional mode
In traditional mode, the Admin API and user traffic share one instance. The data plane and control plane run together, user requests arrive on port 9080, and the Admin API listens on port 9180 on the same node. Anyone who can reach port 9180 can change routes, upstreams and plugins, so the Admin API is effectively a management interface living on the traffic path. The APISIX deployment modes documentation says the Admin API must be turned off manually with enable_admin if you do not need it, which means the default posture depends on your configuration rather than on the topology alone.
This affects network segmentation directly. If you keep the Admin API, restrict port 9180 to a management network or an allowlist of administration hosts, and confirm that load balancers, ingress rules and security groups never expose it to the client-facing network. Decoupled mode changes the shape of the problem: control plane instances serve Admin API requests on port 9180 and data plane instances serve user requests, so you can place the two behind different network policies and scale or lock down each tier separately. Both modes read configuration through etcd, so etcd access also needs the same scrutiny.
Before you commit to a mode, confirm the exact configuration keys, listening ports and network policy against the current APISIX documentation for the version you will run, not against this summary. Ask your platform team to write down which hosts may reach the Admin API, test that a request from a client-facing network segment fails, and record the result as part of your implementation evidence. Your security team should also decide whether a standalone deployment, which has no Admin API on the traffic path in its file-driven form, better matches the control model you need.
Which mode fits Kubernetes, VMs and GitOps teams
Teams running on Kubernetes usually start with the APISIX Ingress Controller, which is a separate project with its own release line (APISIX Ingress Controller 2.2.0 was released on August 18, 2026, per the APISIX downloads page). The standalone mode is the one the documentation describes as targeting Kubernetes, using declarative full YAML configuration and external configuration centers such as Consul. In API-driven standalone mode, the rules live only in memory, the configuration starts empty, and each update replaces the full configuration through the Standalone Admin API. The docs position that API for the Ingress Controller and ADC, so application teams should not call it directly.
- Controller-managed config: The Ingress Controller and ADC push full configurations, so the team operates the controller lifecycle alongside the gateway.
- In-memory state: Standalone configuration does not persist in etcd, so a restarted pod depends on the controller or a file to repopulate routes.
- Declarative files: File-driven standalone mode reads
conf/apisix.yamlorconf/apisix.jsonand needs the#ENDmarker at the end of the YAML file. - Direct API use: The docs warn against using the standalone Admin API directly unless you fully understand its internal workings.
- External config centers: Consul is named as an example of an external configuration center, so confirm whether your cluster needs it.
Before committing, confirm with the APISIX project which Ingress Controller version pairs with your gateway version and how it handles failover.
Teams running APISIX on virtual machines with a shared etcd cluster usually fit the traditional or decoupled topology. In traditional mode, the data plane and control plane run together on each instance, with etcd as the config_provider, user traffic on port 9080, and the Admin API on port 9180. In decoupled mode, data plane nodes serve user requests while control plane nodes serve Admin API requests on port 9180, and both read configuration through etcd. The team must operate the etcd cluster as the source of truth for every node, which makes its health a shared dependency.
- Traditional simplicity: One instance type handles traffic and administration, so there are fewer moving parts to deploy.
- Admin API exposure: In traditional mode the Admin API is on by default, so set
enable_adminto off on nodes that do not need it. - Decoupled separation: Control plane nodes can be placed on a network segment that only administrators reach, with data plane nodes exposed to users.
- etcd operations: Backup, quorum and upgrades for etcd become a responsibility of the platform team.
- Port planning: Plan firewall rules for 9080 and 9180 separately for each node role.
Confirm your etcd backup and restore procedure before go-live, and test a control plane outage in a non-production environment.
Teams that want gateway configuration in version control usually look at standalone mode, because file-driven standalone mode removes etcd from the configuration path. The file-driven option loads routes from conf/apisix.yaml or conf/apisix.json, checks for changes every second, and hot-reloads without restarting, with the data plane role and the yaml or json config provider. A pipeline can therefore commit the file, review it, and let the gateway pick up the change. The team must still build the pipeline that renders, validates and delivers that file to every node.
- Reviewable changes: Route changes appear as diffs in pull requests, which suits change approval workflows.
- Full-file model: Each change is a complete configuration file, so review should cover the whole file, not only the changed lines.
- Delivery to nodes: The pipeline, not APISIX, must distribute the file to every data plane node and confirm each one reloaded.
- Rollback: Keep prior file versions in Git so that a bad change can be reverted quickly.
- Secrets: Keep credentials out of the file in plain text and inject them through your secrets tooling.
Ask the vendor or project how file-driven standalone mode behaves under your expected route count and whether dynamic Admin API changes are needed in the same environment.
What each mode asks your operators to run
This table compares what operators must maintain in each Apache APISIX deployment mode: etcd, the separate control plane, and configuration files or full-replacement pipelines. Read each row against your own team's skills and upgrade cadence. The main takeaway is that traditional and decoupled modes carry etcd operations as a standing duty, while standalone moves that duty into your configuration pipeline.
| Operator task | Traditional mode | Decoupled mode | Standalone mode |
|---|---|---|---|
| Configuration store | etcd cluster on the same nodes as the data and control plane | etcd cluster shared by separate data plane and control plane instances | No etcd; a YAML or JSON file, or an API that replaces the full configuration |
| etcd backup and recovery | Operators must back up and test restore of etcd, since it holds all routes and plugins | Same etcd duty, with backup covering the shared cluster that both planes read | Not applicable to APISIX; back up the configuration files or the source that generates them |
| Control plane lifecycle | Upgraded together with the data plane on each node | Control plane nodes are a separate fleet to patch, scale and monitor | Not applicable; the file or API pipeline is the control surface |
| Upgrades and release cadence | APISIX 3.19.0 was released September 28, 2026; the docs do not mark any release as long-term support, so set your own cadence | Same cadence rule, applied to two instance types that must stay compatible | Same cadence rule; test each new release against your full configuration file before rollout |
| Config change pipeline | Admin API calls or scripts; confirm audit and change records in your own tooling | Admin API on control plane nodes; changes flow to data plane through etcd | Git-managed YAML or JSON reloaded within about a second, or full-replacement API calls |
| Monitoring focus | Node health, etcd health, and both listeners on ports 9080 and 9180 | Data plane and control plane health tracked separately, plus etcd | Data plane reload status and file integrity; confirm metrics available in your version |
| Skills your team needs | etcd administration, NGINX and Lua operations | etcd administration plus separate fleet management for control plane | Configuration-as-code discipline and tooling for generating full configurations |
| Admin API exposure | Admin API on port 9180 stays on unless disabled with enable_admin | Admin API served from control plane nodes only | Admin API is intended for the Ingress Controller and ADC; the docs advise against direct use without deep understanding |
How to choose a mode in four decisions
This sequence narrows the three documented APISIX deployment modes to one by testing for a shared etcd need, Admin API exposure, Git-driven file configuration and Ingress Controller or ADC use. It ends with a pilot that shows whether the chosen mode fits your operations before production commits to it.
Confirm whether you need a shared etcd
Platform engineering and the API team answer one question: do you need a configuration center that every gateway node reads from, with the Admin API used to change routes at runtime? If yes, you are in traditional or decoupled mode, where etcd is the configuration center. If no, configuration can live in a file or an API-driven standalone setup with no etcd. Record the answer in the design document. It is done when the team agrees on the answer and names who owns the etcd cluster if one is needed.
Decide whether the Admin API must stay off user-facing networks
The security architect checks where the Admin API on port 9180 will be reachable. In traditional mode, the data plane and control plane share one instance, and the docs say to turn the Admin API off with enable_admin if you do not need it. In decoupled mode, the Admin API runs on separate control plane nodes, which lets you keep those nodes off the user-facing network. Document the network path and the access controls for the Admin API. It is done when the security architect signs off on the placement of every node that serves the Admin API.
Test whether configuration must come from Git through a file
The platform team checks whether route changes must go through a Git review and be applied from a file. File-driven standalone mode loads routes from conf/apisix.yaml or conf/apisix.json, checks for changes every second and runs with the data_plane role. The YAML file must end with a #END marker. If the team needs runtime changes through the Admin API instead, the API-driven standalone mode is a different option, and its docs warn against using it directly unless you understand its internal workings. It is done when the team has a written choice between file-driven and API-driven configuration, with a sample file that passes review.
Check whether the Ingress Controller or ADC will manage the gateway
The Kubernetes platform owner determines whether the APISIX Ingress Controller or ADC will generate and push configuration. The standalone docs position API-driven standalone mode for these tools, so their use changes the answer from the earlier steps. Confirm the controller version you plan to run, using the APISIX downloads page as the reference for the 2.2.0 release date, and confirm the compatibility with your APISIX version with the vendor or project. It is done when the team records the controller, its version and the mode it requires.
Build a pilot in a non-production environment
The platform team deploys the chosen mode in a non-production environment that mirrors your identity provider, network zones and certificate handling. Run the openid-connect flows your applications need, load test a representative route set, and rehearse a configuration change and rollback. Confirm the ports (9080 for client traffic, 9180 for the Admin API) are reachable only where intended. It is done when the pilot passes the agreed checks and the team can explain each failure it found.
Scope the migration cost before production
Before production, the architecture lead asks the vendor or your own team to estimate what switching modes later would involve. Changing mode generally means moving configuration between a database-backed etcd store and a file or API model, so the work includes exporting routes, plugins and certificates and validating them in the new mode. Ask for the migration steps in writing and who performs each one. It is done when the migration scope is a written document that the sponsor has accepted, because the mode choice is hard to reverse without a configuration migration.
Questions teams ask before running APISIX in production
What drives the cost and effort of each APISIX deployment mode?
The mode changes the number of moving parts more than the license, which is Apache-2.0 for every mode. Traditional mode puts the data plane and control plane on each node and depends on etcd as the configuration center. Decoupled mode adds separate control plane instances, so there are more deployments to size, patch and monitor. Standalone mode removes etcd but shifts effort to how configuration is generated, versioned and reloaded. Recurring cost comes from infrastructure, on-call time and upgrades. Ask any provider to price each mode separately, listing the nodes, etcd cluster, Kubernetes components, monitoring and the hours to build and maintain configuration pipelines.
Can our own team run APISIX in production without outside help?
A team with Linux, NGINX, etcd and Kubernetes experience can run APISIX itself, since the project and its documentation are public and the code is Apache-2.0. The gaps are usually Lua plugin development, hardening the Admin API and writing a safe configuration release process. Count the skills you lack, the people who would carry on-call duty, and the time for a first pilot before you commit. A fixed-scope engagement with DeployOpen can cover planning, implementation, hardening, backup and documentation for a defined set of environments, with ongoing support available as a retainer. Request the written scope, deliverables and timeline before work starts.
How long does an initial APISIX rollout take?
No duration can be stated from the researched facts, so treat any figure you hear with caution. The rollout length depends on the chosen mode, the number of routes and plugins, your identity integration, the number of environments, and whether you run Kubernetes. Standalone file-driven setups can be small, while traditional or decoupled setups add etcd clustering and network design. Ask for a timeline tied to named milestones: environment build, pilot routes, identity testing, load testing, backup and restore testing, and handover. A written scope should state what is excluded so the timeline is comparable across bids.
What skills do operators need for etcd, Kubernetes and Lua plugins?
Traditional and decoupled modes require operators who can run an etcd cluster, since APISIX stores its configuration there and both modes read it through etcd. Kubernetes skills matter if you use the APISIX Ingress Controller or standalone mode for declarative deployment. Lua knowledge matters only if you write custom plugins, because APISIX runs Lua plugins inside worker processes; the docs also describe external plugin runners for Java, Go and Python. Confirm these skills against your roster, and ask any implementer to name the people who would perform the work and how knowledge transfers to your staff.
Is standalone mode safe for general production use?
File-driven standalone mode is the safer starting point for teams that want declarative configuration, because it reads conf/apisix.yaml or conf/apisix.json, checks for changes every second and hot-reloads. The API-driven standalone mode keeps rules only in memory and replaces the full configuration on each update, and the APISIX docs say it is intended for the APISIX Ingress Controller and ADC and warn against using it directly unless you fully understand its internals. Treat that warning as a design constraint. Ask for a written review of which mode fits your release process, and confirm current guidance in the APISIX deployment modes documentation.
How do we switch between APISIX modes later?
Switching is possible but it changes where configuration lives and who operates it, so plan it as a migration. Moving from traditional to decoupled usually means splitting roles across instances while keeping etcd. Moving to standalone means exporting routes, plugins and upstreams into YAML or JSON and removing the etcd dependency, which requires testing every route and credential. Ask any implementer for a migration plan covering inventory of routes and plugins, a parallel run, rollback steps, the Admin API shutdown with enable_admin, and a record of what changed for auditors. Include the cost of that migration in the original quote.
How DeployOpen scopes and delivers APISIX deployments
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, so the mode decision is made against your network, identity and Kubernetes setup. Engagements are fixed-scope, with scope and deliverables agreed in writing before work starts.
How we scope
- Written scope names the chosen mode: traditional, decoupled or standalone, and the reason for it.
- Scope lists which nodes, etcd clusters or Kubernetes namespaces are in and out of the work.
- Scope states whether the Admin API stays enabled, and who controls its access.
- Ask us to confirm which identity provider and OIDC flows the openid-connect plugin will use.
How we build
- Deploy traditional or decoupled topologies with the Admin API on port 9180 restricted to approved clients.
- For standalone, build the YAML or JSON configuration files and the Git workflow that feeds them.
- Test route changes, plugin behavior and failover in a non-production environment before cutover.
- Configure the Admin API off with enable_admin where the chosen mode does not need it.
How we hand over
- Documentation covers the topology diagram, port map, configuration sources and change procedure.
- Runbooks cover upgrades, etcd backup and restore, and rollback steps for the chosen mode.
- Handover includes a record of the trade-offs, including what changes if you later move modes.
- Evidence for access control and change management is packaged for your compliance reviewers.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Retainers can cover version tracking against the APISIX release history you choose to follow.
- Re-testing follows each upgrade, plugin change or move from one deployment mode to another.
- Ask for a written quote tied to the scope, with the recurring and one-time items listed separately.
