How to Setup Apisix and Create Your First Route: Trends, Risks and Outlook
How to Setup Apisix and Create Your First Route: Trends, Risks and Outlook
Author: Your Name • 30 Apr 2026
1️⃣ Why Apache Apisix?
Apache Apisix is a free, open‑source gateway built on the speed of Nginx‑lib and the flexibility of a KV store (etcd, Consul, Redis). It lets you push configuration changes live, scale horizontally, and change routes with zero downtime. Because it runs as a standalone process, a side‑car, or a stateless micro‑service, it fits easily into Kubernetes, service meshes, or traditional VM setups.
Key selling points
- High‑performance – writes Python‑style performance hacks into Nginx.
- Dynamic config loop – updates in etcd are applied on the fly.
- Rich plugin ecosystem – built‑in rate limiting, authentication, circuit breaking, and a Lua/Go plugin SDK.
- Developer portal – an optional UI to manage routes and view metrics.
2️⃣ Prerequisites
| Item | Minimum | Notes |
|---|---|---|
| OS | Ubuntu 20.04 LTS (Debian based) | macOS, CentOS, Alpine, Docker also work |
| Go | 1.18+ | Only if you build from source |
| Node.js | 14+ | Needed for the portal and plugin SDK |
| etcd | 3.5+ | Keeps routing data |
| Git | 2.28+ | Clone the repo |
| Docker (optional) | – | Great for a quick demo |
If you want to skip the plumbing, jump to the Run with Docker section.
3️⃣ Installation Methods
3.1. Pre‑built Binary (Ubuntu 20.04)
sudo apt update && sudo apt install -y curl gnupg
curl -fsSL https://apache.bintray.com/apisix/KEY.pub | sudo apt-key add -
echo "deb https://apache.bintray.com/apisix/apt/ stable main" | \
sudo tee /etc/apt/sources.list.d/apisix.list
sudo apt update
sudo apt install -y apisix
3.2. Build from Source
git clone https://github.com/apache/apisix.git
cd apisix
git checkout v3.10.0 # bump to the latest stable tag
./build.sh
The build outputs an OpenResty bundle at ./build/openresty/nginx.
3.3. Docker Compose (Fast, portable)
# docker-compose.yml
version: "3.8"
services:
etcd:
image: bitnami/etcd:3.5
container_name: apisix-etcd
environment:
- ALLOW_NONE_AUTHENTICATION=yes
- ETCD_ADVERTISE_CLIENT_URLS=http://etcd:2379
expose:
- "2379"
restart: unless-stopped
apisix:
image: apache/apisix:3.10
container_name: apisix
depends_on: [etcd]
environment:
- HOST=0.0.0.0
- PORT_START=9080
- PORT_ADMIN=9091
ports:
- "9080:9080"
- "9091:9091"
restart: unless-stopped
docker compose up -d
The image includes a ready‑to‑use etc/apl.conf that points at the local etcd cluster.
4️⃣ Configuring etcd
When you run the Docker compose stack, etcd is already exposed. For a fresh, non‑Docker install:
# Create a namespace that Apisix will read from etcd
ETCDCTL_API=3 etcdctl \
--endpoints=https://127.0.0.1:2379 \
--insecure-skip-tls-verify \
put /apisix/keys/server1
If you prefer Consul or Redis, modify conf/config.yaml accordingly.
5️⃣ Start the Gateway
5.1. Binary or Source
cd /usr/local/apisix
cp conf/config.yaml.dev conf/config.yaml # example config
export APISIX_HOME=$(pwd) # optional helper
openresty -c conf/nginx.conf
You should now see logs indicating the gateway listening on 9080 (proxy) and 9091 (admin).
curl http://127.0.0.1:9091
Expected: {"status":200,"message":"APISIX Hello, VIP"}
5.2. Docker
With Docker compose, the services are already up. Just hit the same URLs; the container logs appear in docker compose logs apisix.
6️⃣ Create Your First Route Using the Admin API
The Admin API is a simple HTTP JSON interface.
6.1. Define a Backend Service
curl -X POST http://127.0.0.1:9091/v1/services/ \
-H 'Content-Type: application/json' \
-d '{
"name": "httpbin",
"host": "httpbin.org",
"port": 80,
"path": "/"
}'
The gateway stores this definition in etcd.
6.2. Add a Route
curl -X POST http://127.0.0.1:9091/v1/routes/ \
-H 'Content-Type: application/json' \
-d '{
"uri": "/echo",
"methods": ["GET"],
"service_id": "httpbin"
}'
Now forward /echo to httpbin.org/get:
curl http://127.0.0.1:9080/echo
You’ll see the JSON response from httpbin.
7️⃣ Add a Rate‑Limiting Plugin
curl -X PATCH http://127.0.0.1:9091/v1/routes/<route-id> \
-H 'Content-Type: application/json' \
-d '{
"plugins": {
"limit-req": {
"rate": 0.5, # 5 requests per 10 seconds
"burst": 1
}
}
}'
Use curl http://127.0.0.1:9091/v1/routes?skip=0&limit=100 to list routes and find the exact route-id.
Test the limit:
for i in {1..6}; do
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9080/echo
done
The sixth request should return 429 Too Many Requests.
8️⃣ Debugging & Logging
Local runs emit logs in logs/access.log and logs/error.log. To enable more detail, edit conf/config.yaml:
log:
level: debug
In Docker, stdout shows both access and error entries by default.
9️⃣ CI/CD Deployment (Optional)
Store JSON definitions in Git and push them to etcd via a pipeline. A minimal GitHub Actions example:
name: Deploy APISIX Config
on:
push:
paths:
- 'config/*.json'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Push to etcd
env:
ETCD_ENDPOINT: https://etcd.mycompany.com:2379
run: |
for f in config/*.json; do
curl -X PUT \
"${ETCD_ENDPOINT}/v3/keys/apisix/${f%.*}" \
-d "$(cat $f)"
done
🎉 What You’ve Done
- Installed Apache Apisix (binary, source, or Docker).
- Hooked it up to an etcd backend.
- Created a pass‑through route to an external API.
- Secured that route with a rate‑limit plugin.
- Learned where to look for logs and how to raise verbosity.
Next steps? Dive into authentication (JWT, OAuth2), traffic shaping for canary releases, or build your own Lua/Go plugin. The gateway is ready for anything you need.
📚 Further Reading
- Official docs: https://apisix.apache.org/docs/
- Plugin catalog: https://apisix.apache.org/docs/3.0/apisix/plugin/
- Get help in Slack: https://apache.org/apisix/slack
