Merge branch 'main' into 19385-cwl-fast-pack

[arvados.git] / 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 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