Merge branch '21123-scheduling-status'

[arvados.git] / doc / api / dispatch.html.textile.liquid

diff --git a/doc/api/dispatch.html.textile.liquid b/doc/api/dispatch.html.textile.liquid
index 1ca1279ee5ae12dce6a8a3c6eb48ba35f6457847..cfe57640c4785cca1c5ca4df4faadbd8cea996b1 100644 (file)
--- a/doc/api/dispatch.html.textile.liquid
+++ b/doc/api/dispatch.html.textile.liquid
@@ -21,13 +21,18 @@ Example:
 
 These APIs are not available via @arv@ CLI tool.
 
+Note: the term "instance" here refers to a virtual machine provided by a cloud computing service. The alternate terms "cloud VM", "compute node", and "worker node" are sometimes used as well in config files, documentation, and log messages.
+
 h3. List containers
 
 @GET /arvados/v1/dispatch/containers@
 
 Return a list of containers that are either ready to dispatch, or being started/monitored by the dispatcher.
 
-The response provides @uuid@, @priority@, and @state@ fields for each container. Other fields of the container records are not loaded by the dispatcher, and will have empty/zero values here (e.g., @{...,"created_at":"0001-01-01T00:00:00Z","command":[],...}@).
+Each entry in the returned list of @items@ includes:
+* an @instance_type@ entry with the name and attributes of the instance type that will be used to schedule the container (chosen from the @InstanceTypes@ section of your cluster config file); and
+* a @container@ entry with selected attributes of the container itself, including @uuid@, @priority@, @runtime_constraints@, and @state@. Other fields of the container records are not loaded by the dispatcher, and will have empty/zero values here (e.g., @{...,"created_at":"0001-01-01T00:00:00Z","command":[],...}@).
+* a @scheduling_status@ field with a brief explanation of the container's status in the dispatch queue, or an empty string if scheduling is not applicable, e.g., the container has already started running.
 
 Example response:
 
@@ -52,23 +57,42 @@ Example response:
         "AddedScratch": 0,
         "Price": 0.146,
         "Preemptible": false
-      }
+      },
+      "scheduling_status": "waiting for new instance to be ready"
     },
     ...
   ]
 }</pre></notextile>
 
+h3. Get specified container
+
+@GET /arvados/v1/dispatch/container?container_uuid={uuid}@
+
+Return the same information as "list containers" above, but for a single specified container.
+
+Example response:
+
+<notextile><pre>{
+  "container": {
+    ...
+  },
+  "instance_type": {
+    ...
+  },
+  "scheduling_status": "waiting for new instance to be ready"
+}</pre></notextile>
+
 h3. Terminate a container
 
 @POST /arvados/v1/dispatch/containers/kill?container_uuid={uuid}&reason={string}@
 
-Make a single attempt to terminate the indicated container on the relevant cloud VM. (The caller can implement a delay-and-retry loop if needed.)
+Make a single attempt to terminate the indicated container on the relevant instance. (The caller can implement a delay-and-retry loop if needed.)
 
 A container terminated this way will end with state @Cancelled@ if its docker container had already started, or @Queued@ if it was terminated while setting up the runtime environment.
 
 The provided @reason@ string will appear in the dispatcher's log, but not in the user-visible container log.
 
-If the provided @container_uuid@ is not scheduled/running on a worker node, the response status will be 404.
+If the provided @container_uuid@ is not scheduled/running on an instance, the response status will be 404.
 
 h3. List instances