|priority|integer|Range 0-1000. Indicate scheduling order preference.|Clients are expected to submit container requests with zero priority in order to preview the container that will be used to satisfy it. Priority can be null if and only if state!="Committed". See "below for more details":#priority .|
|expires_at|datetime|After this time, priority is considered to be zero.|Not yet implemented.|
|use_existing|boolean|If possible, use an existing (non-failed) container to satisfy the request instead of creating a new one.|Default is true|
-|log_uuid|string|Log collection containing log messages provided by the scheduler and crunch processes.|Null if the container has not yet started running.|
+|log_uuid|string|Log collection containing log messages provided by the scheduler and crunch processes.|Null if the container has not yet started running.
+To retrieve logs in real time while the container is running, use the log API (see below).|
|output_uuid|string|Output collection created when the container finished successfully.|Null if the container has failed or not yet completed.|
|filters|string|Additional constraints for satisfying the container_request, given in the same form as the filters parameter accepted by the container_requests.list API.|
|runtime_token|string|A v2 token to be passed into the container itself, used to access Keep-backed mounts, etc. |Not returned in API responses. Reset to null when state is "Complete" or "Cancelled".|
A client may cancel a committed request early (before the assigned container finishes) by setting the request priority to zero.
-In the following diagram, the green ("go") and red ("stop") arrows indicate client-initiated transitions, and the blue arrows indicate system-initiated transitions.
-
-!{max-width:40em}{{site.baseurl}}/api/methods/container_request_lifecycle.svg!
+!{max-width:60em;}{{site.baseurl}}/api/methods/container_request_lifecycle.svg!
{% comment %}
-# svg generated using https://dreampuf.github.io/
+# svg generated using `graphviz -Tsvg -O`
digraph {
- subgraph cluster_draft {
- label = "Draft\n(no container assigned)";
- style = filled;
- color = lightgrey;
- node [color=black] [fillcolor=white] [style=filled] [shape=box];
- uncommitted [label = "Uncommitted"];
- }
- subgraph cluster_active {
- label = "Active\n(container assigned)";
- style = filled;
- color = lightgrey;
- node [color=black] [fillcolor=white] [style=filled] [shape=box];
- runnable [label = "Committed\npriority>0"];
- node [fillcolor=lightgrey];
- queued -> locked -> running -> complete;
+ graph [nojustify=true] [labeljust=l]
+
+ invisiblestart [label = ""] [color=white] [group=lifecycle];
+ node [color=black] [fillcolor=white] [style=filled] [shape=box] [nojustify=true];
+ uncommitted [label = "container request:\l state=Uncommitted\l"] [fillcolor=lightgrey] [group=lifecycle];
+ {
+ rank=same;
+ committed [label = "container request:\l state=Committed\l priority>0\l"] [group=lifecycle];
+ reused [label = "container request:\l state=Final\lcontainer:\l state=Complete\l(reused existing container)\l"] [fillcolor=lightblue] [group=endstate];
}
- subgraph cluster_complete {
- label = "Complete";
- style = filled;
- color = lightgrey;
- node [color=black] [fillcolor=white] [style=filled] [shape=box];
- reqcomplete [label = "Final"];
+ invisiblestart -> uncommitted [label = " user creates container request\l"] [color=navy] [fontcolor=navy];
+ uncommitted -> committed [label = " user updates to\l state=Committed, priority>0\l"] [color=navy] [fontcolor=navy];
+ queued [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Queued\l"] [group=lifecycle];
+ committed -> queued [label = " Arvados creates a new container\l"];
+ {
+ rank=same;
+ locked [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Locked\l"] [group=lifecycle];
+ latecancelled [label = "container request:\l state=Final\lcontainer:\l state=Cancelled\l"] [fillcolor=lightblue] [group=endstate];
}
- subgraph cluster_cancelled {
- label = "Cancelled";
- style = filled;
- color = lightgrey;
- node [color=black] [fillcolor=white] [style=filled] [shape=box];
- reqcancelled [label = "Final"];
+ queued -> locked [label = " Arvados is ready to dispatch the container\l"];
+ {
+ rank=same;
+ running [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Running\l"] [group=lifecycle];
+ containerfailed [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code≠0\l"] [fillcolor=lightblue] [group=endstate];
}
- cancelling [label = "Committed\npriority=0"] [shape=box];
- runnable -> cancelling [color = red];
- uncommitted -> runnable [color = darkgreen];
- cancelling -> reqcancelled [color = blue];
- runnable -> reqcomplete [color = blue];
- uncommitted -> cancelling [color = red];
+ locked -> running [label = " Arvados starts the container process\l"];
+ containerfinished [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code=0\l"] [fillcolor=lightblue] [group=lifecycle];
+
+ committed -> reused [label = "Arvados selects an existing container"] [constraint=false] [labeldistance=0.5];
+ queued -> latecancelled [label = "user updates to priority=0"] [color=navy] [fontcolor=navy];
+ locked -> latecancelled [label = "user updates to priority=0"] [color=navy] [fontcolor=navy] [constraint=false];
+ running -> latecancelled [label = "user updates to priority=0"] [color=navy] [fontcolor=navy] [constraint=false];
+ running -> containerfailed [label = "container process fails"];
+ running -> containerfinished [label = " container process succeeds\l"];
+
+ # layout hacks
+ reused -> latecancelled [style=invis];
+ latecancelled -> containerfailed [style=invis];
}
{% endcomment %}
h2(#container_reuse). Container reuse
-When a container request is "Committed", the system will try to find and reuse an existing Container with the same command, cwd, environment, output_path, container_image, mounts, secret_mounts, runtime_constraints, runtime_user_uuid, and runtime_auth_scopes being requested. (Hashes in the serialized fields environment, mounts and runtime_constraints use normalized key order.)
+When a container request is "Committed", the system will try to find and reuse an existing Container with the same command, cwd, environment, output_path, container_image, mounts, secret_mounts, runtime_constraints, runtime_user_uuid, and runtime_auth_scopes being requested.
+
+* The serialized fields environment, mounts, and runtime_constraints are normalized when searching.
+* The system will also search for containers with minor variations in the keep_cache_disk and keep_cache_ram runtime_constraints that should not affect the result. This searches for other common values for those constraints, so a container that used a non-default value for these constraints may not be reused by later container requests that use a different value.
In order of preference, the system will use:
+
* The first matching container to have finished successfully (i.e., reached state "Complete" with an exit_code of 0) whose log and output collections are still available.
* The oldest matching "Running" container with the highest progress, i.e., the container that is most likely to finish first.
* The oldest matching "Locked" container with the highest priority, i.e., the container that is most likely to start first.
Setting the priority of a committed container_request to 0 may cancel a running container assigned for it.
See "Canceling a container request":{{site.baseurl}}/api/methods/container_requests.html#cancel_container for further details.
{% include 'notebox_end' %}
+
+h3(#log). log
+
+Get container log data using WebDAV methods.
+
+This API retrieves data from the container request's log collection. It can be used at any time in the container request lifecycle.
+* Before a container has been assigned (the request is @Uncommitted@) it returns an empty directory.
+* While the container is @Queued@ or @Locked@, it returns an empty directory.
+* While the container is @Running@, @.../log/{container_uuid}/@ returns real-time logging data.
+* While the container is @Complete@ or @Cancelled@, @.../log/{container_uuid}/@ returns the final log collection.
+
+If a request results in multiple containers being run (see @container_count_max@ above), the logs from prior attempts remain available at @.../log/{old_container_uuid}/@.
+
+Currently, this API has a limitation that a directory listing at the top level @/arvados/v1/container_requests/{uuid}/log/@ does not reveal the per-container subdirectories. Instead, clients should look up the container request record and use the @container_uuid@ attribute to request files and directory listings under the per-container directory, as in the examples below.
+
+This API supports the @Range@ request header, so it can be used to poll for and retrieve logs incrementally while the container is running.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|method|string|Read-only WebDAV method|HTTP method|@GET@, @OPTIONS@, @PROPFIND@|
+{background:#ccffcc}.|uuid|string|The UUID of the container request.|path|zzzzz-xvdhp-0123456789abcde|
+{background:#ccffcc}.|path|string|Path to a file in the log collection.|path|@/zzzzz-dz642-0123456789abcde/stderr.txt@|
+
+Examples:
+* @GET /arvados/v1/container_requests/zzzzz-xvdhp-0123456789abcde/log/zzzzz-dz642-0123456789abcde/stderr.txt@
+* @PROPFIND /arvados/v1/container_requests/zzzzz-xvdhp-0123456789abcde/log/zzzzz-dz642-0123456789abcde/@
projects / arvados.git / blobdiff