Apache APISIX: A Lua Gateway Built on NGINX and etcd

The problem APISIX solves: configuration that changes without a restart

Traditional gateways keep routes and upstreams in a config file. Changing one means editing the file and reloading the process, which drops in-flight connections and forces a deployment window. APISIX separates the data plane from the configuration store. The README states that APISIX is built on top of NGINX and etcd, and that compared with traditional API gateways it has dynamic routing and hot-loading of plugins, which it says is especially suitable for API management under a microservice architecture.

That is the whole pitch. A route created through the Admin API is written to etcd, the data plane watches etcd, and the new route takes effect without restarting NGINX. The same mechanism applies to plugins, upstreams and certificates. The intended audience is platform and infrastructure teams running many services, where a gateway reload per change is not workable. It is less obviously aimed at a single application with three routes, where the etcd dependency costs more than the dynamism returns.

How the etcd data plane and hot plugin loading actually work

The architecture diagram in the repository shows APISIX sitting between clients and upstreams, with etcd as the configuration store. The README describes the gateway as "dynamic, real-time, high-performance" and lists hot updates and hot plugins as a feature: configurations and plugins update continuously without restarts. The Admin API is the write path; the data plane is the read path.

Because the data plane is NGINX with LuaJIT, request handling happens in Lua rather than in a separate process. That is why plugin behaviour can change at runtime: a plugin is Lua code loaded into the request path, and the README points readers to the plugin development guide and the plugin concept document for extending it. The trade-off is that the gateway's behaviour is only as predictable as the plugins you enable, and each enabled plugin adds work inside the request lifecycle. The README also notes that APISIX can serve as an AI gateway through the plugin system, with AI proxying, load balancing and fallbacks across multiple LLM providers, token-based rate limiting, and the mcp-bridge plugin that converts stdio-based MCP servers to HTTP SSE services. Those are plugin capabilities, not core routing features, and they inherit the same request-path cost.

Installing APISIX with the quickstart script and creating a first route

The README gives a single-command quickstart that requires Docker. It starts APISIX together with its etcd configuration store. APISIX listens on port 9080 and the Admin API on port 9180.

curl -sL https://run.api7.ai/apisix/quickstart | sh

After it finishes, the README suggests checking that the server responds by grepping the Server header from a HEAD request. You should see a Server header in the response.

curl "http://127.0.0.1:9080" --head | grep Server

Next, create a route through the Admin API. This example proxies /get to httpbin.org over round-robin. The route id here is 1, and the PUT is idempotent, so re-running it overwrites the same route.

curl -i "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT -d '
{
  "uri": "/get",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

Finally, send a request through the gateway on port 9080 to confirm the route works. The response body comes from the upstream, not from APISIX.

curl "http://127.0.0.1:9080/get"

The README points to the Getting Started guide and the installation documentation for other deployment methods, including Kubernetes. Note that the quickstart command fetches a script from run.api7.ai and pipes it to a shell, and the README does not document what that script does beyond starting APISIX and etcd. If your environment forbids piping remote scripts into sh, use the installation guide instead.

etcd is not optional, and that is the main architectural cost

Every dynamic feature in APISIX depends on etcd being reachable from the data plane. The README presents etcd as part of the foundation alongside NGINX, not as an optional backend. If etcd is unavailable, the gateway can keep serving from the configuration it already holds, but new routes, plugin changes and certificate updates cannot be applied. The README does not document rollback behaviour when a bad configuration is written, and it does not document what happens to in-flight requests during an etcd outage. Treat those as questions to answer against the operations documentation before production use.

This is also where APISIX is the wrong tool. If your deployment model is a single container with a config file, or a serverless edge where you cannot run a stateful configuration store, the etcd dependency is a liability rather than a feature. A gateway that reads a static file and reloads on signal is simpler for that case, and APISIX's dynamism buys you nothing.

APISIX compared with Kong: same job, different configuration model

Kong is the most common comparison, and the difference is not the feature list. Kong's traditional deployment stores configuration in a database and its newer modes move toward declarative files and a database-less proxy. APISIX commits to etcd as the source of truth and to LuaJIT on NGINX as the execution engine, and the README frames the dynamism as the reason to choose it.

The practical difference shows up in operations. With APISIX you are running and backing up etcd, and you need to understand how the data plane watches it. With Kong you are choosing between a database and a declarative config file, and the operational burden lands elsewhere. Neither is strictly better; the question is which dependency you already have. A team already running etcd for Kubernetes has most of the APISIX operational story in place. A team that does not will be adding a stateful service to run a gateway.

Licence, release cadence and what upgrading costs

APISIX is licensed under Apache-2.0, and the repository carries the standard ASF files including LICENSE and NOTICE. Apache-2.0 is a permissive licence with an explicit patent grant, which matters if you embed the gateway in a product. This is a description of the licence identifier in the repository, not legal advice; review the LICENSE and NOTICE files with your own counsel if you redistribute.

The repository shows three releases in 2026: 3.16.0 on 2026-04-08, 3.17.0 on 2026-06-16 and 3.18.0 on 2026-08-20. The last push to the default branch was on 2026-09-18. That cadence is worth weighing: a gateway upgrade is not a library bump, and if you run custom Lua plugins you own the work of checking them against each new release. The README does not describe a long-term support policy or an upgrade procedure, so the cost of a version jump has to be estimated from the changelog and the release notes for each version you cross.

What APISIX is not good at

APISIX is not a service mesh. The README positions it for north-south traffic and for east-west traffic between services, and it can act as a Kubernetes ingress controller, but the sidecar-per-pod model is a different design with different failure modes. If you want mutual TLS between every workload without a central proxy, a mesh addresses that more directly.

It is also not a configuration UI. The README documents the Admin API and the documentation site, and the related searches show people looking for an APISIX dashboard and an APISIX UI, but the README in this repository does not describe a bundled dashboard. Plan on driving configuration through the Admin API or through an ingress controller, and treat any dashboard as a separate component you have to source and operate yourself.

Editorial conclusion

Adopt APISIX if you already operate etcd or Kubernetes and need routes and plugins to change without a reload. Do not adopt it if you want a gateway with no external configuration store, or if you cannot run LuaJIT and OpenResty in your build pipeline. Before committing, verify that the plugin you need exists in the repository's plugin directory, that your deployment can reach etcd on its client port, and that your release cadence can absorb the upgrade pace implied by 3.16.0, 3.17.0 and 3.18.0 shipping between 2026-04-08 and 2026-08-20.

Frequently asked questions

Official sources

1. apache/apisix on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases