# Apache APISIX Gateway

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

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: apisix, apisix-dashboard, etcd, prometheus, grafana
- Tags: apisix, api-gateway, cloud-native, etcd, plugins
- Source: https://docker.recipes/devops/apisix-gateway-stack

## 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.

## 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

## Use cases

- Microservices API gateway for Kubernetes clusters requiring dynamic service routing and plugin-based traffic policies
- Multi-tenant SaaS platforms needing per-tenant rate limiting, authentication, and custom routing logic
- E-commerce platforms implementing A/B testing, canary deployments, and traffic splitting for new features
- Enterprise API management with centralized logging, metrics collection, and security policy enforcement
- Edge computing deployments requiring lightweight, high-performance traffic management with real-time configuration updates
- Development environments needing rapid API prototyping, mock responses, and traffic simulation capabilities
- Legacy 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    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:
    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:
    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

volumes:
  etcd_data:
  prometheus_data:
  grafana_data:

networks:
  apisix-net:
    driver: bridge
```

## .env

```bash
# Grafana
GRAFANA_PASSWORD=secure_grafana_password

# APISIX Dashboard Credentials
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=admin
```

## Usage notes

- APISIX Gateway at http://localhost:9080
- Dashboard at http://localhost:9000
- Default login: admin / admin
- Supports 80+ plugins out of box

## 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

