Machines
Platform-admin pages for the virtual machines the platform provisions onto its own hypervisors — the layer under a Docker context. A machine is a record in its own right: it can serve a context, or be a plain VM serving nothing, and both are ordinary states.
Everything here is the operator-visible half of the provisioning plan; the flow behind it is §05 there.
The list
Admin → Machines. Every machine the platform has asked a hypervisor for,
newest first, with its state, size, disk, island address and the context it
serves (or —).
Creating one
New machine walks five steps on the same wizard the organization and
application forms use. Submitting is a handoff, not a completion: the machine
lands as requested and its page shows it come up.
The button only appears once a hypervisor is answering its probe — step 1 asks which one, and a wizard whose first question has no answers can only dead-end. With none registered the page points at New hypervisor; with all of them quiet it points at Hypervisors, where you can re-check one.
| Step | Asks | Worth knowing |
|---|---|---|
| 1 · Hypervisor | Which registered Proxmox endpoint | Only ones a probe has answered from are offered |
| 2 · Size | S, M or L |
Chosen, not derived from any role. The cards are Derek, Doreen and Norman — the catalogue's own cast |
| 3 · Storage | How many 32 GB blocks | Its own step because it is the irreversible one: blocks only ever grow |
| 4 · Purpose | New Docker context, or just a machine | "No context" is a first-class answer, plus the machine's name — also its hostname |
| 5 · Review | Confirm | The address, vmid and template are the control plane's to allocate; they appear on the machine's page as the flow claims them |
If the chosen hypervisor has no template yet, the form says exactly what to
run (app:proxmox:template <name>) rather than failing later.
Watching it come up
The machine's page is the progress display — the same row the provisioning
worker writes, polled while the flow runs:
requested → cloning → configuring → starting → booting, ending in running
when the guest agent answers. A machine that serves a context later becomes
serving when the reconciler observes the node — the swarm's word, not the
machine's.
Underneath the flow, a Live log panel follows the hypervisor's own task
output as it happens — the same account the settled Hypervisor tasks panel
gives once the machine stops moving, but while it is still running. It is one
connection, opened once and left open, not the page's own refresh: the
two-second poll never touches the hypervisor, only the row a browser can read
in a moment. State changes appear inline as ── configuring ──-style markers
between the lines they separate.
A finished machine stops polling and shows its record — address, sizing, the template it was cloned from, and its context's endpoint:
A failure keeps the task's own words, verbatim:
When it fails
That red box is the verdict — usually one line of Proxmox's exitstatus. The
Hypervisor tasks panel underneath it is the account: every task the node ran
for this machine's vmid, newest first, green for OK and red for anything else.
Each task links to its own log — where the reason lives, as opposed to the verdict:
The panel is only fetched once the machine has settled. While the flow is still running the page polls every two seconds, and asking the hypervisor on every refresh would stall the one page that has to stay responsive; it says so rather than showing an empty box. A hypervisor that will not answer says that too, instead of breaking the page.
Reprovision
Reprovision runs the flow again from the top. It appears only on a failed machine — a running one has nothing to retry, and a machine mid-flow already has a worker on it.
Three things it does that are worth knowing:
- It clears the failed attempt off the hypervisor first. A failure past
cloningleaves a real VM at that vmid; the retry stops it, destroys it and drops the previous seed disc before cloning again. Otherwise every retry would fail on "that vmid is taken" and tell you nothing about the original problem. - It keeps the island address. The machine already holds one, and a retry has no reason to burn another out of the pool.
- It will not destroy a VM it cannot prove is ours. Proxmox hands out vmids without reserving them, so a machine that failed a while ago may find its number belongs to something else by now. The name has to match; when it does not, the machine stays failed and says whose VM is sitting there.