Skip to main content
Version: 3.20.0

How APISIX Works

APISIX loads configuration into worker memory and uses it to match routes, execute plugins, and, when proxying, select an upstream inside OpenResty. This page explains how those components fit together, how request execution progresses through NGINX phases, and how configuration updates reach workers without a restart.

Overview​

APISIX is a Lua application that runs inside OpenResty, which is NGINX extended with the lua-nginx-module. NGINX provides the connection handling, worker model, and request phase machinery; APISIX adds a Lua program that hooks into each phase to perform routing, plugin execution, and upstream selection.

This page takes a request-flow view of APISIX. Every request that APISIX serves passes through three runtime components:

  • A configuration store that supplies the route and plugin definitions.
  • A router that matches the request to a route.
  • A plugin engine that runs the matched route's plugins at the appropriate NGINX phase.

The sections below describe each component and then trace a single request through them. Other parts of APISIX such as load balancing, service discovery, and the Admin API are referenced where they appear in the request flow but are covered in depth in their own pages.

The diagram below shows the request and configuration flow in the default traditional deployment mode, where etcd is the source of configuration. The router, plugin engine, balancer, and in-memory configuration all live inside each APISIX worker process:


File-driven standalone mode keeps the same request path but loads configuration from apisix.yaml or apisix.json. Each worker polls the local file and reloads it when the content changes:

Configuration Store​

In the default deployment mode, APISIX uses etcd as the source of truth for routes, upstreams, services, consumers, SSL certificates, plugin configurations, and global rules. Every NGINX worker subscribes to etcd through a long-poll watch and keeps an in-memory copy of the configuration.

When you create or update a resource through the Admin API, the change is written to etcd. Workers observe the change through the watch and rebuild their in-memory routing structures independently, without reload, restart, or cross-worker coordination. Configuration changes apply across a live cluster without dropping connections.

APISIX supports these configuration delivery paths:

  • Etcd-backed modes: in traditional mode and on decoupled data planes, etcd is the source of truth and every worker watches it. The traditional model is illustrated above.
  • File-driven standalone mode: each worker polls apisix.yaml or apisix.json and loads changes into memory. There is no etcd. See File-Driven Standalone Mode Configurations.
  • API-driven standalone mode for APISIX Ingress Controller: the controller uses this etcd-free path to send complete snapshots through the standalone Admin API. It resolves the gateway endpoints and sends the snapshot to each APISIX instance; worker coordination remains local to the receiving instance. This mode is designed for the Ingress Controller integration, not as a general operator-managed configuration workflow. See Set Up Ingress Controller and Gateway and API-Driven Standalone Mode Usage.

The request-flow behavior described in the rest of this page is independent of how configuration is delivered. See Deployment Modes for the full list of supported modes and how to configure them.

Router​

The router turns an incoming request into a matched route. APISIX uses a radix tree (a compressed prefix tree) as the matching engine.

Routes are inserted into the tree at configuration time, and at request time the URI is walked through the tree in time proportional to the length of the URI, not the number of routes configured. Match cost stays roughly flat as the route count grows.

APISIX bundles three HTTP router variants, which differ in what they use as the primary index of the tree:

  1. radixtree_host_uri (default): uses host + uri as the primary index. Matches both the request host and URI.
  2. radixtree_uri: uses only uri as the primary index. Hosts are not part of the index.
  3. radixtree_uri_with_parameter: same as radixtree_uri but additionally supports path parameters such as /user/:id.

The active HTTP router is selected through the apisix.router.http setting in config.yaml. SSL certificate selection during the TLS handshake uses a separate radixtree_sni router that matches the client's SNI value against the configured certificate set. For configuration and a feature comparison of the HTTP router variants, see Router Options.

Plugin Engine​

Once the router has identified the matched route, the plugin engine assembles the locally bound plugin configuration from these sources:

  • The matched route.
  • The route's referenced Plugin Config, if any.
  • The route's service, if any.
  • The matched consumer and consumer group, if any.

For non-authentication plugins, when the same plugin is configured in more than one local source, APISIX uses the highest-precedence configuration:

Consumer > Consumer Group > Route > Plugin Config > Service

Authentication plugins follow a different lifecycle. APISIX runs authentication from the pre-consumer local configuration before it knows the consumer. It then merges consumer and consumer group plugins, but does not rerun authentication plugins from that merge.

Global Rule plugins are not part of this precedence chain. They run as a separate global scope. For HTTP rewrite and access, APISIX runs global rewrite, local rewrite, global access, and local access in that order. In later common phases, the global scope also runs before the local scope.

Within one phase and global or local scope, the engine sorts plugins by priority, highest first. A priority cannot move a plugin across phase or scope boundaries. A plugin may modify the request or response, or terminate the request early. For example, an authentication plugin can return 401 before the request reaches an upstream.

A plugin defines one or more phase functions. The phases the engine drives for HTTP traffic are rewrite, access, before_proxy, header_filter, body_filter, and log.

Most plugins ship as Lua modules. APISIX also supports plugins written in Go, Java, and Python through the external plugin runner, and WebAssembly modules through the WASM runner. See Plugins for the per-phase model and the rules for combining plugin configuration from route, service, and consumer.

Request Lifecycle​

The following table traces a single HTTP request through the NGINX phases that APISIX hooks into:

PhaseWhat APISIX Does
ssl_client_hello / ssl_certificateUse the client's SNI value to pick a certificate from the radixtree_sni router.
accessMatch the request against the HTTP router, then merge the referenced Plugin Config and Service into the local route configuration. Run the global and local rewrite and access plugin groups in their execution order; Consumer and Consumer Group plugins can join the local configuration after authentication. A plugin may short-circuit the request here. Resolve the upstream, select the initial node, and then run before_proxy.
balancerApply the upstream node selected during access. For an eligible retry, reselect an upstream node with the configured load-balancing algorithm and health-check state.
header_filterRun response-header plugins as NGINX assembles the response headers.
body_filterRun response-body plugins as the response body is streamed back to the client.
logRun logging plugins after the response has been sent. Most logger plugins use NGINX timers so the client does not wait for the log write.

The diagram below shows the order in which APISIX executes routing, the plugin phases, balancer selection, and proxying for a single HTTP request:


Stream (Layer 4) traffic follows a parallel but smaller lifecycle:

PhaseWhat APISIX Does
prereadMatch the connection against the stream router and run the route's preread plugins. A plugin may close the connection here. Resolve the upstream, select the initial node, and then run before_proxy.
balancerApply the upstream node selected during preread. For an eligible retry, reselect an upstream node with the configured load-balancing algorithm and health-check state.
logRun logging plugins after the connection has been closed.

Hot Configuration Updates​

Every worker keeps an in-memory copy of the configuration. All modes can apply changes without reloading NGINX or restarting workers, but they distribute updates differently:

  • Etcd-backed modes: a control plane writes to etcd, and every data-plane worker independently receives the change through its etcd watch.
  • File-driven standalone mode: every worker polls the local apisix.yaml or apisix.json file and loads a completed update.
  • API-driven standalone mode for APISIX Ingress Controller: the receiving instance stores the controller's snapshot in shared memory and coordinates its local workers through worker events and fallback polling. The standalone API supports an optional bounded wait for local worker application; rollout across APISIX instances remains the controller's responsibility.

Additional Resources​