TSYSDevStack-SupportStack-Cloudron/Package-Workspace/API-Gateway/apisix/README.md

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

```bash
# 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
```bash
# Test via HTTP
curl http://localhost:9080/hello

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

### 3. Add SSL Certificates
```bash
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:

```bash
# 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**:

```bash
# 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:

```bash
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](https://apisix.apache.org/docs/)
- [Admin API Reference](https://apisix.apache.org/docs/apisix/admin-api/)
- [Plugin Configuration](https://apisix.apache.org/docs/apisix/plugins/)
- [Best Practices](https://apisix.apache.org/docs/general/faq)
- [AI Gateway Guide](https://apisix.apache.org/ai-gateway/)

## 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](https://github.com/apache/apisix)
[Apache Project Page](https://apisix.apache.org/)
[Official Docker Images](https://hub.docker.com/r/apache/apisix)