Roadmap to Learn Apache APISIX

1. Stage 1 – Fundamentals & Setup: Begin with core concepts and a basic APISIX installation. Learn
what APISIX is and how it works (it’s an open source, dynamic, scalable, high-performance API gateway
1 ). Read the official “Get APISIX” guide and Getting Started tutorials to understand terminology

(Routes, Services, Upstreams, Plugins, Consumers, etc.) and architecture 1 2 . Practice installing
APISIX (e.g. using the quickstart Docker script 3 ) and issuing Admin API calls to create your first
Route and Upstream. For example, use curl to create a route that proxies /hello to an HTTP
server (see the Configure Routes tutorial). Verify that APISIX is running (e.g. curl http://
127.0.0.1:9080 should return Server: APISIX/... 4 ). Resources: official docs (Get APISIX,
Installation), APISIX blog posts, the APISIX Dashboard UI for experimentation, and simple labs like
“create route → test response” or “enable a plugin (e.g. proxy-rewrite) on a route”.

2. Stage 2 – Feature Exploration: Dive deeper into APISIX’s features. Learn to use Routes vs Services
vs Upstreams: e.g. a Route matches client requests (host, URI, headers) and binds to an Upstream (a
set of backend nodes) 2 5 . Understand how a Service groups routes and allows shared plugin
configs (a Service is an abstraction for one or more routes and typically points to one upstream 6
7 ). Practice advanced routing (prefix/suffix matching, regex, weighted or canary routing) and

experiment with Upstream settings (load-balancing algorithms, retries, health checks 8 ). Explore
built-in plugins: e.g. enable authentication (key-auth, JWT, basic-auth) and traffic control (limit-
count, limit-req, limit-conn) on routes via Admin API. Try observability plugins: enable the
Prometheus plugin (scrapes metrics at :9091/apisix/prometheus/metrics 9 ) and a tracing
plugin (e.g. Zipkin 10 ). Set up logging (see the http-logger and other logger plugins) and view
APISIX access/error logs. Deploy APISIX in a small cluster: run an etcd cluster and multiple APISIX
nodes in “traditional” or “decoupled” mode 11 , and watch configuration sync via etcd. Try APISIX on
Kubernetes using the official Helm chart 12 . Resources: APISIX tutorials (Load Balancing, Key
Authentication, Rate Limiting), official docs on Plugins and Admin API, APISIX Dashboard, and
community examples (API7.ai blog).

3. Stage 3 – Advanced & Internals: Study APISIX’s internal architecture and extend it. Read about the
data plane / control plane separation: APISIX uses etcd (by default) as a config store, with the
Admin API writing to etcd and the OpenResty-based data plane nodes watching for changes 13 14 .
Examine the APISIX code structure (the apisix/ Lua modules, core/ , router/ , etc.) and
plugin lifecycle (init, schema check, rewrite, access, header/body filter, log phases). Try writing a
custom Lua plugin: follow the plugin development guide to create a plugin module (see the sample
code in the docs). Explore multi-language plugin runners: install the Go/Python/Java plugin-runner
and develop a plugin in your language of choice (APISIX supports external plugins via ext-plugin-
pre-req / post-req 15 ). Experiment with a WASM plugin (using the wasm support). Build a
production-style APISIX: automate config changes with scripts or CI (using the Admin API or the
APISIX ADC CLI), back up configurations, and practice rolling updates (APISIX supports hot-reloading
of configs without restarts 16 ). Finally, consider contributing or studying issues on the APISIX
GitHub to deepen understanding. Resources: official Development docs, APISIX code on GitHub,

1
 “How to Write Apache APISIX Plugin” blog posts, and community resources (eg. APISIX Slack,
StackOverflow).

Architecture and Internal Concepts

Figure: APISIX software architecture. APISIX is built on OpenResty (Nginx + LuaJIT) 17 . The APISIX Core (Lua
code) handles routing, load balancing, service discovery, and config management 18 . A Plugin Runtime
layer executes enabled plugins (written in Lua by default, or via multi-language runners/WASM) to
implement traffic control, security, observability, etc. All configuration (Routes, Services, Upstreams, Plugins,
Consumers) is stored in etcd (or another config center). When the Admin API updates a route or plugin,
APISIX writes to etcd; each APISIX node’s data plane (the Nginx processes) watches etcd and applies
changes in real-time 13 14 . This means no reloads/restarts are needed – APISIX supports fully-dynamic
hot-reload of routing rules and plugins 16 .

