Keal
Keal is the control plane for a data centre: it manages the VMs, storage and networks of an engine and the compute nodes it boots. It has a FastAPI backend, a plain HTML and JavaScript UI, a REST API and a command-line client.
What is where
| Path | What it holds |
|---|---|
api/ |
The FastAPI application — routers under api/v1/routers, the UI under api/v1/static |
core/ |
Shared Python: config, ticket auth, and the wrapper that calls the Perl backend |
cgi/ |
Keal's own copy of the Perl resource scripts |
piston/ |
The script that keeps the registers a node's report writes to |
support/ |
What runs beside the API: the privileged helper, engine set-up, the node agent, the workers such as steamExec, and the database schema |
cli/keal |
The keal command-line client |
api/v1/docs/ |
This handbook |
How a request is served
Keal does not talk to libvirt or MySQL directly. Every operation goes through
the Perl resource scripts in cgi/, run as command-line programs rather than
over HTTP. They hold the business logic, the permission model and the database
schema.
The practical consequence: a change to how something behaves usually belongs in
cgi/, while a change to how it is exposed belongs in api/v1/routers/.
Authentication
Keal owns identity itself. Apache is a TLS-terminating reverse proxy for this
vhost and performs no authentication — there is no Require valid-user and no
REMOTE_USER injection. Keal validates the mod_auth_tkt ticket cookie
directly, in core/auth_tkt.py, and api/deps.py's get_current_user is what
every route depends on to resolve the acting user.
The same shared TKTAuthSecret is what lets backend processes prove themselves
when they push events back in — see Events.
Two copies of the scripts, one database
The engine's base install keeps a copy of the resource scripts of its own,
which its background workers - pressurecontrol, and the scheduled steamExec
jobs - still run. Keal runs its own copy in cgi/. The two share the MySQL
register, so both see the same VMs and images.
Code is per-copy, data is shared
A long job the base install's workers finish runs in their copy, not in
Keal's. That is why both copies have to be able to report events, and why a
change made only in cgi/ may not affect work that starts elsewhere. Compute
nodes report to Keal itself, so what they say is handled by Keal's copy.