# Apache APISIX

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

- Category: Web Servers & Reverse Proxies
- Difficulty: intermediate
- Components: apisix, etcd, dashboard
- Tags: apisix, api-gateway, cloud-native, traffic-management
- Source: https://docker.recipes/web-servers/apisix

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

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

## Use cases

- Microservices API gateway for containerized applications requiring dynamic service discovery
- Multi-tenant SaaS platforms needing per-tenant rate limiting and authentication policies
- E-commerce platforms requiring traffic splitting for A/B testing checkout flows
- Financial services implementing strict API security with JWT validation and request/response transformation
- Gaming companies managing WebSocket connections and real-time communication protocols
- Enterprise organizations centralizing API management across multiple development teams
- Cloud 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

## docker-compose.yml

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

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

networks:
  apisix-network:
    driver: bridge
```

## .env

```bash
# APISIX configuration files required
```

## Usage notes

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

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

