APISIX API Gateway Configuration

Apache APISIX is a modern, open-source API gateway built on Nginx and Lua, designed for cloud-native architectures and microservices. APISIX leverages etcd for configuration management, enabling real-time updates without restarts. This guide covers installation, route and upstream configuration, plugin management, etcd integration, dashboard access, SSL setup, and authentication mechanisms.

Table of Contents

  1. Introduction to APISIX
  2. System Requirements
  3. Installation Methods
  4. Docker Compose Deployment
  5. etcd Configuration
  6. Routes Configuration
  7. Upstreams Configuration
  8. Plugin Management
  9. Dashboard Access
  10. SSL Certificate Management
  11. Authentication Plugins
  12. Admin API
  13. Troubleshooting

Introduction to APISIX

Apache APISIX provides a next-generation API gateway with:

  • Dynamic routing without restarts
  • Centralized etcd-based configuration
  • 100+ plugins for authentication, rate limiting, and transformation
  • gRPC and HTTP/3 support
  • Real-time hot reloading
  • High-performance Lua scripting
  • Kubernetes native deployment options

APISIX architecture separates data plane (gateway) from control plane (configuration), enabling scalable, flexible deployments.

System Requirements

Ensure your system meets:

  • Linux kernel 3.10 or newer
  • 1 GB RAM minimum (2 GB recommended)
  • etcd 3.4+ for distributed configuration
  • 100 MB disk space
  • Network access to backend services

Installation Methods

APISIX can be deployed via Docker Compose, package managers, or source compilation.

Docker Compose Deployment

Create a comprehensive docker-compose.yml for APISIX with etcd:

version: '3.8'

services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.13
    restart: always
    ports:
      - "2379:2379"
      - "2380:2380"
    environment:
      ETCD_LISTEN_CLIENT_URLS: http://0.0.0.0:2379
      ETCD_ADVERTISE_CLIENT_URLS: http://etcd:2379
      ETCD_LISTEN_PEER_URLS: http://0.0.0.0:2380
      ETCD_INITIAL_ADVERTISE_PEER_URLS: http://etcd:2380
      ETCD_INITIAL_CLUSTER: default=http://etcd:2380
      ETCD_INITIAL_CLUSTER_STATE: new
      ETCD_INITIAL_CLUSTER_TOKEN: etcd-cluster
    volumes:
      - etcd_data:/etcd-data

  apisix:
    image: apache/apisix:3.7-alpine
    restart: always
    ports:
      - "80:9080"
      - "443:9443"
      - "9180:9180"
    depends_on:
      - etcd
    volumes:
      - ./apisix_config.yaml:/usr/local/apisix/conf/config.yaml:ro
      - ./certs:/usr/local/apisix/conf/ssl:ro
    environment:
      APISIX_ADMIN_ALLOW_ADMIN: "true"
    command: apisix start

  apisix-dashboard:
    image: apache/apisix-dashboard:3.7-alpine
    restart: always
    ports:
      - "9000:9000"
    depends_on:
      - etcd
    environment:
      ETCD_ENDPOINTS: http://etcd:2379

volumes:
  etcd_data:

networks:
  default:
    name: apisix_network

Deploy the stack:

docker-compose up -d

Verify APISIX is running:

curl http://localhost:9180/apisix/admin/version

etcd Configuration

APISIX uses etcd as the configuration store. Configure etcd endpoint in APISIX config:

Create apisix_config.yaml:

apisix:
  node_listen: 9080
  admin_listen: 9180
  admin_api_version: v3
  enable_admin: true
  admin_key: "edd1c9f034335f136f87ad84b625c8f1"
  
  ssl:
    listen_port: 9443
    enable_http2: true

etcd:
  host:
    - "http://etcd:2379"
  prefix: /apisix
  timeout: 30
  resync_delay: 5

plugins:
  - basic-auth
  - key-auth
  - jwt-auth
  - rate-limiting
  - request-id
  - cors
  - proxy-rewrite
  - log-rotate

log_level: notice
log_format: json

Verify etcd connectivity:

curl http://localhost:2379/version

Routes Configuration

Create routes via APISIX Admin API. A route maps requests to upstreams:

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "web-route",
    "uri": "/",
    "methods": ["GET", "POST", "PUT", "DELETE"],
    "upstream_id": "web-upstream",
    "plugins": {
      "cors": {
        "allow_origins": "*",
        "allow_methods": "*",
        "allow_headers": "*",
        "expose_headers": "*",
        "max_age": 5
      }
    }
  }'

Create host-based routes:

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "api-route",
    "host": "api.example.com",
    "uri": "/api/*",
    "upstream_id": "api-upstream",
    "strip_uri": true
  }'

Create path-based routing with multiple routes:

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "blog-route",
    "host": "blog.example.com",
    "uri": "/",
    "upstream_id": "blog-upstream"
  }'

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "static-route",
    "uri": "/static/*",
    "upstream_id": "static-upstream",
    "strip_uri": true
  }'

List all routes:

curl http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Update a route:

curl -X PATCH http://localhost:9180/apisix/admin/routes/web-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{"plugins": {"request-id": {"header_name": "X-Request-ID"}}}'

Delete a route:

curl -X DELETE http://localhost:9180/apisix/admin/routes/web-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Upstreams Configuration

