Merge branch '19624-priority-doc'

fixes #19624

Arvados-DCO-1.1-Signed-off-by: Tom Clegg <tom@curii.com>

diff --git a/doc/api/methods/container_request_lifecycle.svg b/doc/api/methods/container_request_lifecycle.svg
new file mode 100644 (file)
index 0000000..06215aa
--- /dev/null
+++ b/doc/api/methods/container_request_lifecycle.svg
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.43.0 (0)
+ -->
+<!-- Title: %3 Pages: 1 -->
+<svg width="748pt" height="818pt"
+ viewBox="0.00 0.00 747.50 818.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 814)">
+<title>%3</title>
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-814 743.5,-814 743.5,4 -4,4"/>
+<!-- invisiblestart -->
+<g id="node1" class="node">
+<title>invisiblestart</title>
+<ellipse fill="none" stroke="white" cx="88" cy="-792" rx="27" ry="18"/>
+</g>
+<!-- uncommitted -->
+<g id="node2" class="node">
+<title>uncommitted</title>
+<polygon fill="lightgrey" stroke="black" points="176,-723 0,-723 0,-685 176,-685 176,-723"/>
+<text text-anchor="start" x="8" y="-707.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="8" y="-692.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Uncommitted</text>
+</g>
+<!-- invisiblestart&#45;&gt;uncommitted -->
+<g id="edge1" class="edge">
+<title>invisiblestart&#45;&gt;uncommitted</title>
+<path fill="none" stroke="navy" d="M88,-773.6C88,-762.06 88,-746.65 88,-733.36"/>
+<polygon fill="navy" stroke="navy" points="91.5,-733.27 88,-723.27 84.5,-733.27 91.5,-733.27"/>
+<text text-anchor="start" x="88" y="-744.8" font-family="Times,serif" font-size="14.00" fill="navy"> &#160;&#160;user creates container request</text>
+</g>
+<!-- committed -->
+<g id="node3" class="node">
+<title>committed</title>
+<polygon fill="white" stroke="black" points="167,-604 9,-604 9,-551 167,-551 167,-604"/>
+<text text-anchor="start" x="17" y="-588.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="17" y="-573.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Committed</text>
+<text text-anchor="start" x="17" y="-558.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;priority&gt;0</text>
+</g>
+<!-- uncommitted&#45;&gt;committed -->
+<g id="edge2" class="edge">
+<title>uncommitted&#45;&gt;committed</title>
+<path fill="none" stroke="navy" d="M88,-684.9C88,-666.53 88,-637.61 88,-614.55"/>
+<polygon fill="navy" stroke="navy" points="91.5,-614.43 88,-604.43 84.5,-614.43 91.5,-614.43"/>
+<text text-anchor="start" x="88" y="-655.8" font-family="Times,serif" font-size="14.00" fill="navy"> &#160;&#160;user updates to</text>
+<text text-anchor="start" x="88" y="-640.8" font-family="Times,serif" font-size="14.00" fill="navy"> &#160;&#160;&#160;&#160;&#160;state=Committed, priority&gt;0</text>
+</g>
+<!-- reused -->
+<g id="node4" class="node">
+<title>reused</title>
+<polygon fill="lightblue" stroke="black" points="739.5,-619 530.5,-619 530.5,-536 739.5,-536 739.5,-619"/>
+<text text-anchor="start" x="538.5" y="-603.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="538.5" y="-588.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Final</text>
+<text text-anchor="start" x="538.5" y="-573.8" font-family="Times,serif" font-size="14.00">container:</text>
+<text text-anchor="start" x="538.5" y="-558.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Complete</text>
+<text text-anchor="start" x="538.5" y="-543.8" font-family="Times,serif" font-size="14.00">(reused existing container)</text>
+</g>
+<!-- committed&#45;&gt;reused -->
+<g id="edge6" class="edge">
+<title>committed&#45;&gt;reused</title>
+<path fill="none" stroke="black" d="M167.25,-577.5C260.04,-577.5 414.48,-577.5 520.34,-577.5"/>
+<polygon fill="black" stroke="black" points="520.43,-581 530.43,-577.5 520.43,-574 520.43,-581"/>
+<text text-anchor="middle" x="348.75" y="-584.3" font-family="Times,serif" font-size="14.00">Arvados selects an existing container</text>
+</g>
+<!-- queued -->
+<g id="node5" class="node">
+<title>queued</title>
+<polygon fill="white" stroke="black" points="167,-485 9,-485 9,-402 167,-402 167,-485"/>
+<text text-anchor="start" x="17" y="-469.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="17" y="-454.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Committed</text>
+<text text-anchor="start" x="17" y="-439.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;priority&gt;0</text>
+<text text-anchor="start" x="17" y="-424.8" font-family="Times,serif" font-size="14.00">container:</text>
+<text text-anchor="start" x="17" y="-409.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Queued</text>
+</g>
+<!-- committed&#45;&gt;queued -->
+<g id="edge3" class="edge">
+<title>committed&#45;&gt;queued</title>
+<path fill="none" stroke="black" d="M88,-550.74C88,-534.9 88,-514.07 88,-495.05"/>
+<polygon fill="black" stroke="black" points="91.5,-495.01 88,-485.01 84.5,-495.01 91.5,-495.01"/>
+<text text-anchor="start" x="88" y="-506.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;Arvados creates a new container</text>
+</g>
+<!-- latecancelled -->
+<g id="node7" class="node">
+<title>latecancelled</title>
+<polygon fill="lightblue" stroke="black" points="709,-343.5 561,-343.5 561,-275.5 709,-275.5 709,-343.5"/>
+<text text-anchor="start" x="569" y="-328.3" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="569" y="-313.3" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Final</text>
+<text text-anchor="start" x="569" y="-298.3" font-family="Times,serif" font-size="14.00">container:</text>
+<text text-anchor="start" x="569" y="-283.3" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Cancelled</text>
+</g>
+<!-- reused&#45;&gt;latecancelled -->
+<!-- locked -->
+<g id="node6" class="node">
+<title>locked</title>
+<polygon fill="white" stroke="black" points="167,-351 9,-351 9,-268 167,-268 167,-351"/>
+<text text-anchor="start" x="17" y="-335.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="17" y="-320.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Committed</text>
+<text text-anchor="start" x="17" y="-305.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;priority&gt;0</text>
+<text text-anchor="start" x="17" y="-290.8" font-family="Times,serif" font-size="14.00">container:</text>
+<text text-anchor="start" x="17" y="-275.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Locked</text>
+</g>
+<!-- queued&#45;&gt;locked -->
+<g id="edge4" class="edge">
+<title>queued&#45;&gt;locked</title>
+<path fill="none" stroke="black" d="M88,-401.82C88,-389.02 88,-374.73 88,-361.32"/>
+<polygon fill="black" stroke="black" points="91.5,-361.27 88,-351.27 84.5,-361.27 91.5,-361.27"/>
+<text text-anchor="start" x="88" y="-372.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;Arvados is ready to dispatch the container</text>
+</g>
+<!-- queued&#45;&gt;latecancelled -->
+<g id="edge7" class="edge">
+<title>queued&#45;&gt;latecancelled</title>
+<path fill="none" stroke="navy" d="M167.18,-436.67C233.02,-429.8 328.19,-415.07 406,-384 417.33,-379.47 417.89,-374.06 429,-369 467.51,-351.46 512.51,-337.95 550.6,-328.36"/>
+<polygon fill="navy" stroke="navy" points="551.77,-331.68 560.64,-325.88 550.09,-324.88 551.77,-331.68"/>
+<text text-anchor="middle" x="525" y="-372.8" font-family="Times,serif" font-size="14.00" fill="navy">user updates to priority=0</text>
+</g>
+<!-- locked&#45;&gt;latecancelled -->
+<g id="edge8" class="edge">
+<title>locked&#45;&gt;latecancelled</title>
+<path fill="none" stroke="navy" d="M167.25,-309.5C269.4,-309.5 446.28,-309.5 550.79,-309.5"/>
+<polygon fill="navy" stroke="navy" points="550.98,-313 560.98,-309.5 550.98,-306 550.98,-313"/>
+<text text-anchor="middle" x="364" y="-316.3" font-family="Times,serif" font-size="14.00" fill="navy">user updates to priority=0</text>
+</g>
+<!-- running -->
+<g id="node8" class="node">
+<title>running</title>
+<polygon fill="white" stroke="black" points="167,-217 9,-217 9,-134 167,-134 167,-217"/>
+<text text-anchor="start" x="17" y="-201.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="17" y="-186.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Committed</text>
+<text text-anchor="start" x="17" y="-171.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;priority&gt;0</text>
+<text text-anchor="start" x="17" y="-156.8" font-family="Times,serif" font-size="14.00">container:</text>
+<text text-anchor="start" x="17" y="-141.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Running</text>
+</g>
+<!-- locked&#45;&gt;running -->
+<g id="edge5" class="edge">
+<title>locked&#45;&gt;running</title>
+<path fill="none" stroke="black" d="M88,-267.82C88,-255.02 88,-240.73 88,-227.32"/>
+<polygon fill="black" stroke="black" points="91.5,-227.27 88,-217.27 84.5,-227.27 91.5,-227.27"/>
+<text text-anchor="start" x="88" y="-238.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;Arvados starts the container process</text>
+</g>
+<!-- containerfailed -->
+<g id="node9" class="node">
+<title>containerfailed</title>
+<polygon fill="lightblue" stroke="black" points="709,-217 561,-217 561,-134 709,-134 709,-217"/>
+<text text-anchor="start" x="569" y="-201.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="569" y="-186.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Final</text>
+<text text-anchor="start" x="569" y="-171.8" font-family="Times,serif" font-size="14.00">container:</text>
+<text text-anchor="start" x="569" y="-156.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Complete</text>
+<text text-anchor="start" x="569" y="-141.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;exit_code≠0</text>
+</g>
+<!-- latecancelled&#45;&gt;containerfailed -->
+<!-- running&#45;&gt;latecancelled -->
+<g id="edge9" class="edge">
+<title>running&#45;&gt;latecancelled</title>
+<path fill="none" stroke="navy" d="M167.03,-191.54C223.51,-202.63 301.19,-218.59 369,-235 430.25,-249.82 498.77,-268.81 550.93,-283.78"/>
+<polygon fill="navy" stroke="navy" points="550.23,-287.22 560.81,-286.62 552.16,-280.49 550.23,-287.22"/>
+<text text-anchor="middle" x="523" y="-238.8" font-family="Times,serif" font-size="14.00" fill="navy">user updates to priority=0</text>
+</g>
+<!-- running&#45;&gt;containerfailed -->
+<g id="edge10" class="edge">
+<title>running&#45;&gt;containerfailed</title>
+<path fill="none" stroke="black" d="M167.25,-175.5C269.4,-175.5 446.28,-175.5 550.79,-175.5"/>
+<polygon fill="black" stroke="black" points="550.98,-179 560.98,-175.5 550.98,-172 550.98,-179"/>
+<text text-anchor="middle" x="364" y="-182.3" font-family="Times,serif" font-size="14.00">container process fails</text>
+</g>
+<!-- containerfinished -->
+<g id="node10" class="node">
+<title>containerfinished</title>
+<polygon fill="lightblue" stroke="black" points="162,-83 14,-83 14,0 162,0 162,-83"/>
+<text text-anchor="start" x="22" y="-67.8" font-family="Times,serif" font-size="14.00">container request:</text>
+<text text-anchor="start" x="22" y="-52.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Final</text>
+<text text-anchor="start" x="22" y="-37.8" font-family="Times,serif" font-size="14.00">container:</text>
+<text text-anchor="start" x="22" y="-22.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;state=Complete</text>
+<text text-anchor="start" x="22" y="-7.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;exit_code=0</text>
+</g>
+<!-- running&#45;&gt;containerfinished -->
+<g id="edge11" class="edge">
+<title>running&#45;&gt;containerfinished</title>
+<path fill="none" stroke="black" d="M88,-133.82C88,-121.02 88,-106.73 88,-93.32"/>
+<polygon fill="black" stroke="black" points="91.5,-93.27 88,-83.27 84.5,-93.27 91.5,-93.27"/>
+<text text-anchor="start" x="88" y="-104.8" font-family="Times,serif" font-size="14.00"> &#160;&#160;container process succeeds</text>
+</g>
+</g>
+</svg>

