docker.recipes

Apache APISIX Gateway

advanced

Cloud-native API gateway with APISIX, etcd backend, Dashboard UI, and Grafana monitoring.

Overview

Apache APISIX is a cloud-native, high-performance API gateway built on OpenResty/Nginx and etcd. Launched by the Apache Software Foundation, APISIX provides dynamic routing, load balancing, and comprehensive plugin ecosystem with over 80 plugins for authentication, security, observability, and traffic management. Unlike traditional API gateways that require restarts for configuration changes, APISIX offers hot-reloading capabilities and real-time configuration updates through its etcd backend. This production-grade stack combines APISIX's core gateway functionality with etcd for distributed configuration storage, the APISIX Dashboard for web-based management, Prometheus for metrics collection, and Grafana for visualization. The etcd cluster serves as APISIX's control plane, storing route configurations, plugin settings, and upstream definitions with strong consistency guarantees. Prometheus scrapes metrics from APISIX's built-in metrics endpoint, while Grafana provides rich dashboards for monitoring API traffic, latency, error rates, and plugin performance. This configuration targets platform engineers, API architects, and DevOps teams building microservices infrastructures that require dynamic traffic management, comprehensive observability, and plugin-based extensibility. The stack excels in environments demanding frequent routing changes, A/B testing capabilities, and granular traffic control without service interruptions.

Key Features

  • Dynamic routing and upstream management without gateway restarts through etcd-based configuration
  • 80+ built-in plugins including JWT authentication, rate limiting, circuit breakers, and custom Lua scripting
  • Real-time traffic splitting and canary deployments with percentage-based routing rules
  • APISIX Dashboard web interface for visual route management, plugin configuration, and upstream health monitoring
  • Native Prometheus metrics export with detailed API gateway performance, plugin execution times, and traffic patterns
  • etcd clustering for high availability configuration storage with automatic leader election and data replication
  • WebSocket and gRPC protocol support alongside traditional HTTP/HTTPS with SSL termination
  • Built-in service discovery integration with Consul, DNS, and Kubernetes for automatic upstream detection

Common Use Cases

  • 1Microservices API gateway for Kubernetes clusters requiring dynamic service routing and plugin-based traffic policies
  • 2Multi-tenant SaaS platforms needing per-tenant rate limiting, authentication, and custom routing logic
  • 3E-commerce platforms implementing A/B testing, canary deployments, and traffic splitting for new features
  • 4Enterprise API management with centralized logging, metrics collection, and security policy enforcement
  • 5Edge computing deployments requiring lightweight, high-performance traffic management with real-time configuration updates
  • 6Development environments needing rapid API prototyping, mock responses, and traffic simulation capabilities
  • 7Legacy system modernization providing API abstraction layer with gradual migration support and traffic mirroring

Prerequisites

  • Minimum 2GB RAM (APISIX: 512MB, etcd: 512MB, Grafana: 512MB, Prometheus: 1GB for metrics retention)
  • Docker Engine 20.10+ and Docker Compose 2.0+ with overlay network support for multi-container communication
  • Available ports 9080, 9443, 9000, 9090, 3000 for APISIX gateway, dashboard, and monitoring interfaces
  • Basic understanding of API gateway concepts, REST routing, and plugin-based architecture patterns
  • Familiarity with YAML configuration syntax for APISIX routes, upstreams, and plugin definitions
  • Knowledge of PromQL query language for creating custom Grafana dashboards and Prometheus alerting rules

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

docker-compose.yml

docker-compose.yml
1services: 
2  apisix: 
3    image: apache/apisix:latest
4    ports: 
5      - "9080:9080"
6      - "9443:9443"
7      - "9091:9091"
8      - "9092:9092"
9    volumes: 
10      - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
11    depends_on: 
12      - etcd
13    networks: 
14      - apisix-net
15    restart: unless-stopped
16
17  etcd: 
18    image: bitnami/etcd:latest
19    environment: 
20      ETCD_ENABLE_V2: "true"
21      ALLOW_NONE_AUTHENTICATION: "yes"
22      ETCD_ADVERTISE_CLIENT_URLS: http://etcd:2379
23      ETCD_LISTEN_CLIENT_URLS: http://0.0.0.0:2379
24    volumes: 
25      - etcd_data:/bitnami/etcd
26    networks: 
27      - apisix-net
28    restart: unless-stopped
29
30  apisix-dashboard: 
31    image: apache/apisix-dashboard:latest
32    ports: 
33      - "9000:9000"
34    volumes: 
35      - ./dashboard_conf/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro
36    depends_on: 
37      - apisix
38    networks: 
39      - apisix-net
40    restart: unless-stopped
41
42  prometheus: 
43    image: prom/prometheus:latest
44    ports: 
45      - "9090:9090"
46    volumes: 
47      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
48      - prometheus_data:/prometheus
49    networks: 
50      - apisix-net
51    restart: unless-stopped
52
53  grafana: 
54    image: grafana/grafana:latest
55    ports: 
56      - "3000:3000"
57    environment: 
58      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
59    volumes: 
60      - grafana_data:/var/lib/grafana
61    networks: 
62      - apisix-net
63    restart: unless-stopped
64
65volumes: 
66  etcd_data: 
67  prometheus_data: 
68  grafana_data: 
69
70networks: 
71  apisix-net: 
72    driver: bridge

