Tasks

Starting a VM, cloning, migrating, taking a backup or a snapshot: Proxmox VE runs these as tasks in the background and the API answers at once, with the id of the task, the UPID. The same tasks appear in the Tasks panel of the web interface.

// newid, bwlimit, description, format, full, name, pool, snapname, storage, target
var result = client.getNodes().get("pve01").getQemu().get(9000).getClone()
        .cloneVm(121, null, null, null, true, "web02", null, null, null, null);

var upid = result.getData().asText();
// UPID:pve01:0012A3F4:05C1B2D3:6720F1A0:qmclone:9000:automation@pve!app:

The call returned when the task started. Before using the new VM the code has to wait for the task.

Wait for a task

waitForTaskToFinish takes the UPID, the milliseconds between two checks and the longest time to wait, in milliseconds:

if (!result.isSuccessStatusCode()) {
    System.out.println("Clone not started: " + result.getReasonPhrase());
    return;
}

// check every 2 seconds, for up to 10 minutes
var finished = client.waitForTaskToFinish(upid, 2000, 600000);

It reads the status of the task at each interval until the task stops, and returns true if it stopped, false if it is still running when the time runs out. Set the time to the longest the task may take: seconds for a start or a snapshot, minutes for a clone, a migration or a backup. An interval of 0 or less becomes 500 milliseconds, and a time shorter than the interval becomes the interval plus 5 seconds.

To check without waiting, taskIsRunning(upid) returns true while the task runs.

The node of the task is read from the UPID, so none of these needs the node: PveClientBase.getNodeFromTask(upid) returns it.

Did it succeed?

A finished task is not necessarily a successful one. waitForTaskToFinish only says the task stopped; getExitStatusTask says how: OK, WARNINGS: <n> when it ended with warnings in its log, or the error of the task.

if (!client.waitForTaskToFinish(upid, 2000, 600000)) {
    throw new IllegalStateException("Task still running after 10 minutes: " + upid);
}

var exitStatus = client.getExitStatusTask(upid);
if (!exitStatus.equals("OK") && !exitStatus.startsWith("WARNINGS")) {
    throw new IllegalStateException("Task failed: " + exitStatus);
}

For example a snapshot with a name already in use ends with an exit status such as snapshot name 'before-update' already used. For a task that is still running the exit status is null.

The log of a task

The log, the same text the web interface shows, comes from the log endpoint of the task. Each entry has the line number in n and the text in t:

import com.fasterxml.jackson.databind.JsonNode;
import it.corsinvest.proxmoxve.api.PveClientBase;

var node = PveClientBase.getNodeFromTask(upid);

// download, limit, start
var log = client.getNodes().get(node).getTasks().get(upid).getLog().readTaskLog(null, 1000, null);
for (JsonNode line : log.getData()) {
    System.out.println(line.get("t").asText());
}

Without limit Proxmox VE returns the first 50 lines. For a longer log raise limit, or read it in pages with start.

The other details of a task (type, user, start time) are in client.getNodes().get(node).getTasks().get(upid).getStatus().readTaskStatus(), and the tasks of a node in client.getNodes().get(node).getTasks().nodeTasks().

Show progress

Proxmox VE reports no percentage for a task: what can be shown is the time and the last lines of the log. Poll with taskIsRunning:

var started = System.currentTimeMillis();

while (client.taskIsRunning(upid)) {
    System.out.print("\rCloning... " + (System.currentTimeMillis() - started) / 1000 + " s");
    Thread.sleep(2000);
}

System.out.println();
System.out.println(client.getExitStatusTask(upid));

When the status cannot be read

taskIsRunning, getExitStatusTask and waitForTaskToFinish read the status of the task from its node. If they cannot (the node is down, or the account has no right to see the task), they throw PveResultException, an unchecked exception, with the reason, for example Read status of task 'UPID:…' failed (403 Forbidden): …, instead of reporting a finished task. The failed Result is in getResult() of the exception. A value that is not a UPID throws the same exception before any request.

A token can always read the tasks it started itself; to read the tasks of other users it needs Sys.Audit on the node: see Permissions.

Calls that return no task

Not every call returns a UPID. Calls that finish immediately (reading, most configuration changes) return their result directly. The API viewer shows what an endpoint returns: a UPID is a string described as the task id. Some endpoints exist in both forms: for the configuration of a VM, PUT applies the change and returns nothing, while POST returns a task, which is what you need when the change allocates a disk.