63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# 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:**
|
|
1. Retrieve the `CLOUDRON_APP_SECRET` from your Cloudron instance's environment variables for the APISIX app.
|
|
2. 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`):
|
|
|
|
1. **Build the Docker image**:
|
|
```bash
|
|
docker build -t cloudron-apisix:latest CloudronPackages/APISIX/
|
|
```
|
|
2. **Run the container (with mock etcd environment variables)**:
|
|
```bash
|
|
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.*
|
|
|
|
3. **Verify APISIX status (once running)**:
|
|
```bash
|
|
curl -i http://localhost:9080/status
|
|
```
|
|
4. **Test Admin API (replace with your test key)**:
|
|
```bash
|
|
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.
|