Core abstractions: A Route defines how to match an incoming request (e.g. uri , host , HTTP method)
and what Upstream to proxy to 2 . An Upstream is a virtual host with a load-balancing policy over one or
more backend nodes (type = round-robin, chash, least_conn, etc.), optionally with health-checks and retries
5 8 . You can attach an Upstream directly to a Route or to a Service (a Service abstracts common route

patterns and shared plugin config); typically multiple routes map to one Service (N:1) 6 7 . A Consumer
represents an API consumer (user or app) identified via authentication (key, JWT, etc.); you can bind plugins
or credentials to a Consumer. APISIX merges plugin configurations in precedence order: Consumer >
Consumer Group > Route > Plugin Config > Service 19 , so a per-consumer plugin (e.g. quota) overrides a
route-level setting.

Data flow: When a request arrives, Nginx hands it to APISIX’s router. APISIX matches it to the highest-
priority route (using the router-radixtree by default), looks up the target Service/Upstream, and assembles
the list of enabled plugins. Plugins execute in Nginx phases: rewrite → access → (upstream proxy) →
header_filter → body_filter → log. Each plugin has a defined phase and a numeric priority to order execution.
For example, rewrite plugins can modify URIs or headers before proxying; access plugins enforce
auth/rate-limits; header_filter / body_filter plugins can modify the response; and the log phase
logs the request. Built-in plugins include functions like traffic splitting, authentication, rate-limiting, header
manipulation, etc. (APISIX provides 80+ out of the box 20 21 ). After plugin processing, APISIX forwards the
request to the chosen Upstream node, using dynamic load-balancing and failover settings.

2
Features and Functionality
• Traffic management: APISIX excels at dynamic routing and load balancing. You can match on hosts,
paths, methods, headers, and even any Nginx variable 16 . It supports path rewriting and redirects
(via plugins). Upstreams support algorithms like round-robin, weighted-chash (sticky), least_conn,
and configurations for passive health-check and retry 8 . Advanced traffic control includes canary/
A-B testing via weight rules or the traffic-split plugin (send X% of traffic to a new upstream) 22 , and
circuit-breaking with the api-breaker plugin. APISIX also offers caching (proxy-cache plugin) and
request mirroring.

• Security: APISIX provides many built-in plugins for security. For authentication and authorization
there are key-auth, basic-auth, jwt-auth, hmac-auth, LDAP, Keycloak/OAuth integrations, and role-
based (wolf-rbac) plugins 23 . It has IP whitelisting/blacklisting (ip-restriction), user-agent restrictions
(ua-restriction), referer restrictions, and even CSRF protection 24 . A cors plugin easily enables cross-
origin headers 25 . APISIX can terminate TLS (HTTPS) and even mutual TLS: e.g. it supports mTLS on
the Admin API or client-to-gateway path (clients present certs validated against a CA) 26 . It can also
use mTLS when talking to etcd, and even configure mTLS between itself and back-end services for
end-to-end encryption. Rate-limiting is handled by plugins: limit-count (fixed window), limit-req (leaky
bucket), and limit-conn (concurrent connections) 27 . In practice, combine TLS, API keys, and these
access controls to harden the gateway.

• Observability: APISIX is designed for monitoring and tracing. It has a Prometheus plugin that
exposes internal metrics (requests, latencies, plugin stats, etc.) in Prometheus format 9 28 . A
community Grafana dashboard is available for visualizing APISIX metrics. For distributed tracing,
APISIX has plugins for Zipkin and OpenTelemetry. In fact the zipkin plugin sends spans to Zipkin (and
hence Jaeger or SkyWalking via Zipkin API) 10 , and there are dedicated skywalking and opentelemetry
plugins 29 . Each request can carry a request-id (via request-id plugin 30 ) for correlation. Logging is
flexible: APISIX logs in Nginx’s access/error logs by default, but you can push logs to external
systems via plugins. For example, http-logger can send JSON logs to an HTTP endpoint, and there are
built-in plugins to log via TCP, Kafka, RocketMQ, UDP, syslog, etc. 31 . (Datadog also has a built-in
monitoring plugin). This means you can integrate APISIX into any observability stack: Prometheus/
Grafana for metrics, ELK or Splunk for logs, and Zipkin/Jaeger/Tempo for traces.

