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

APISIX Cloudron Package

DEPLOYED: https://apigw.knownelement.com (production Cloudron, 2026-09-07)

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.

Package design

• Base image: apache/apisix:3.18.0-debian (pinned by tag AND digest).
• Embedded etcd: Cloudron has no etcd addon, so a single-node etcd (copied from quay.io/coreos/etcd v3.5.33, digest-pinned) runs inside the container, state under /app/data/etcd. This keeps the Admin API and dynamic routes available with zero platform dependencies.
• Read-only rootfs ready: Cloudron 8 mounts app root filesystems read-only. start.sh relocates the APISIX runtime tree (CLI, deps, generated config.yaml, nginx.conf, logs, sockets) to /app/data/apisix via APISIX_PREFIX and a path-patched CLI copy.
• Ports: only the proxy port (9080) is served; Cloudron terminates TLS and proxies https://apigw.knownelement.com to it. In-container TLS is disabled.

Authentication / admin access

The Admin API listens on 127.0.0.1:9180 only - it is never published. It is protected by a random 64-hex-char key persisted at /app/data/.admin_key (rotating it invalidates automation clients).

Operate the gateway from the host (or any admin shell):

# read the admin key
cloudron exec -a apigw.knownelement.com cat /app/data/.admin_key

# example: list routes (from inside the app container)
cloudron exec -a apigw.knownelement.com curl \
  -H "X-API-Key: $KEY" http://127.0.0.1:9180/apisix/admin/routes

Data-plane auth (key-auth, jwt-auth, OIDC relay, IP restriction, ...) is per-route and configured by the operator through the Admin API - the gateway itself has no user concept.

Operator notes

• Routes persist in the embedded etcd across restarts and Cloudron backups (state is under /app/data).
• Health: Cloudron's healthcheck hits / (a 404 counts as alive); /healthz returns 200 for external monitoring.
• Real client IPs are restored from the Cloudron proxy's X-Forwarded-For (RFC1918 trusted).
• etcd tuning: auto-compaction every hour keeps the embedded store small; single-node by design (gateway config is reproducible from infrastructure-as-code, not a durability concern).

Files

File	Purpose
Dockerfile	Pinned base image + etcd/etcdctl binaries + start.sh
start.sh	etcd lifecycle, config generation, health route seed
CloudronManifest.json	Package manifest (localstorage only)
sbom.cyclonedx.json	SBOM [#834] (syft, pinned container)

History

The original package (2026-09-01) used a nonexistent Cloudron "etcd addon" and an unpinned apache/apisix:latest - it could never have installed. Rewritten 2026-09-07 (embedded etcd, digest pins, read-only rootfs support) and deployed to production; see JOURNAL.md §20.