Compatibility paths
Keal's API lives under /api/v1. A few paths outside it are answered as well,
because something that was built before Keal still asks for them by name: the
stacks' own management pages, and compute nodes that have not been reimaged.
They are listed in the API reference under compatibility. Each
is a second door to something that has a proper place under /api/v1, not an
API of its own, and each goes away once nothing calls it any more.
| Path | Who calls it | The same as |
|---|---|---|
/stabile/{package}, /stabile/{package}/{target} |
A stack, from inside its own VM | /api/v1/internal/… |
GET /stabile/networks/{uuid} |
A signed-in browser, from a stack's terminal page | /api/v1/networks/{uuid} |
/stabile/piston/piston.cgi |
A compute node that has not been reimaged | /api/v1/piston/… |
Nothing else under /stabile is answered.
Calls from inside a VM
A stack's management interface asks the engine about itself: which network it is on, which VM it is, what else is in its stack, where it may put an image. It does so from inside the VM, over the gateway address:
curl -sk https://$gw/stabile/networks/this
curl -sk "https://$gw/stabile/servers?action=getappid"
curl -sk "https://$gw/stabile/images?action=liststoragepools"
These carry no ticket. The caller is known by its address:
- it has to be one of the engine's own internal addresses;
- the network that address is on decides whose call it is — its owner's;
- that account has to have Let this account's VMs call the engine's API switched on, under API access.
That is also what gives this its meaning: the caller's own network, VM or
stack. A call from anywhere else is refused with a 403.
What is asked is the action in the query, or a plain read with none. The
method matters only in that a PUT or POST with no action is a save of the
record in its body. Only what the stacks use is let through:
| Package | Allowed |
|---|---|
networks |
read, dnscheck, dnscreate, dnsdelete, getdnsdomain |
servers |
read, save, getappid, getappinfo, setrunning, attach, detach |
systems |
read, save, buildsystem, removesystem |
images |
read, liststoragepools, activate, sync_save, publish, release, linkmaster |
users |
read, me, listids |
Anything else is refused before it reaches the backend, so this is not a way
around the rest of the API. New stacks should call /api/v1/internal/…, which
is the same thing at Keal's own path.
A network, for the terminal page
One of those paths is also asked for by a browser. The terminal a stack ships titles its tab with the VM's name, and finds the name by fetching the network it is reached through:
GET /stabile/networks/<network uuid> → { …, "domainnames": "testvm", … }
Here it is the signed-in user asking, with their ticket, so the answer is the
same as /api/v1/networks/{uuid}: one of their own networks, or a 404. An
invalid ticket is a 401. Without a ticket the request is treated as a call from
inside a VM, as above.
This is the only /stabile path a browser may use.
Compute nodes
A node reports to /api/v1/piston/… in JSON. One that still runs the older
node software posts form fields to /stabile/piston/piston.cgi and expects
key=value lines back; that conversation is passed through as it is.
Either way it is for a compute node only: the call has to come from the node network and carry the node credentials.
Management links
Links to a stack's management interface and terminal were once stored with a
/stabile/pipe/ prefix. That path is not answered. Keal serves the same
thing at /pipe/, and rewrites the prefix in the links it hands out, so a
stored link keeps working without being edited.