Apache APISIX

intermediate

Dynamic cloud-native API gateway with rich traffic management features.

Overview

Apache APISIX is a high-performance, cloud-native API gateway built on OpenResty and NGINX that provides dynamic routing, load balancing, and comprehensive traffic management capabilities. Originally developed by the Apache Software Foundation, APISIX distinguishes itself from traditional API gateways through its real-time configuration updates without service restarts, plugin-based architecture supporting over 80 plugins, and native support for modern protocols including gRPC, WebSocket, and HTTP/2. This Docker stack combines APISIX with etcd as the configuration store and the APISIX Dashboard for web-based management, creating a complete API gateway solution that can handle enterprise-scale traffic while maintaining sub-millisecond latency. The etcd integration enables APISIX's dynamic configuration capabilities, storing route definitions, plugin configurations, and SSL certificates in a distributed manner, while the dashboard provides an intuitive interface for managing routes, upstream services, and monitoring API performance. This combination is particularly valuable for organizations transitioning to microservices architectures, cloud-native deployments, or those requiring advanced traffic management features like canary deployments, circuit breakers, and multi-protocol support in a single, unified platform.

Key Features

Dynamic route configuration through etcd without service restarts or downtime
Built-in support for 80+ plugins including authentication, rate limiting, and observability
Multi-protocol support for HTTP/1.1, HTTP/2, gRPC, WebSocket, and TCP/UDP proxying
Advanced load balancing algorithms including consistent hashing, least connections, and weighted round-robin
Real-time metrics and monitoring with Prometheus, Grafana, and SkyWalking integrations
Canary deployment and A/B testing capabilities with traffic splitting
JWT authentication and OAuth2 support with custom claim validation
Web-based dashboard for visual route management and API analytics

Common Use Cases

1Microservices API gateway for containerized applications requiring dynamic service discovery
2Multi-tenant SaaS platforms needing per-tenant rate limiting and authentication policies
3E-commerce platforms requiring traffic splitting for A/B testing checkout flows
4Financial services implementing strict API security with JWT validation and request/response transformation
5Gaming companies managing WebSocket connections and real-time communication protocols
6Enterprise organizations centralizing API management across multiple development teams
7Cloud migration projects consolidating legacy API endpoints behind modern gateway infrastructure

Prerequisites

Docker Engine 20.10+ with Docker Compose v2 for multi-container orchestration
Minimum 1GB RAM available (512MB for etcd, 256MB for APISIX, 256MB for dashboard)
Ports 9000, 9080, 9180, and 9443 available on the host system
Basic understanding of API gateway concepts and HTTP routing principles
YAML configuration knowledge for creating APISIX config.yaml and dashboard.yaml files
SSL certificate management knowledge if enabling HTTPS endpoints

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  etcd: 
3    image: bitnami/etcd:latest
4    container_name: apisix-etcd
5    restart: unless-stopped
6    environment: 
7      ALLOW_NONE_AUTHENTICATION: "yes"
8    networks: 
9      - apisix-network
10
11  apisix: 
12    image: apache/apisix:latest
13    container_name: apisix
14    restart: unless-stopped
15    volumes: 
16      - ./apisix/config.yaml:/usr/local/apisix/conf/config.yaml:ro
17    ports: 
18      - "9080:9080"
19      - "9443:9443"
20      - "9180:9180"
21    depends_on: 
22      - etcd
23    networks: 
24      - apisix-network
25
26  dashboard: 
27    image: apache/apisix-dashboard:latest
28    container_name: apisix-dashboard
29    restart: unless-stopped
30    volumes: 
31      - ./apisix/dashboard.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro
32    ports: 
33      - "9000:9000"
34    depends_on: 
35      - apisix
36    networks: 
37      - apisix-network
38
39networks: 
40  apisix-network: 
41    driver: bridge

.env Template

.env

1# APISIX configuration files required

Usage Notes

1Docs: https://apisix.apache.org/docs/apisix/getting-started/
2Dashboard at http://localhost:9000 (default: admin/admin)
3Gateway on port 9080 (HTTP), 9443 (HTTPS)
4Admin API on port 9180 with API key authentication
5Create config.yaml and dashboard.yaml from APISIX examples
6Dynamic routing - no restart needed for config changes

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

etcd

etcd:
  image: bitnami/etcd:latest
  container_name: apisix-etcd
  restart: unless-stopped
  environment:
    ALLOW_NONE_AUTHENTICATION: "yes"
  networks:
    - apisix-network

apisix

apisix:
  image: apache/apisix:latest
  container_name: apisix
  restart: unless-stopped
  volumes:
    - ./apisix/config.yaml:/usr/local/apisix/conf/config.yaml:ro
  ports:
    - "9080:9080"
    - "9443:9443"
    - "9180:9180"
  depends_on:
    - etcd
  networks:
    - apisix-network

dashboard

dashboard:
  image: apache/apisix-dashboard:latest
  container_name: apisix-dashboard
  restart: unless-stopped
  volumes:
    - ./apisix/dashboard.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro
  ports:
    - "9000:9000"
  depends_on:
    - apisix
  networks:
    - apisix-network

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  etcd:
5    image: bitnami/etcd:latest
6    container_name: apisix-etcd
7    restart: unless-stopped
8    environment:
9      ALLOW_NONE_AUTHENTICATION: "yes"
10    networks:
11      - apisix-network
12
13  apisix:
14    image: apache/apisix:latest
15    container_name: apisix
16    restart: unless-stopped
17    volumes:
18      - ./apisix/config.yaml:/usr/local/apisix/conf/config.yaml:ro
19    ports:
20      - "9080:9080"
21      - "9443:9443"
22      - "9180:9180"
23    depends_on:
24      - etcd
25    networks:
26      - apisix-network
27
28  dashboard:
29    image: apache/apisix-dashboard:latest
30    container_name: apisix-dashboard
31    restart: unless-stopped
32    volumes:
33      - ./apisix/dashboard.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro
34    ports:
35      - "9000:9000"
36    depends_on:
37      - apisix
38    networks:
39      - apisix-network
40
41networks:
42  apisix-network:
43    driver: bridge
44EOF
45
46# 2. Create the .env file
47cat > .env << 'EOF'
48# APISIX configuration files required
49EOF
50
51# 3. Start the services
52docker compose up -d
53
54# 4. View logs
55docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/apisix/run | bash

Troubleshooting

APISIX fails to start with 'failed to fetch data from etcd': Verify etcd container is running and accessible on apisix-network, check etcd logs for authentication errors
Dashboard shows 'Connection refused' on localhost:9000: Ensure dashboard container started after APISIX, verify dashboard.yaml contains correct APISIX admin API endpoint
Routes return 404 despite being configured: Check APISIX admin API on port 9180 is accessible, verify route configuration syntax in etcd using etcdctl
High memory usage by etcd container: Enable etcd compaction and defragmentation, consider setting ETCD_AUTO_COMPACTION_RETENTION environment variable
SSL certificate errors on port 9443: Upload certificates through dashboard or admin API, verify certificate chain completeness and private key format
Plugin configuration not taking effect: Restart APISIX container if plugin requires reload, check plugin compatibility with APISIX version, verify plugin schema validation

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

apisixetcddashboard

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download