doc/api/methods/container_requests.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "container_requests"
   6
   7 ...
   8
   9 See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
  10
  11 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/container_requests@
  12
  13 Required arguments are displayed in %{background:#ccffcc}green%.
  14
  15 h2. Resource
  16
  17 Each ContainerRequest offers the following attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
  18
  19 All attributes are optional, unless otherwise marked as required.
  20
  21 table(table table-bordered table-condensed).
  22 |_. Attribute|_. Type|_. Description|_. Notes|
  23 |name|string|The name of the container_request.||
  24 |description|string|The description of the container_request.||
  25 |properties|hash|Client-defined structured data that does not affect how the container is run.||
  26 |state|string|The allowed states are "Uncommitted", "Committed", and "Final".|Once a request is Committed, the only attributes that can be modified are priority, container_uuid, and container_count_max. A request in the "Final" state cannot have any of its functional parts modified (i.e., only name, description, and properties fields can be modified).|
  27 |requesting_container_uuid|string|The uuid of the parent container that created this container_request, if any. Represents a process tree.|The priority of this container_request is inherited from the parent container, if the parent container is cancelled, this container_request will be cancelled as well.|
  28 |container_uuid|string|The uuid of the container that satisfies this container_request. The system will find and reuse any preexisting Container that matches this ContainerRequest's criteria. See "Container reuse":#container_reuse for more details.|Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported.|
  29 |container_count_max|integer|Maximum number of containers to start, i.e., the maximum number of "attempts" to be made.||
  30 |mounts|hash|Objects to attach to the container's filesystem and stdin/stdout.|See "Mount types":#mount_types for more details.|
  31 |runtime_constraints|hash|Restrict the container's access to compute resources and the outside world.|Required when in "Committed" state. e.g.,<pre><code>{
  32   "ram":12000000000,
  33   "vcpus":2,
  34   "API":true
  35 }</code></pre>See "Runtime constraints":#runtime_constraints for more details.|
  36 |container_image|string|Portable data hash of a collection containing the docker image to run the container.|Required.|
  37 |environment|hash|Environment variables and values that should be set in the container environment (@docker run --env@). This augments and (when conflicts exist) overrides environment variables given in the image's Dockerfile.||
  38 |cwd|string|Initial working directory, given as an absolute path (in the container) or a path relative to the WORKDIR given in the image's Dockerfile.|Required.|
  39 |command|array of strings|Command to execute in the container.|Required. e.g., @["echo","hello"]@|
  40 |output_path|string|Path to a directory or file inside the container that should be preserved as container's output when it finishes. This path must be, or be inside, one of the mount targets. For best performance, point output_path to a writable collection mount.|Required.|
  41 |priority|integer|Higher value means spend more resources on this container_request, i.e., go ahead of other queued containers, bring up more nodes etc.|Priority 0 means a container should not be run on behalf of this request. Clients are expected to submit ContainerRequests with zero priority in order to prevew the container that will be used to satisfy it. Priority can be null if and only if state!="Committed".|
  42 |expires_at|datetime|After this time, priority is considered to be zero.|Not yet implemented.|
  43 |filters|string|Additional constraints for satisfying the container_request, given in the same form as the filters parameter accepted by the container_requests.list API.||
  44
  45 h2(#mount_types). {% include 'mount_types' %}
  46
  47 h2(#runtime_constraints). {% include 'container_runtime_constraints' %}
  48
  49 h2(#container_reuse). Container reuse
  50
  51 When a ContainerRequest is "Committed", the system will try to find and reuse any preexisting Container with the same exact command, cwd, environment, output_path, container_image, mounts, and runtime_constraints as this ContainerRequest. The serialized fields environment, mounts and runtime_constraints are sorted to facilitate comparison.
  52
  53 The system will use the following scheme to determine which Container to consider for reuse: A Container with the same exact command, cwd, environment, output_path, container_image, mounts, and runtime_constraints as this ContainerRequest and,
  54 * The oldest successfully finished container, i.e., in state "Complete" with exit_code of 0. If matching containers with different outputs are found, the system will forgo reusing any of these finished containers and instead look for suitable containers in other states
  55 * The oldest "Running" container with the highest progress, i.e., the container that is most likely to finish first
  56 * The oldest "Locked" container with the highest priority, i.e., the container that is most likely to start first
  57 * The oldest "Queued" container with the highest priority, i.e, the container that is most likely to start first
  58
  59 {% include 'notebox_begin' %}
  60 Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported.
  61 {% include 'notebox_end' %}
  62
  63 h2(#cancel_container). Canceling a ContainerRequest
  64
  65 A ContainerRequest may be canceled by setting it's priority to 0, using an update call.
  66
  67 When a ContainerRequest 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.
  68
  69 h2. Methods
  70 h2(#create). create
  71
  72 Create a new ContainerRequest.
  73
  74 Arguments:
  75
  76 table(table table-bordered table-condensed).
  77 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  78 {background:#ccffcc}.|container_request|object|See "ContainerRequest resource":{{site.baseurl}}/api/schema/ContainerRequest.html|request body||
  79
  80 The request body must include the required attributes command, container_image, cwd, and output_path. It can also inlcude other attributes such as environment, mounts, and runtime_constraints.
  81
  82 h3. delete
  83
  84 Delete an existing ContainerRequest.
  85
  86 Arguments:
  87
  88 table(table table-bordered table-condensed).
  89 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  90 {background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
  91
  92 h3. get
  93
  94 Get a ContainerRequest's metadata by UUID.
  95
  96 Arguments:
  97
  98 table(table table-bordered table-condensed).
  99 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 100 {background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
 101
 102 h3. list
 103
 104 List container_requests.
 105
 106 Arguments:
 107
 108 table(table table-bordered table-condensed).
 109 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 110 |limit|integer (default 100)|Maximum number of container_requests to return.|query||
 111 |order|string|Order in which to return matching container_requests.|query||
 112 |filters|array|Conditions for filtering container_requests.|query||
 113
 114 See the create method documentation for more information about ContainerRequest-specific filters.
 115
 116 h3. update
 117
 118 Update attributes of an existing ContainerRequest.
 119
 120 Arguments:
 121
 122 table(table table-bordered table-condensed).
 123 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 124 {background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
 125 |container_request|object||query||
 126
 127 {% include 'notebox_begin' %}
 128 Setting the priority of a committed container_request to 0 may cancel a running container assigned for it.
 129 See "Canceling a ContainerRequest":{{site.baseurl}}/api/schema/ContainerRequest.html#cancel_container for further details.
 130 {% include 'notebox_end' %}