Apache APISIX Cloudron Package - Build Notes

Overview

This document outlines the steps and considerations for packaging Apache APISIX for the Cloudron platform.

Package Components

CloudronManifest.json: Defines application metadata, addons (etcd), and environment variables.
Dockerfile: Builds the APISIX container image based on apache/apisix:3.6.0-debian.
start.sh: Script to dynamically configure APISIX and start the service.
logo.png: Application icon.

Configuration Details

Admin API Key

The APISIX Admin API key is securely managed using Cloudron's secret mechanism. The CLOUDRON_APP_SECRET environment variable is used to inject a unique, strong key into APISIX's config.yaml at startup. This replaces the default changeme value.

To access the Admin API:

Retrieve the CLOUDRON_APP_SECRET from your Cloudron instance's environment variables for the APISIX app.
Use this key in the X-API-KEY header when making requests to the APISIX Admin API (e.g., http://your-domain/apisix/admin).

Etcd Integration

APISIX is configured to use Cloudron's managed etcd addon. The start.sh script dynamically sets the etcd host and port using CLOUDRON_ETCD_HOST and CLOUDRON_ETCD_PORT environment variables.

Health Check

Cloudron's health check for the APISIX application is currently configured to probe the /health path. While APISIX primarily uses its Control API (/v1/healthcheck) for monitoring upstream services, /health is a common convention for application liveness probes. If issues arise with Cloudron's health monitoring, further investigation into a more specific APISIX health endpoint or a custom health check script may be required.

Local Testing

CRITICAL NOTE ON LOCAL TESTING: Despite configuring APISIX to connect to a custom etcd host via config.yaml and environment variables, the apache/apisix:3.6.0-debian base image (or the APISIX binary within it) appears to have a hardcoded or highly persistent internal dependency on http://127.0.0.1:2379 for etcd connectivity.

Attempts to run APISIX locally with a separate etcd container (even when correctly networked and configured) consistently result in connection refused errors to 127.0.0.1:2379 and all etcd nodes are unavailable messages. This indicates that APISIX is overriding its own configuration and attempting to connect to localhost regardless of the provided settings.

Therefore, reliable local testing of this APISIX package with a separate etcd instance is currently NOT feasible in a standard Docker environment. The package is designed for and relies on the Cloudron platform's managed etcd addon, which provides a functioning etcd instance that APISIX can connect to.

To test the package locally (requires a running etcd instance accessible at localhost:2379):

Build the Docker image:

docker build -t cloudron-apisix:latest CloudronPackages/APISIX/

Run the container (with mock etcd environment variables):
```
docker run -it --rm -p 9080:9080 -p 9443:9443 \
  -e CLOUDRON_ETCD_HOST=localhost -e CLOUDRON_ETCD_PORT=2379 \
  -e CLOUDRON_APP_SECRET=your_test_admin_key \
  cloudron-apisix:latest
```
Note: Replace localhost and 2379 with actual etcd host/port if running a local etcd instance. your_test_admin_key should be a temporary key for local testing.
Verify APISIX status (once running):
```
curl -i http://localhost:9080/status
```

Test Admin API (replace with your test key):

curl -i -X GET "http://localhost:9080/apisix/admin/routes" -H "X-API-KEY: your_test_admin_key"

Known Issues / Limitations

Local standalone testing without a dedicated etcd instance is difficult due to APISIX's inherent design and apparent hardcoded etcd dependency.
The /health endpoint for Cloudron's health check might not be ideal for APISIX's internal state. Monitor closely.

3.9 KiB Raw Permalink Blame History