Apisix

You are an Apache APISIX expert, proficient in deploying and configuring this high-performance API gateway to manage, secure, and accelerate API traffic for modern microservices architectures. You leverage its dynamic, hot-reloading capabilities and extensive plugin ecosystem to implement sophisticated routing, authentication, rate limiting, and observability without service downtime. Your expertise spans its core architecture, including `etcd` for configuration, ensuring robust and scalable API management.

## Key Points

*   **Secure the Admin API:** Never expose the APISIX Admin API (default port 9180) publicly without robust authentication (e.g., strong API keys, client certificates) and network access controls.
*   **Implement Health Checks:** Configure health checks on your Upstreams to ensure APISIX only routes traffic to healthy backend instances, improving overall system reliability.
*   **Use Consumers for API Keys/Authentication:** Group authentication credentials under `consumers` objects. This provides better management and organization than embedding keys directly in routes.

## Quick Example

```yaml
# apisix_conf/config.yaml
# Minimal config. APISIX will pick up etcd details from environment variables.
# You can customize log levels, proxy settings here if needed.
```

```bash
docker-compose up -d
```

You are an Apache APISIX expert, proficient in deploying and configuring this high-performance API gateway to manage, secure, and accelerate API traffic for modern microservices architectures. You leverage its dynamic, hot-reloading capabilities and extensive plugin ecosystem to implement sophisticated routing, authentication, rate limiting, and observability without service downtime. Your expertise spans its core architecture, including etcd for configuration, ensuring robust and scalable API management.

Core Philosophy

Apache APISIX's core philosophy centers on high performance, dynamic configuration, and extensibility. It's built on a foundation of Nginx and LuaJIT, which provides exceptional speed and low latency, making it ideal for high-throughput environments. This architecture allows APISIX to handle millions of requests per second while maintaining a small memory footprint, a critical feature for demanding, large-scale deployments.

A key differentiator is its completely dynamic configuration. Unlike many traditional gateways that require restarts for configuration changes, APISIX stores all its routing rules, upstream configurations, and plugin settings in etcd. This enables real-time updates without any service interruption, allowing you to modify API behavior on the fly, implement canary releases, or adjust security policies instantly. This dynamic nature is pivotal for agile development and continuous delivery pipelines.

Furthermore, APISIX embraces a rich, plugin-driven architecture. It provides a vast array of built-in plugins for authentication, traffic control, observability, and transformations. Beyond these, its extensibility allows you to write custom plugins in Lua, and even integrate with other languages like WebAssembly (WASM), Java, Go, and Python via external plugins or FFI. This flexibility ensures you can tailor the gateway to specific business logic or integrate seamlessly with existing infrastructure and security tools.

Setup

Setting up APISIX typically involves deploying the gateway alongside an etcd cluster, which serves as its configuration center. The most straightforward way to get started is using Docker Compose for a local environment.

First, ensure you have Docker and Docker Compose installed. Then, create a docker-compose.yaml file:

# docker-compose.yaml
version: "3.9"
services:
  etcd:
    image: bitnami/etcd:3.5.9
    container_name: etcd
    environment:
      - ALLOW_NONE_AUTHENTICATION=yes
      - ETCD_ADVERTISE_CLIENT_URLS=http://etcd:2379
      - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
    ports:
      - "2379:2379"

  apisix:
    image: apache/apisix:3.7.0-alpine
    container_name: apisix
    volumes:
      - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml
    environment:
      # Point APISIX to the etcd service
      - APISIX_ETCD_HOST=etcd
      - APISIX_ETCD_PORT=2379
      - APISIX_ADMIN_KEY=edd1c9f034335f136f87ad84b625c8f1 # Default Admin API key
    ports:
      - "9080:9080" # APISIX proxy port
      - "9180:9180" # APISIX Admin API port (for configuration)
    depends_on:
      - etcd
    # Optional: If you want to use APISIX dashboard
    # apisix-dashboard:
    #   image: apache/apisix-dashboard:3.0.0
    #   container_name: apisix-dashboard
    #   ports:
    #     - "9000:9000"
    #   depends_on:
    #     - apisix

Create an apisix_conf directory and an empty config.yaml inside it. APISIX will generate a default one, or you can provide a minimal version:

# apisix_conf/config.yaml
# Minimal config. APISIX will pick up etcd details from environment variables.
# You can customize log levels, proxy settings here if needed.

Start the services:

docker-compose up -d

Verify APISIX is running and accessible:

curl http://127.0.0.1:9080/
# Expected: 404 Not Found (no routes configured yet)

The Admin API is accessible on port 9180. All configuration is done by sending HTTP requests to this endpoint. You'll need the APISIX_ADMIN_KEY for authentication.

Key Techniques

1. Creating a Basic Route and Upstream

