X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/6477db8a1f5ed0b2f81cf743bbea32c681c7c10c..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 d694ec778d..fad051f4bf 100644
--- 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.
@@ -86,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.
@@ -99,7 +156,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