• Scalability & HA: APISIX is horizontally scalable. All nodes are stateless – they only pull config from
etcd and serve traffic. You can spin up hundreds of APISIX instances behind a load balancer. Because
config lives in etcd (which itself should be run as a clustered/HA service), APISIX supports real-time
config updates across thousands of nodes with minimal lag 32 . The decoupled architecture
ensures the data plane is unaffected by control-plane tasks 13 . For high availability, run an etcd
cluster (or other supported store like Consul/Nacos) and multiple APISIX nodes; use Kubernetes with
its readiness probes and multiple pods; or run in cloud regions with DNS failover. APISIX also offers a
Standalone mode (for simple k8s YAML-driven setups) and a control-plane/data-plane split mode
11 for more complex deployments. In large setups, consider using the TiDB-backed config center (a

community project) as an alternative to etcd for very large configuration sets 32 .

3
Plugin Ecosystem
APISIX has 80+ built-in plugins (and counting). Key ones include:

• Authentication & Security: key-auth and jwt-auth are widely used to enforce API keys or JWT
tokens with consumers 33 . Other auth plugins: basic-auth , ldap-auth , hmac-auth , OAuth
(Keycloak, OIDC), etc. Rate-limit plugins ( limit-count , limit-req , limit-conn ) control API
traffic 27 . Security plugins like cors , ip-restriction , ua-restriction , uri-blocker ,
and csrf help block malicious or unwanted traffic 24 . The wolf-rbac plugin implements role-
based access control.

• Traffic Management: proxy-cache enables response caching; traffic-split implements

canary/blue-green traffic distribution 22 . proxy-mirror can duplicate requests to another
backend (for testing). api-breaker provides circuit-breaking. request-id tags requests with
unique IDs for tracing 30 . Utilities like proxy-rewrite and response-rewrite can modify
requests/responses on the fly. The request-validation plugin can validate JSON/XML payloads
against a schema.

• Observability: The prometheus plugin exposes metrics 28 . The skywalking , zipkin , and
opentelemetry plugins emit tracing spans 34 10 . There are dozens of logger plugins for access
logs: e.g. http-logger , tcp-logger , kafka-logger , rocketmq-logger , udp-logger ,
syslog , elasticsearch-logger , and cloud-specific loggers (SLS, Google Cloud, Splunk, etc.)
31 . There’s also node-status for node health, and log-rotate for file rotation.

• Serverless & Extensibility: APISIX includes serverless-pre-function and

serverless-post-function to run custom Lua functions before/after proxy. It supports external
plugins via the ext-plugin-pre-req and ext-plugin-post-req mechanism – you can write plugins in Go,
Java, Python, etc., and APISIX will call them over RPC 15 35 . WebAssembly (WASM) plugins are also
supported (using Proxy-WASM SDK).

Plugin ordering: All plugins run in fixed Nginx phases (init/schema → rewrite → access → proxy → header/
body filter → log). Within each phase, plugins execute in priority order. Plugin configs can be attached at
Route, Service, Consumer or global level 36 , and merged by the precedence rule (Consumer > Consumer
Group > Route > Plugin Config > Service) 19 .

Production Readiness
• Deployment patterns: APISIX runs virtually anywhere – on bare-metal, VMs or containers. You can
deploy via Docker (an official image is available) or on Kubernetes using the official Helm chart 12 .
In K8s, APISIX is often run with an accompanying APISIX Dashboard and an etcd (or etcd-like)
datastore. For simplicity, the traditional mode runs APISIX as both data and control plane; the
decoupled mode runs separate control-plane (Admin API) and data-plane instances 11 . The project
provides an Ingress Controller and Helm charts, and there are community charts (e.g. Bitnami) for
production.

4
 • CI/CD integration: Since all config is exposed via a RESTful Admin API, APISIX can be configured by
automation pipelines (curl, scripts, Terraform, etc.). Use Infrastructure-as-Code tools or GitOps (store
APISIX route/upstream JSON/YAML in Git). The api7.ai APISIX CLI and Dashboard can also manage
configs programmatically. In CI pipelines, you might curl the Admin API to update routes or use
the Terraform APISIX provider to declaratively manage APISIX resources. For secrets (API keys, TLS
certs), store them securely (e.g. HashiCorp Vault, Kubernetes Secrets) and use APISIX integrations
(APISIX can fetch TLS certs from Vault) 37 .

• Configuration & secrets: The static config.yaml (or environment) configures etcd addresses,
admin keys, ports, etc. Always change the default admin_key and restrict Admin API access
(firewall or mTLS) in production 38 . APISIX supports dynamic SSL: you can upload TLS certs via
Admin API or integrate with Vault (APISIX can retrieve certs from Vault on demand 37 ). If using
Kubernetes, store etcd TLS certificates and APISIX passwords in Secrets and mount them securely.
For multi-tenant or hybrid environments, you may run multiple APISIX clusters with separate config
centers and use API gateways or DNS to route traffic.

