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 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/container_requests@
  15
  16 Object type: @xvhdp@
  17
  18 Example UUID: @zzzzz-xvhdp-0123456789abcde@
  19
  20 h2. Resource
  21
  22 A container request is a request for the Arvados cluster to perform some computational work.  See "computing with Crunch":{{site.baseurl}}/api/execution.html for details.
  23
  24 Each ContainerRequest offers the following attributes, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  25
  26 All attributes are optional, unless otherwise marked as required.
  27
  28 table(table table-bordered table-condensed).
  29 |_. Attribute|_. Type|_. Description|_. Notes|
  30 |name|string|The name of the container_request.||
  31 |description|string|The description of the container_request.||
  32 |properties|hash|Client-defined structured data that does not affect how the container is run.||
  33 |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).|
  34 |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.|
  35 |container_uuid|string|The uuid of the container that satisfies this container_request. The system may return a preexisting Container that matches the container request criteria. See "Container reuse":#container_reuse for more details.|Container reuse is the default behavior, but may be disabled with @use_existing: false@ to always create a new container.|
  36 |container_count_max|integer|Maximum number of containers to start, i.e., the maximum number of "attempts" to be made.||
  37 |mounts|hash|Objects to attach to the container's filesystem and stdin/stdout.|See "Mount types":#mount_types for more details.|
  38 |runtime_constraints|hash|Restrict the container's access to compute resources and the outside world.|Required when in "Committed" state. e.g.,<pre><code>{
  39   "ram":12000000000,
  40   "vcpus":2,
  41   "API":true
  42 }</code></pre>See "Runtime constraints":#runtime_constraints for more details.|
  43 |scheduling_parameters|hash|Parameters to be passed to the container scheduler when running this container.|e.g.,<pre><code>{
  44 "partitions":["fastcpu","vfastcpu"]
  45 }</code></pre>See "Scheduling parameters":#scheduling_parameters for more details.|
  46 |container_image|string|Portable data hash of a collection containing the docker image to run the container.|Required.|
  47 |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.||
  48 |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.|
  49 |command|array of strings|Command to execute in the container.|Required. e.g., @["echo","hello"]@|
  50 |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. Also, see "Pre-populate output using Mount points":#pre-populate-output for details regarding optional output pre-population using mount points.|Required.|
  51 |output_name|string|Desired name for the output collection. If null, a name will be assigned automatically.||
  52 |output_ttl|integer|Desired lifetime for the output collection, in seconds. If zero, the output collection will not be deleted automatically.||
  53 |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 container requests with zero priority in order to preview the container that will be used to satisfy it. Priority can be null if and only if state!="Committed".|
  54 |expires_at|datetime|After this time, priority is considered to be zero.|Not yet implemented.|
  55 |use_existing|boolean|If possible, use an existing (non-failed) container to satisfy the request instead of creating a new one.|Default is true|
  56 |log_uuid|string|Log collection containing log messages provided by the scheduler and crunch processes.|Null if the container has not yet completed.|
  57 |output_uuid|string|Output collection created when the container finished successfully.|Null if the container has failed or not yet completed.|
  58 |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.|
  59
  60 h2(#mount_types). {% include 'mount_types' %}
  61
  62 h2(#runtime_constraints). {% include 'container_runtime_constraints' %}
  63
  64 h2(#scheduling_parameters). {% include 'container_scheduling_parameters' %}
  65
  66 h2(#container_reuse). Container reuse
  67
  68 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, and runtime_constraints being requested. (Hashes in the serialized fields environment, mounts and runtime_constraints are compared without regard to key order.)
  69
  70 In order of preference, the system will use:
  71 * 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.
  72 * The oldest matching "Running" container with the highest progress, i.e., the container that is most likely to finish first.
  73 * The oldest matching "Locked" container with the highest priority, i.e., the container that is most likely to start first.
  74 * The oldest matching "Queued" container with the highest priority, i.e,, the container that is most likely to start first.
  75 * A new container.
  76
  77 h2(#cancel_container). Canceling a container request
  78
  79 A container request may be canceled by setting its priority to 0, using an update call.
  80
  81 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.
  82
  83 h2. Methods
  84
  85 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  86
  87 Required arguments are displayed in %{background:#ccffcc}green%.
  88
  89 h2(#create). create
  90
  91 Create a new container request.
  92
  93 Arguments:
  94
  95 table(table table-bordered table-condensed).
  96 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  97 {background:#ccffcc}.|container_request|object|Container request resource.|request body||
  98
  99
 100 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.
 101
 102 h3. delete
 103
 104 Delete an existing container request.
 105
 106 Arguments:
 107
 108 table(table table-bordered table-condensed).
 109 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 110 {background:#ccffcc}.|uuid|string|The UUID of the container request in question.|path||
 111
 112 h3. get
 113
 114 Get a container request's metadata by UUID.
 115
 116 Arguments:
 117
 118 table(table table-bordered table-condensed).
 119 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 120 {background:#ccffcc}.|uuid|string|The UUID of the container request in question.|path||
 121
 122 h3. list
 123
 124 List container_requests.
 125
 126 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
 127
 128 See the create method documentation for more information about container request-specific filters.
 129
 130 h3. update
 131
 132 Update attributes of an existing container request.
 133
 134 Arguments:
 135
 136 table(table table-bordered table-condensed).
 137 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 138 {background:#ccffcc}.|uuid|string|The UUID of the container request in question.|path||
 139 |container_request|object||query||
 140
 141 {% include 'notebox_begin' %}
 142 Setting the priority of a committed container_request to 0 may cancel a running container assigned for it.
 143 See "Canceling a container request":{{site.baseurl}}/api/methods/container_requests.html#cancel_container for further details.
 144 {% include 'notebox_end' %}