X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/d2c770ed6eafa87f9b488a0e41ce250af57f1bd1..3d65beeef57b2dd7a60171c8dce05785ef1ae383:/doc/api/methods/container_requests.html.textile.liquid diff --git a/doc/api/methods/container_requests.html.textile.liquid b/doc/api/methods/container_requests.html.textile.liquid index bbd1a8de92..fad051f4bf 100644 --- a/doc/api/methods/container_requests.html.textile.liquid +++ b/doc/api/methods/container_requests.html.textile.liquid @@ -72,38 +72,48 @@ Once a request is in the Committed state, Arvados locates a suitable existing co A client may cancel a committed request early (before the assigned container finishes) by setting the request priority to zero. -!{max-width:40em;max-height:70em}{{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 { - graph [nojustify=true] [labeljust=l]; + graph [nojustify=true] [labeljust=l] - invisiblestart [label = ""] [color=white]; + 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]; - committed [label = "container request:\l state=Committed\l priority>0\l"]; - invisiblestart -> uncommitted [label = "user creates container request"]; - uncommitted -> committed [label = "user assigns state=Committed, priority>0\l"]; - queued [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Queued\l"]; - committed -> queued [label = "Arvados creates\la new container\l"]; - locked [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Locked\l"]; - queued -> locked [label = "Arvados is ready\lto dispatch the container\l"]; - running [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Running\l"]; - locked -> running [label = "Arvados starts the\lcontainer process\l"]; - - node [color=black] [fillcolor=lightblue] [style=filled] [shape=box]; - reused [label = "container request:\l state=Final\lcontainer:\l state=Complete\l(reused existing container)\l"]; - latecancelled [label = "container request:\l state=Final\lcontainer:\l state=Cancelled\l"]; - containerfinished [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code=0\l"]; - containerfailed [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code≠0\l"]; - reused -> latecancelled -> containerfailed -> containerfinished [style=invis]; - - committed -> reused [label = "Arvados selects an\lexisting container\l"]; - queued -> latecancelled [label = "user assigns\lpriority=0"]; - locked -> latecancelled [label = "user assigns\lpriority=0"]; - running -> latecancelled [label = "user assigns\lpriority=0"]; - running -> containerfailed [label = "container process\lfails\l"]; - running -> containerfinished [label = "container process\lsucceeds\l"]; + 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]; + } + 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]; + } + 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]; + } + 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 %} @@ -129,9 +139,13 @@ h2(#scheduling_parameters). {% include 'container_scheduling_parameters' %} 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.