diff --git a/Package-Workspace/API-Gateway/apisix/CHANGELOG.md b/Package-Workspace/API-Gateway/apisix/CHANGELOG.md new file mode 100644 index 0000000..adaa9da --- /dev/null +++ b/Package-Workspace/API-Gateway/apisix/CHANGELOG.md @@ -0,0 +1,21 @@ +# Changelog + +## [3.12.0] - 2025-01-24 + +### Added +- Initial Cloudron package for APISIX +- Official Apache APISIX Docker image wrapper +- Automatic etcd configuration via Cloudron addon +- Admin API key configuration +- Health check endpoint +- Documentation with usage examples +- Architecture diagram + +### Features +- Multi-protocol support (HTTP/HTTPS, TCP/UDP, Dubbo, MQTT, gRPC, WebSocket) +- Dynamic configuration without restarts +- Load balancing with multiple strategies +- Rich plugin ecosystem (100+ plugins) +- Security features (IP restrictions, JWT, API Key auth) +- Traffic management (rate limiting, circuit breaking, canary releases) +- AI Gateway capabilities for LLM proxying diff --git a/Package-Workspace/API-Gateway/apisix/CloudronManifest.json b/Package-Workspace/API-Gateway/apisix/CloudronManifest.json new file mode 100644 index 0000000..37154b3 --- /dev/null +++ b/Package-Workspace/API-Gateway/apisix/CloudronManifest.json @@ -0,0 +1,41 @@ +{ + "version": 1, + "manifestVersion": 2, + "type": "app", + "id": "io.cloudron.apisix", + "title": "APISIX", + "description": "Apache APISIX is a dynamic, real-time, high-performance API Gateway. Provides rich traffic management features like load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability and more.", + "author": "Apache APISIX", + "website": "https://apisix.apache.org", + "contactEmail": "cloudron@tsys.dev", + "tagline": "Cloud-native, high-performance API gateway", + "version": "3.12-latest", + "healthCheckPath": "/apisix/admin/routes", + "httpPort": 9180, + "memoryLimit": 1024, + "addons": { + "localstorage": true, + "etcd": { + "version": "3.4" + } + }, + "tcpPorts": { + "ADMIN_PORT": { + "description": "APISIX Admin API port", + "defaultValue": 9180 + }, + "HTTP_PORT": { + "description": "APISIX HTTP proxy port", + "defaultValue": 9080 + }, + "HTTPS_PORT": { + "description": "APISIX HTTPS proxy port", + "defaultValue": 9443 + } + }, + "mediaLinks": [ + "https://raw.githubusercontent.com/apache/apisix/master/logos/apache-apisix.png" + ], + "changelog": "Initial Cloudron package for APISIX API Gateway", + "icon": "file://logo.png" +} diff --git a/Package-Workspace/API-Gateway/apisix/Dockerfile b/Package-Workspace/API-Gateway/apisix/Dockerfile new file mode 100644 index 0000000..c8e957c --- /dev/null +++ b/Package-Workspace/API-Gateway/apisix/Dockerfile @@ -0,0 +1,7 @@ +FROM apache/apisix:latest + +# Copy start script (already executable from host) +COPY start.sh /start.sh + +# Start APISIX +CMD ["/start.sh"] diff --git a/Package-Workspace/API-Gateway/apisix/README.md b/Package-Workspace/API-Gateway/apisix/README.md new file mode 100644 index 0000000..c7a2d62 --- /dev/null +++ b/Package-Workspace/API-Gateway/apisix/README.md @@ -0,0 +1,188 @@ +# 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) diff --git a/Package-Workspace/API-Gateway/apisix/config.yaml.example b/Package-Workspace/API-Gateway/apisix/config.yaml.example new file mode 100644 index 0000000..4332f12 --- /dev/null +++ b/Package-Workspace/API-Gateway/apisix/config.yaml.example @@ -0,0 +1,95 @@ +# APISIX Configuration Sample +# This file is automatically generated by Cloudron package +# Located at: /usr/local/apisix/conf/config.yaml + +deployment: + role: traditional + role_traditional: + config_provider: etcd + + admin: + # Admin API port + port: 9180 + + # Allow admin access from all IPs + # Restrict this in production to specific IPs + allow_admin: + - 0.0.0.0/0 + + # Admin API key (CHANGE THIS IN PRODUCTION) + admin_key: + - admin-key-secret-change-me + + # Admin API version + admin_api_version: v3 + + etcd: + # Etcd hosts (automatically configured by Cloudron) + host: + - 127.0.0.1 + port: 2379 + prefix: "/apisix" + timeout: 30 + + apisix: + # SSL configuration + ssl: + ssl_trusted_certificate: /etc/ssl/certs/ca-certificates.crt + ssl_protocols: "TLSv1.2 TLSv1.3" + + # Main HTTP proxy port + node_listen: 9080 + + # Disable IPv6 + enable_ipv6: false + + # Enable CORS for admin API + enable_admin_cors: true + + # Enable HTTP/2 + enable_http2: true + + # Nginx configuration + nginx_config: + # Error log file + error_log: "logs/error.log" + error_log_level: "warn" + + # Worker processes + worker_processes: auto + + # Maximum open files + worker_rlimit_nofile: 20480 + + # Event worker processes + event_worker_processes: 2 + + # Worker shutdown timeout + worker_shutdown_timeout: 240s + +# Additional configuration options: +# +# Plugin configuration (default plugins enabled) +# plugins: +# - real-ip +# - proxy-rewrite +# - limit-req +# - limit-conn +# - prometheus +# - node-status +# - jwt-auth +# - key-auth +# - basic-auth +# - ip-restriction +# - cors +# - proxy-cache +# - limit-count +# - request-id +# - fault-injection +# - consumer +# +# Stream plugins (for TCP/UDP): +# stream_plugins: +# - mqtt-proxy +# - ip-restriction +# - limit-conn diff --git a/Package-Workspace/API-Gateway/apisix/logo.png b/Package-Workspace/API-Gateway/apisix/logo.png new file mode 100644 index 0000000..6e3aefc Binary files /dev/null and b/Package-Workspace/API-Gateway/apisix/logo.png differ diff --git a/Package-Workspace/API-Gateway/apisix/start.sh b/Package-Workspace/API-Gateway/apisix/start.sh new file mode 100755 index 0000000..f151760 --- /dev/null +++ b/Package-Workspace/API-Gateway/apisix/start.sh @@ -0,0 +1,69 @@ +#!/bin/bash + +set -e + +# Cloudron etcd connection +ETCD_HOST=${CLOUDRON_ETCD_HOST:-127.0.0.1} +ETCD_PORT=${CLOUDRON_ETCD_PORT:-2379} + +echo "Etcd host: $ETCD_HOST" +echo "Etcd port: $ETCD_PORT" + +# Wait for etcd to be ready +echo "Waiting for etcd to be ready..." +MAX_WAIT=30 +WAIT_TIME=0 +while ! curl -f "http://${ETCD_HOST}:${ETCD_PORT}/health" 2>/dev/null; do + if [ $WAIT_TIME -ge $MAX_WAIT ]; then + echo "Timeout waiting for etcd" + exit 1 + fi + echo "Etcd is unavailable - sleeping ($WAIT_TIME/$MAX_WAIT)" + sleep 2 + WAIT_TIME=$((WAIT_TIME+2)) +done + +echo "Etcd is ready!" + +# Create APISIX configuration file +cat > /usr/local/apisix/conf/config.yaml << 'EOF' +deployment: + role: traditional + role_traditional: + config_provider: etcd + admin: + port: 9180 + allow_admin: + - 0.0.0.0/0 + admin_key: + - ${ADMIN_KEY:-admin-key-secret-change-me} + admin_api_version: v3 + etcd: + host: + - ${ETCD_HOST} + port: ${ETCD_PORT} + prefix: "/apisix" + timeout: 30 + apisix: + ssl: + ssl_trusted_certificate: /etc/ssl/certs/ca-certificates.crt + ssl_protocols: "TLSv1.2 TLSv1.3" + node_listen: 9080 + enable_ipv6: false + enable_admin_cors: true + enable_http2: true + nginx_config: + error_log: "logs/error.log" + error_log_level: "warn" + worker_processes: auto + worker_rlimit_nofile: 20480 + event_worker_processes: 2 + worker_shutdown_timeout: 240s +EOF + +echo "APISIX configuration created at /usr/local/apisix/conf/config.yaml" +cat /usr/local/apisix/conf/config.yaml + +# Start APISIX +echo "Starting APISIX..." +exec /usr/bin/apisix start