TSYSDevStack-SupportStack-Cloudron/Package-Workspace/API-Gateway/apisix

APISIX Cloudron Package

Description

Apache APISIX is a dynamic, real-time, high-performance API Gateway. It provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability and more.

Features

Core Capabilities

• Dynamic Configuration: Hot updates and hot plugins without restarts
• Multi-Protocol Support: HTTP/HTTPS, TCP/UDP, Dubbo, MQTT, gRPC, WebSocket
• Load Balancing: Multiple load balancing strategies
• Security: IP restrictions, JWT authentication, API Key authentication
• Traffic Management: Rate limiting, circuit breaking, canary releases
• Observability: Prometheus metrics, distributed tracing
• AI Gateway: Support for LLM proxying and AI workloads

Gateway Features

• Proxy Rewrite (host, URI, schema, method, headers)
• Upstream Health Checks
• Request/Response Transformation
• CORS Support
• Web Application Firewall (WAF) via plugins
• OpenID Connect integration

Configuration

Etcd Connection

APISIX requires an etcd instance for configuration storage. The Cloudron package automatically configures this connection using Cloudron's etcd addon.

Environment Variables

• CLOUDRON_ETCD_HOST: Etcd host (automatically set by Cloudron)
• CLOUDRON_ETCD_PORT: Etcd port (automatically set by Cloudron)
• ADMIN_KEY: Admin API key (default: admin-key-secret-change-me, change this in production)

Ports

• 9180: Admin API port (for configuration via REST API)
• 9080: HTTP proxy port (client requests)
• 9443: HTTPS proxy port (client requests with SSL)

Usage

1. Configure Routes via Admin API

APISIX provides a RESTful Admin API for configuration:

# List all routes
curl http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: admin-key-secret-change-me'

# Create a new route
curl http://localhost:9180/apisix/admin/routes/1 \
  -H 'X-API-KEY: admin-key-secret-change-me' \
  -X PUT -d '{
    "uri": "/hello",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

2. Test the Gateway

# Test via HTTP
curl http://localhost:9080/hello

# Test via HTTPS (after configuring SSL)
curl -k https://localhost:9443/hello

3. Add SSL Certificates

curl http://localhost:9180/apisix/admin/ssls/1 \
  -H 'X-API-KEY: admin-key-secret-change-me' \
  -X PUT -d '{
    "cert": "...",
    "key": "...",
    "snis": ["example.com"]
  }'

4. Configure Plugins

APISIX supports 100+ plugins for various capabilities:

# Enable rate limiting
curl http://localhost:9180/apisix/admin/routes/1 \
  -H 'X-API-KEY: admin-key-secret-change-me' \
  -X PATCH -d '{
    "plugins": {
      "limit-count": {
        "count": 10,
        "time_window": 60,
        "rejected_code": 429
      }
    }
  }'

Security

Change Default Admin Key

The default admin key is admin-key-secret-change-me. Change this immediately after installation:

# Get current admin key from Cloudron environment
# Update in /usr/local/apisix/conf/config.yaml
# Restart APISIX

Use HTTPS in Production

Always use HTTPS (port 9443) for production deployments. Configure SSL certificates via the Admin API.

IP Restrictions

Configure IP restrictions to limit who can access the Admin API:

curl http://localhost:9180/apisix/admin/routes/1 \
  -H 'X-API-KEY: admin-key-secret-change-me' \
  -X PATCH -d '{
    "plugins": {
      "ip-restriction": {
        "whitelist": ["192.168.1.0/24"]
      }
    }
  }'

Architecture

                    ┌─────────────┐
                    │   Client    │
                    └──────┬──────┘
                           │
                           ▼
                   ┌──────────────┐
                   │   APISIX    │
                   │  (Gateway)   │
                   └──────┬──────┘
                           │
                           ▼
                   ┌──────────────┐
                   │  Upstream    │
                   │  Services    │
                   └──────────────┘

                   ┌──────────────┐
                   │    Etcd     │
                   │ (Config DB)  │
                   └──────────────┘

Documentation

For more information on configuring APISIX:

• Official Documentation
• Admin API Reference
• Plugin Configuration
• Best Practices
• AI Gateway Guide

Troubleshooting

APISIX won't start

1. Check etcd connectivity: curl http://localhost:2379/health
2. Review logs in /usr/local/apisix/logs/error.log
3. Verify configuration syntax in /usr/local/apisix/conf/config.yaml

Routes not working

1. Check Admin API key is correct
2. Verify upstream servers are accessible
3. Check firewall rules allow traffic to ports 9080/9443
4. Review route configuration via Admin API

Performance issues

1. Increase worker processes in nginx_config
2. Enable HTTP/2 for better performance
3. Consider horizontal scaling (multiple APISIX instances)

Upstream

GitHub Repository Apache Project Page Official Docker Images