• Observability stack: In production, pair APISIX with Prometheus & Grafana for metrics (APISIX
exposes a built-in metrics endpoint 9 ). Import community Grafana dashboards (see Grafana.com).
Use Zipkin/Jaeger for tracing (APISIX can inject spans) and any logging system for access logs (e.g.
ELK via the http-logger or elasticsearch-logger ). The APISIX Dashboard itself provides
basic metrics and route status. Also monitor etcd health (APISIX depends on it).

• Security & hardening: Follow gateway best practices. Always enable Admin API authentication
(don’t leave it open) 38 . Run APISIX with least privilege (e.g. non-root user), and apply regular OS/
container hardening. Use TLS everywhere: require HTTPS for client→APISIX (and optionally mTLS for
admins/consumers) 26 , and TLS for APISIX→upstream if needed. Limit resources (worker processes,
timeouts) in config.yaml to mitigate DoS. Keep APISIX up-to-date and monitor logs for unusual
traffic. Use IP/UA restrictions and firewalls to limit access. In summary, treat APISIX as a critical edge
service – lock down ports, use strong crypto, and audit configurations.

Table: Deployment & Tooling Examples

Aspect Example Practices Resources

Docker containers; Kubernetes Helm chart; Official Docker/Helm docs;

Deployment
bare-metal APISIX blog 12 39

Admin API scripts (curl/HTTP); Terraform APISIX Admin API docs;

Config as Code
provider Terraform registry

Secrets Store certs/API keys in Vault or Kubernetes APISIX Vault integration guide
management Secrets 37

Automated route updates via pipeline; blue- Community blogs; APISIX

CI/CD
green rollout of APISIX versions GitHub examples

Prometheus + Grafana (APISIX metrics); APISIX monitoring docs 9 ;

Monitoring Stack
Zipkin/Jaeger for tracing; ELK for logs Grafana Dashboards

5
 Aspect Example Practices Resources

Enable Admin API auth; use mTLS; restrict IPs; APISIX Security FAQ; best-
Hardening
keep APISIX up-to-date practice guides

Sources: APISIX official documentation and blogs are the primary sources for these details 13 18 2 5

20 9 21 31 26 , supplemented by community resources.

1 3 4 38 Get APISIX | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apache-apisix.netlify.app/docs/apisix/getting-started/readme/

2 7 Route | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apisix.apache.org/docs/apisix/terminology/route/

5 8 Upstream | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apisix.apache.org/docs/apisix/terminology/upstream/

6 Admin API | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apisix.apache.org/docs/apisix/admin-api/

9 Monitor APISIX Metrics with Prometheus | APISIX & API7 API Gateway Docs
https://docs.api7.ai/apisix/how-to-guide/observability/monitor-apisix-with-prometheus

10 zipkin | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apisix.apache.org/docs/apisix/3.10/plugins/zipkin/

11 Deployment modes | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apisix.apache.org/docs/apisix/deployment-modes/

12 How to Easily Deploy Apache APISIX in Kubernetes | Apache APISIX® -- Cloud-Native API Gateway
39

and AI Gateway
https://apisix.apache.org/blog/2021/12/15/deploy-apisix-in-kubernetes/

13 15 Apache APISIX 3.0: 11 Highlights of Open Source API Gateway - API7.ai

https://api7.ai/blog/apache-apisix-3-0-11-highlights-of-open-source-api-gateway

14 High Availability Configuration with TiDB and APISIX | Apache APISIX® -- Cloud-Native API Gateway
32

and AI Gateway
https://apisix.apache.org/blog/2022/04/22/apisix-with-tidb-practice/

16 37 Getting started | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apache-apisix.netlify.app/docs/apisix/3.1/getting-started/

17 18 Architecture | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apisix.apache.org/docs/apisix/architecture-design/apisix/

19 20 36 Plugin | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway

https://apisix.apache.org/docs/apisix/terminology/plugin/

21 22 23 24 25 27 28 29 30 31 33 34 Plugin Hub | Apache APISIX® -- Cloud-Native API Gateway and

AI Gateway
https://apisix.apache.org/plugins/

6
26 Mutual TLS Authentication | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway
https://apisix.apache.org/docs/apisix/mtls/

35 How to Write an Apache APISIX Plugin in Java | Apache APISIX® -- Cloud-Native API Gateway and AI
Gateway
https://apisix.apache.org/blog/2021/06/21/use-java-to-write-apache-apisix-plugins/