.env Template

.env
1# Grafana
2GRAFANA_PASSWORD=secure_grafana_password
3
4# APISIX Dashboard Credentials
5DASHBOARD_USERNAME=admin
6DASHBOARD_PASSWORD=admin

Usage Notes

  1. 1APISIX Gateway at http://localhost:9080
  2. 2Dashboard at http://localhost:9000
  3. 3Default login: admin / admin
  4. 4Supports 80+ plugins out of box

Individual Services(5 services)

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

apisix
apisix:
  image: apache/apisix:latest
  ports:
    - "9080:9080"
    - "9443:9443"
    - "9091:9091"
    - "9092:9092"
  volumes:
    - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
  depends_on:
    - etcd
  networks:
    - apisix-net
  restart: unless-stopped
etcd
etcd:
  image: bitnami/etcd:latest
  environment:
    ETCD_ENABLE_V2: "true"
    ALLOW_NONE_AUTHENTICATION: "yes"
    ETCD_ADVERTISE_CLIENT_URLS: http://etcd:2379
    ETCD_LISTEN_CLIENT_URLS: http://0.0.0.0:2379
  volumes:
    - etcd_data:/bitnami/etcd
  networks:
    - apisix-net
  restart: unless-stopped
apisix-dashboard
apisix-dashboard:
  image: apache/apisix-dashboard:latest
  ports:
    - "9000:9000"
  volumes:
    - ./dashboard_conf/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro
  depends_on:
    - apisix
  networks:
    - apisix-net
  restart: unless-stopped
prometheus
prometheus:
  image: prom/prometheus:latest
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    - prometheus_data:/prometheus
  networks:
    - apisix-net
  restart: unless-stopped
grafana
grafana:
  image: grafana/grafana:latest
  ports:
    - "3000:3000"
  environment:
    GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
  volumes:
    - grafana_data:/var/lib/grafana
  networks:
    - apisix-net
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  apisix:
5    image: apache/apisix:latest
6    ports:
7      - "9080:9080"
8      - "9443:9443"
9      - "9091:9091"
10      - "9092:9092"
11    volumes:
12      - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
13    depends_on:
14      - etcd
15    networks:
16      - apisix-net
17    restart: unless-stopped
18
19  etcd:
20    image: bitnami/etcd:latest
21    environment:
22      ETCD_ENABLE_V2: "true"
23      ALLOW_NONE_AUTHENTICATION: "yes"
24      ETCD_ADVERTISE_CLIENT_URLS: http://etcd:2379
25      ETCD_LISTEN_CLIENT_URLS: http://0.0.0.0:2379
26    volumes:
27      - etcd_data:/bitnami/etcd
28    networks:
29      - apisix-net
30    restart: unless-stopped
31
32  apisix-dashboard:
33    image: apache/apisix-dashboard:latest
34    ports:
35      - "9000:9000"
36    volumes:
37      - ./dashboard_conf/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro
38    depends_on:
39      - apisix
40    networks:
41      - apisix-net
42    restart: unless-stopped
43
44  prometheus:
45    image: prom/prometheus:latest
46    ports:
47      - "9090:9090"
48    volumes:
49      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
50      - prometheus_data:/prometheus
51    networks:
52      - apisix-net
53    restart: unless-stopped
54
55  grafana:
56    image: grafana/grafana:latest
57    ports:
58      - "3000:3000"
59    environment:
60      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
61    volumes:
62      - grafana_data:/var/lib/grafana
63    networks:
64      - apisix-net
65    restart: unless-stopped
66
67volumes:
68  etcd_data:
69  prometheus_data:
70  grafana_data:
71
72networks:
73  apisix-net:
74    driver: bridge
75EOF
76
77# 2. Create the .env file
78cat > .env << 'EOF'
79# Grafana
80GRAFANA_PASSWORD=secure_grafana_password
81
82# APISIX Dashboard Credentials
83DASHBOARD_USERNAME=admin
84DASHBOARD_PASSWORD=admin
85EOF
86
87# 3. Start the services
88docker compose up -d
89
90# 4. View logs
91docker 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-gateway-stack/run | bash

Troubleshooting

  • APISIX fails to start with 'etcd connection refused': Ensure etcd container is fully initialized before APISIX starts, add health check or delay
  • Dashboard shows 'failed to fetch routes' error: Verify APISIX admin API is accessible on port 9091 and admin_key matches between config files
  • 502 Bad Gateway on API requests: Check upstream service availability and ensure upstream definitions in APISIX point to correct backend services
  • Prometheus shows no APISIX metrics: Enable prometheus plugin in APISIX config.yaml and verify metrics endpoint accessibility on port 9091/apisix/prometheus/metrics
  • etcd data loss after container restart: Ensure etcd_data volume is properly mounted and ETCD_DATA_DIR environment variable points to persistent storage
  • Plugin configuration changes not taking effect: Verify etcd connectivity and check APISIX error logs for plugin validation failures or syntax errors

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

apisixapisix-dashboardetcdprometheusgrafana

Tags

#apisix#api-gateway#cloud-native#etcd#plugins

Category

DevOps & CI/CD

Related Recipes

Ad Space