diff --git a/doc/api/methods/container_requests.html.textile.liquid b/doc/api/methods/container_requests.html.textile.liquid
index d694ec778df2122b98ac2adbd2a3420f3bebf264..5e15df5ba6866742e1df067f62e5bed00da9cd24 100644 (file)
--- a/doc/api/methods/container_requests.html.textile.liquid
+++ b/doc/api/methods/container_requests.html.textile.liquid
@@ -64,6 +64,59 @@ table(table table-bordered table-condensed).
 |output_properties|hash|User metadata properties to set on the output collection.  The output collection will also have default properties "type" ("intermediate" or "output") and "container_request" (the uuid of container request that produced the collection).|
 |cumulative_cost|number|Estimated cost of the cloud VMs used to satisfy the request, including retried attempts and completed subrequests, but not including reused containers.|0 if container was reused or VM price information was not available.|
 
+h2(#lifecycle). Container request lifecycle
+
+A container request may be created in the Committed state, or created in the Uncommitted state and then moved into the Committed state.
+
+Once a request is in the Committed state, Arvados locates a suitable existing container or schedules a new one. When the assigned container finishes, the request state changes to Final.
+
+A client may cancel a committed request early (before the assigned container finishes) by setting the request priority to zero.
+
+!{max-width:60em;}{{site.baseurl}}/api/methods/container_request_lifecycle.svg!
+{% comment %}
+# svg generated using `graphviz -Tsvg -O`
+digraph {
+    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];
+    }
+    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 %}
+
 h2(#priority). Priority
 
 The @priority@ field has a range of 0-1000.
@@ -99,7 +152,7 @@ h2(#cancel_container). Canceling a container request
 
 A container request may be canceled by setting its priority to 0, using an update call.
 
-When a container request is canceled, it will still reflect the state of the Container it is associated with via the container_uuid attribute. If that Container is being reused by any other container_requests that are still active, i.e., not yet canceled, that Container may continue to run or be scheduled to run by the system in future. However, if no other container_requests are using that Contianer, then the Container will get canceled as well.
+When a container request is canceled, it will still reflect the state of the Container it is associated with via the container_uuid attribute. If that Container is being reused by any other container_requests that are still active, i.e., not yet canceled, that Container may continue to run or be scheduled to run by the system in future. However, if no other container_requests are using that Container, then the Container will get canceled as well.
 
 h2. Methods
 

diff --git a/doc/architecture/dispatchcloud.html.textile.liquid b/doc/architecture/dispatchcloud.html.textile.liquid
index ae854fc2e620acb2e8d48ceb1698a5fcde62f0a7..cc3f11d196aba4421a311dc0a414850dd5e75ae6 100644 (file)
--- a/doc/architecture/dispatchcloud.html.textile.liquid
+++ b/doc/architecture/dispatchcloud.html.textile.liquid
@@ -20,7 +20,7 @@ In this diagram, the black edges show interactions involved in starting a VM ins
 !{max-width:40em}{{site.baseurl}}/architecture/dispatchcloud.svg!
 
 {% comment %}
-# svg generated using https://graphviz.it/
+# svg generated using https://dreampuf.github.io/
 digraph {
     subgraph cluster_cloudvm {
         node [color=black] [fillcolor=white] [style=filled];