Apache APISIX

Last reviewed Aug 26, 2026 · 854 words

Apache APISIX is Nginx where the configuration lives in etcd and every change takes effect without a reload. That is the whole pitch and the whole cost in one sentence. The pitch: routes, upstreams, rate limits and authentication plugins are objects you create over an Admin API, hot-applied across every gateway node in milliseconds, with about 100 plugins available. The cost: you are running etcd, a consensus datastore, to publish a web app. If your job is putting HTTPS in front of Jellyfin and Vaultwarden, that is the wrong trade and Caddy or Traefik will make you happier. If your job is exposing APIs to third parties with keys, quotas and metrics, APISIX is one of the two serious open-source options.

Two containers minimum, and the admin key is the first thing to fix

APISIX ships as the apache/apisix image and needs etcd 3.4 or later beside it. The gateway listens on 9080 for HTTP and 9443 for HTTPS, the Admin API on 9180, and Prometheus metrics on 9091. The distributed default config.yaml contains a well-known admin key, edd1c9f034335f136f87ad84b625c8f1, that appears in every tutorial and every scanner's wordlist. Change it before the container has a public port, and bind the Admin API to localhost or a management network:

# conf/config.yaml
deployment:
  admin:
    allow_admin:
      - 127.0.0.0/24
    admin_key:
      - name: admin
        key: replace-with-40-random-characters
        role: admin
  etcd:
    host:
      - "http://etcd:2379"

The catalogue's 512 MB is realistic for the gateway alone; etcd wants its own few hundred megabytes and, more importantly, a disk that is not slow, because etcd fsyncs constantly and a cheap SD card will make the whole gateway sluggish.

Routes, upstreams and plugins are the entire mental model

Everything you do is one of three objects. An upstream is a set of backend nodes and a balancing algorithm. A route matches a host, path and method and sends traffic to an upstream. Plugins attach to routes (or to services and consumers, which are just reusable bundles) and run in a fixed order. Creating a rate-limited route is one request:

curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $ADMIN_KEY" -d '{
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "limit-req": { "rate": 10, "burst": 5, "key": "remote_addr", "rejected_code": 429 }
  },
  "upstream": { "type": "roundrobin", "nodes": { "app:3000": 1 } }
}'

The plugin library is where the value is: key-auth, jwt-auth and openid-connect for identity, limit-count and limit-req for quotas, cors, proxy-rewrite, prometheus, opentelemetry, gRPC transcoding and WebSocket proxying. Plugins are Lua running inside OpenResty, and you can write your own in Lua or, more slowly, in an external runner. This is the actual reason to pick APISIX over a reverse proxy: those features exist as one-line JSON, not as a Nginx snippet you maintain.

Standalone mode drops etcd if you can live with a file

For a single gateway you can skip etcd entirely. Set deployment.role to data_plane with config_provider: yaml, and APISIX reads routes from conf/apisix.yaml, reloading when the file changes. You lose the Admin API and the multi-node hot sync, and keep the plugins and the performance. For a homelab publishing 3 APIs this is the version I would run; it turns "APISIX plus etcd plus dashboard" into "one container and one YAML file", which is a fair fight against Traefik. The dashboard is a separate deployment and the project has reshuffled its dashboard efforts more than once; treat the Admin API and the YAML file as the stable surfaces and the UI as a bonus.

Where it sits against Kong and against the proxies

Kong is the other serious gateway, also Nginx-and-Lua underneath, backed by Postgres rather than etcd and with a commercial edition that owns the more advanced plugins. APISIX is Apache-2.0 throughout with about 17,000 stars and no open-core split, which is the reason a lot of teams moved to it. Against Traefik and Caddy the comparison is simpler: they auto-discover Docker containers and get certificates for you, and APISIX does neither out of the box. The reverse proxy showdown covers the proxy tier; the proxy category lists the field. On Kubernetes, APISIX also has an ingress controller and a Helm chart, which is where the etcd model stops feeling like overhead because you already run a cluster.

What I'd do

Run APISIX only when you are publishing an API, meaning consumers with keys, per-consumer rate limits and metrics you have to show someone. In that case use standalone YAML mode for a single node, or etcd on real disk for more than one, change the admin key before the first docker compose up, and keep Caddy or Traefik in front for certificates and the ordinary web traffic. For the standard homelab of a dozen web UIs, do not run it at all; Traefik with Docker labels does 100% of that job with a fraction of the moving parts.