Upstreams define backend service pools. Create an upstream:

curl -X POST http://localhost:9180/apisix/admin/upstreams \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "web-upstream",
    "type": "roundrobin",
    "nodes": {
      "192.168.1.100:8000": 1,
      "192.168.1.101:8000": 1,
      "192.168.1.102:8000": 1
    },
    "timeout": {
      "connect": 5,
      "send": 10,
      "read": 10
    },
    "checks": {
      "active": {
        "http_path": "/health",
        "healthy": {
          "interval": 2,
          "successes": 1
        },
        "unhealthy": {
          "interval": 1,
          "http_failures": 5
        }
      }
    }
  }'

Create upstream with weighted load balancing:

curl -X POST http://localhost:9180/apisix/admin/upstreams \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "api-upstream",
    "type": "roundrobin",
    "nodes": {
      "192.168.1.110:8080": 3,
      "192.168.1.111:8080": 1
    }
  }'

Create upstream with least connection algorithm:

curl -X POST http://localhost:9180/apisix/admin/upstreams \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "blog-upstream",
    "type": "least_conn",
    "nodes": {
      "192.168.1.120:3000": 1,
      "192.168.1.121:3000": 1
    }
  }'

Plugin Management

Enable plugins globally or per-route. Enable rate limiting plugin:

curl -X POST http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "/api/*",
    "upstream_id": "api-upstream",
    "plugins": {
      "limit-count": {
        "count": 100,
        "time_window": 60,
        "policy": "local",
        "key_type": "var",
        "key": "remote_addr"
      }
    }
  }'

Enable CORS plugin:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "cors": {
        "allow_origins": "https://example.com",
        "allow_methods": "GET,POST,PUT,DELETE",
        "allow_headers": "Content-Type,Authorization",
        "expose_headers": "X-Total-Count"
      }
    }
  }'

Enable request transformation:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "proxy-rewrite": {
        "uri": "/v1",
        "headers": {
          "add": {
            "X-Custom-Header": "custom-value",
            "X-Forwarded-Proto": "https"
          }
        }
      }
    }
  }'

Dashboard Access

Access the APISIX Dashboard at http://localhost:9000

Default credentials:

  • Username: admin
  • Password: admin

Configure dashboard admin password by setting environment variables or updating configuration.

SSL Certificate Management

Upload SSL certificate via Admin API:

curl -X POST http://localhost:9180/apisix/admin/ssl \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "example-ssl",
    "cert": "'"$(cat /path/to/certificate.crt)"'",
    "key": "'"$(cat /path/to/private.key)"'",
    "sni": "example.com"
  }'

Or use curl with file content:

CERT_CONTENT=$(cat /etc/ssl/certs/example.com.crt | base64 | tr -d '\n')
KEY_CONTENT=$(cat /etc/ssl/private/example.com.key | base64 | tr -d '\n')

curl -X POST http://localhost:9180/apisix/admin/ssl \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{"id": "cert-id", "sni": "example.com", "cert": "'${CERT_CONTENT}'", "key": "'${KEY_CONTENT}'"}'

List SSL certificates:

curl http://localhost:9180/apisix/admin/ssl \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Authentication Plugins

Enable basic authentication on a route:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "basic-auth": {}
    }
  }'

Create a consumer with basic auth credentials:

curl -X POST http://localhost:9180/apisix/admin/consumers \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "app-client",
    "plugins": {
      "basic-auth": {
        "username": "api_user",
        "password": "secure_password"
      }
    }
  }'

Enable key authentication:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "key-auth": {
        "header": "X-API-Key"
      }
    }
  }'

Create API key credentials:

curl -X POST http://localhost:9180/apisix/admin/consumers/app-client/credentials \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "key-auth",
    "key": "super-secret-api-key-12345"
  }'

Enable JWT authentication:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "jwt-auth": {
        "secret": "your-jwt-secret-key"
      }
    }
  }'

Admin API

APISIX provides comprehensive Admin API for all configuration tasks:

Get APISIX version:

curl http://localhost:9180/apisix/admin/version \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Get node information:

curl http://localhost:9180/apisix/admin/nodes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Get all plugins:

curl http://localhost:9180/apisix/admin/plugins/list \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Get route details:

curl http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Troubleshooting

Check APISIX container logs:

docker-compose logs -f apisix

Verify etcd is running:

curl http://localhost:2379/version

Test API gateway connectivity:

curl -v http://localhost:80/

Check route configuration via etcd:

curl http://localhost:2379/v3/kv/range \
  -d '{"key": "L2FwaXN4L3JvdXRlcw=="}'

Verify upstream health:

curl http://localhost:9180/apisix/admin/upstreams/web-upstream \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Check for configuration errors in logs:

docker-compose logs apisix | grep -i error

Test route with authentication:

curl -H "X-API-Key: super-secret-api-key-12345" http://localhost:80/api/test

Conclusion

Apache APISIX provides a modern, cloud-native API gateway with dynamic configuration management through etcd. Its extensive plugin ecosystem, support for advanced authentication mechanisms, and real-time updates without restarts make it ideal for microservices architectures. The combination of powerful Admin API and web dashboard enables flexible management of complex API traffic routing and transformation requirements.