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

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "containers"
   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/containers@
  15
  16 Object type: @dz642@
  17
  18 Example UUID: @zzzzz-dz642-0123456789abcde@
  19
  20 h2. Resource
  21
  22 A container is work order to be dispatched to an Arvados cluster to perform some computational work.  A container is created in response to a container request.  See "computing with Crunch":{{site.baseurl}}/api/execution.html for details.
  23
  24 Each Container offers the following attributes, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  25
  26 table(table table-bordered table-condensed).
  27 |_. Attribute|_. Type|_. Description|_. Notes|
  28 |state|string|The allowed states are "Queued", "Locked", "Running", "Cancelled" and "Complete".|See "Container states":#container_states for more details.|
  29 |started_at|datetime|When this container started running.|Null if container has not yet started.|
  30 |finished_at|datetime|When this container finished.|Null if container has not yet finished.|
  31 |log|string|Portable data hash of a collection containing the log messages produced when executing the container.|Null if container has not yet started. The Crunch system will periodically update this field for a running container.|
  32 |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.|Must be equal to a ContainerRequest's environment in order to satisfy the ContainerRequest.|
  33 |cwd|string|Initial working directory.|Must be equal to a ContainerRequest's cwd in order to satisfy the ContainerRequest|
  34 |command|array of strings|Command to execute.| Must be equal to a ContainerRequest's command in order to satisfy the ContainerRequest.|
  35 |output_path|string|Path to a directory or file inside the container that should be preserved as this container's output when it finishes.|Must be equal to a ContainerRequest's output_path in order to satisfy the ContainerRequest.|
  36 |mounts|hash|Must contain the same keys as the ContainerRequest being satisfied. Each value must be within the range of values described in the ContainerRequest at the time the Container is assigned to the ContainerRequest.|See "Mount types":#mount_types for more details.|
  37 |secret_mounts|hash|Must contain the same keys as the ContainerRequest being satisfied. Each value must be within the range of values described in the ContainerRequest at the time the Container is assigned to the ContainerRequest.|Not returned in API responses. Reset to empty when state is "Complete" or "Cancelled".|
  38 |runtime_constraints|hash|Compute resources, and access to the outside world, that are / were available to the container.
  39 Generally this will contain additional keys that are not present in any corresponding ContainerRequests: for example, even if no ContainerRequests specified constraints on the number of CPU cores, the number of cores actually used will be recorded here.|e.g.,
  40 <pre><code>{
  41   "ram":12000000000,
  42   "vcpus":2,
  43   "API":true
  44 }</code></pre>See "Runtime constraints":#runtime_constraints for more details.|
  45 |runtime_status|hash|Information related to the container's run, including its steps. Some keys have specific meaning and are described later in this page.|e.g.,
  46 <pre><code>{
  47   "error": "This container won't be successful because at least one step has already failed."
  48 }</code></pre>See "Runtime status":#runtime_status for more details.|
  49 |scheduling_parameters|hash|Parameters to be passed to the container scheduler when running this container.|e.g.,<pre><code>{
  50 "partitions":["fastcpu","vfastcpu"]
  51 }</code></pre>See "Scheduling parameters":#scheduling_parameters for more details.|
  52 |output|string|Portable data hash of the output collection.|Null if the container is not yet finished.|
  53 |container_image|string|Portable data hash of a collection containing the docker image used to run the container.||
  54 |progress|number|A number between 0.0 and 1.0 describing the fraction of work done.||
  55 |priority|integer|Range 0-1000.  Indicate scheduling order preference.|Currently assigned by the system as the max() of the priorities of all associated ContainerRequests.  See "container request priority":container_requests.html#priority.|
  56 |exit_code|integer|Process exit code.|Null if container process has not exited yet.|
  57 |auth_uuid|string|UUID of a token to be passed into the container itself, used to access Keep-backed mounts, etc.  Automatically assigned.|Null if state∉{"Locked","Running"} or if @runtime_token@ was provided.|
  58 |locked_by_uuid|string|UUID of a token, indicating which dispatch process changed state to Locked. If null, any token can be used to lock. If not null, only the indicated token can modify this container.|Null if state∉{"Locked","Running"}|
  59 |runtime_token|string|A v2 token to be passed into the container itself, used to access Keep-backed mounts, etc.|Not returned in API responses.  Reset to null when state is "Complete" or "Cancelled".|
  60 |gateway_address|string|Address (host:port) of gateway server.|Internal use only.|
  61 |interactive_session_started|boolean|Indicates whether @arvados-client shell@ has been used to run commands in the container, which may have altered the container's behavior and output.||
  62 |output_storage_classes|array of strings|The storage classes that will be used for the log and output collections of this container||
  63 |output_properties|hash|User metadata properties to set on the output collection.|
  64 |cost|number|Estimated cost of the cloud VM used to run the container.|0 if not available.|
  65 |subrequests_cost|number|Total estimated cumulative cost of container requests submitted by this container.|0 if not available.|
  66
  67 h2(#container_states). Container states
  68
  69 table(table table-bordered table-condensed).
  70 |_. State&nbsp;value|_. Description|_. Allowed next|
  71 |Queued|Waiting for a dispatcher to lock it and try to run the container.|Locked, Cancelled|
  72 |Locked|A dispatcher has "taken" the container and is allocating resources for it. The container has not started yet.|Queued, Running, Cancelled|
  73 |Running|Resources have been allocated and the contained process has been started (or is about to start). Crunch-run _must_ set state to Running _before_ there is any possibility that user code will run in the container.|Complete, Cancelled|
  74 |Complete|Container was running, and the contained process/command has exited.|Cancelled|
  75 |Cancelled|The container did not run long enough to produce an exit code. This includes cases where the container didn't even start, cases where the container was interrupted/killed before it exited by itself (e.g., priority changed to 0), and cases where some problem prevented the system from capturing the contained process's exit status (exit code and output).|-|
  76
  77 See "Controlling container reuse":{{site.baseurl}}/admin/controlling-container-reuse.html for details about changing state from @Complete@ to @Cancelled@
  78
  79 h2(#mount_types). {% include 'mount_types' %}
  80
  81 h2(#runtime_constraints). {% include 'container_runtime_constraints' %}
  82
  83 h2(#runtime_status). Runtime status
  84
  85 Runtime status provides container's relevant information about its progress even while it's still in Running state. This is used to avoid reusing containers that have not yet failed but will definitely do, and also for easier workflow debugging.
  86
  87 The following keys have well known meanings:
  88
  89 table(table table-bordered table-condensed).
  90 |_. Key|_. Type|_. Description|_. Notes|
  91 |error|string|The existance of this key indicates the container will definitely fail, or has already failed.|Optional.|
  92 |warning|string|Indicates something unusual happened or is currently happening, but isn't considered fatal.|Optional.|
  93 |activity|string|A message for the end user about what state the container is currently in.|Optional.|
  94 |errorDetail|string|Additional structured error details.|Optional.|
  95 |warningDetail|string|Additional structured warning details.|Optional.|
  96 |preemptionNotice|string|Details about any cloud provider scheduled interruption to the instance running this container.|Existence of this key indicates the container likely was (or will soon be) @Cancelled@ due to an instance interruption.|
  97
  98 h2(#scheduling_parameters). {% include 'container_scheduling_parameters' %}
  99
 100 h2. Methods
 101
 102 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
 103
 104 Required arguments are displayed in %{background:#ccffcc}green%.
 105
 106 Supports federated @get@ and @list@.
 107
 108 h3(#create). create
 109
 110 Create a new Container.
 111
 112 This API requires admin privileges. In normal operation, it should not be used at all.
 113
 114 Arguments:
 115
 116 table(table table-bordered table-condensed).
 117 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 118 {background:#ccffcc}.|container|object|Container resource|request body||
 119
 120 h3. delete
 121
 122 Delete a Container.
 123
 124 This API requires admin privileges. In normal operation, it should not be used at all. API clients like Workbench might not work correctly when a container request references a container that has been deleted.
 125
 126 Arguments:
 127
 128 table(table table-bordered table-condensed).
 129 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 130 {background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
 131
 132 h3. get
 133
 134 Get a Container's metadata by UUID.
 135
 136 Arguments:
 137
 138 table(table table-bordered table-condensed).
 139 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 140 {background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
 141
 142 h3. list
 143
 144 List containers.
 145
 146 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
 147
 148 h3. update
 149
 150 Update attributes of an existing Container.
 151
 152 Arguments:
 153
 154 table(table table-bordered table-condensed).
 155 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 156 {background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
 157 |container|object||query||
 158
 159 h3. auth
 160
 161 Get the api_client_authorization record indicated by this container's auth_uuid, which belongs to the container's locked_by_uuid.
 162
 163 table(table table-bordered table-condensed).
 164 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 165 {background:#ccffcc}.|uuid|string||path||
 166
 167 h3. log
 168
 169 Get container log data using WebDAV methods.
 170
 171 This API retrieves data from the container's log collection. It can be used at any time in the container lifecycle.
 172 * While the container is @Queued@ or @Locked@ it returns an empty directory.
 173 * While the container is @Running@ it returns real-time logging data.
 174 * While the container is @Complete@ or @Cancelled@ it returns the final log collection.
 175
 176 This API also supports the @Range@ request header, so it can be used to poll for and retrieve logs while the container is running.
 177
 178 Arguments:
 179
 180 table(table table-bordered table-condensed).
 181 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 182 |method|string|Read-only WebDAV method|HTTP method|@GET@, @OPTIONS@, @PROPFIND@|
 183 {background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
 184 |path|string|Path to a file in the log collection.|path|@/stderr.txt@|
 185
 186 Examples:
 187 * @GET /arvados/v1/containers/zzzzz-dz642-0123456789abcde/log/stderr.txt@
 188 * @PROPFIND /arvados/v1/containers/zzzzz-dz642-0123456789abcde/log/@