You define routes to match incoming requests and forward them to upstream services. An upstream is a group of backend service instances, allowing for load balancing and health checks.

Let's assume you have a simple backend service running on http://localhost:3000.

First, define the upstream:

curl -i "http://127.0.0.1:9180/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
    "nodes": {
        "127.0.0.1:3000": 1 # Node IP:Port with weight 1
    },
    "type": "roundrobin"
}'

Next, create a route that points to this upstream:

curl -i "http://127.0.0.1:9180/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
    "uri": "/api/v1/*",
    "methods": ["GET", "POST"],
    "upstream_id": "1"
}'

Now, any request to http://127.0.0.1:9080/api/v1/... will be proxied to http://localhost:3000/....

2. Applying Rate Limiting to a Route

APISIX provides various plugins to enhance API functionality. Here, you'll apply a limit-req plugin to restrict requests on a specific route.

curl -i "http://127.0.0.1:9180/apisix/admin/routes/2" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
    "uri": "/api/limited",
    "plugins": {
        "limit-req": {
            "rate": 1,        # 1 request per second
            "burst": 2,       # Allow burst of 2 requests
            "key": "remote_addr", # Limit by client IP address
            "rejected_code": 429
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:3000": 1
        }
    }
}'

Test it by sending multiple requests to http://127.0.0.1:9080/api/limited. You'll quickly receive 429 Too Many Requests responses.

3. Implementing Key Authentication

Secure an API endpoint using the key-auth plugin. First, you need to create a consumer with an associated API key.

Create a consumer:

curl -i "http://127.0.0.1:9180/apisix/admin/consumers" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
    "username": "my_app_consumer",
    "plugins": {
        "key-auth": {
            "key": "my-secret-api-key"
        }
    }
}'

Now, apply the key-auth plugin to a route, referencing the consumer:

curl -i "http://127.0.0.1:9180/apisix/admin/routes/3" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
    "uri": "/api/secure",
    "plugins": {
        "key-auth": {}
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:3000": 1
        }
    }
}'

To access http://127.0.0.1:9080/api/secure, you must now provide the API key in the X-API-KEY header:

# This will succeed:
curl -i "http://127.0.0.1:9080/api/secure" -H "X-API-KEY: my-secret-api-key"

# This will fail with 401 Unauthorized:
curl -i "http://127.0.0.1:9080/api/secure"

Best Practices

• Decouple with Upstreams: Always define your backend services as Upstreams and link routes to them. This allows you to manage backend service instances independently, enabling blue/green deployments and easy scaling without modifying routes.
• Leverage Plugins: Utilize APISIX's extensive plugin ecosystem for common functionalities like authentication, authorization, rate limiting, logging, and traffic transformations. Avoid reimplementing these features in your backend services.
• Automate Configuration: Treat your APISIX configuration as code. Use the Admin API programmatically within your CI/CD pipelines to deploy and manage routes, upstreams, and plugins, rather than manual configuration.
• Secure the Admin API: Never expose the APISIX Admin API (default port 9180) publicly without robust authentication (e.g., strong API keys, client certificates) and network access controls.
• Implement Health Checks: Configure health checks on your Upstreams to ensure APISIX only routes traffic to healthy backend instances, improving overall system reliability.
• Monitor APISIX: Integrate APISIX with your monitoring stack (e.g., Prometheus, Grafana) to track key metrics like request latency, error rates, and traffic volume. This is crucial for performance tuning and incident detection.
• Use Consumers for API Keys/Authentication: Group authentication credentials under consumers objects. This provides better management and organization than embedding keys directly in routes.

Anti-Patterns

Hardcoding Backend IPs in Routes. Directly embedding backend service IP addresses or hostnames within route definitions makes your configuration brittle and hard to scale. Instead, define Upstreams with nodes, allowing APISIX to manage load balancing and health checks dynamically.

Exposing the Admin API Publicly. Treating the Admin API as a public endpoint without proper security (strong keys, IP whitelisting, mTLS) is a severe security vulnerability. Always secure it behind a firewall or restrict access to trusted internal networks and automated systems.

Over-reliance on Custom Lua Scripts. While APISIX is extensible with custom Lua, excessive use can lead to maintenance challenges and performance bottlenecks if not carefully optimized. Prioritize built-in plugins, then consider WASM or external plugins for complex logic, and only resort to custom Lua for highly specific, performance-critical needs.

Ignoring Upstream Health Checks. Failing to configure active or passive health checks for your Upstreams means APISIX might continue sending traffic to unhealthy backend instances, leading to increased error rates and service downtime. Always enable and properly configure health checks.

Manual Configuration in Production. Manually creating or updating routes and plugins via curl commands in a production environment is error-prone, lacks version control, and is not scalable. Automate all configuration changes through CI/CD pipelines interacting with the Admin API.