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

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "containers"
   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/containers@
  12
  13 UUID type: @dz642@
  14
  15 Required arguments are displayed in %{background:#ccffcc}green%.
  16
  17 h2. Resource
  18
  19 Each Container offers the following attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
  20
  21 table(table table-bordered table-condensed).
  22 |_. Attribute|_. Type|_. Description|_. Notes|
  23 |state|string|The allowed states are "Queued", "Locked", "Running", "Cancelled" and "Complete".|See "Container states":#container_states for more details.|
  24 |started_at|datetime|When this container started running.|Null if container has not yet started.|
  25 |finished_at|datetime|When this container finished.|Null if container has not yet finished.|
  26 |log|string|Portable data hash of the collection containing logs from a completed container run.|Null if the container is not yet finished.|
  27 |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.|
  28 |cwd|string|Initial working directory.|Must be equal to a ContainerRequest's cwd in order to satisfy the ContainerRequest|
  29 |command|array of strings|Command to execute.| Must be equal to a ContainerRequest's command in order to satisfy the ContainerRequest.|
  30 |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.|
  31 |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.|
  32 |runtime_constraints|hash|Compute resources, and access to the outside world, that are / were available to the container.
  33 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.,
  34 <pre><code>{
  35   "ram":12000000000,
  36   "vcpus":2,
  37   "API":true
  38 }</code></pre>See "Runtime constraints":#runtime_constraints for more details.|
  39 |output|string|Portable data hash of the output collection.|Null if the container is not yet finished.|
  40 |container_image|string|Portable data hash of a collection containing the docker image used to run the container.||
  41 |progress|number|A number between 0.0 and 1.0 describing the fraction of work done.||
  42 |priority|integer|Priority assigned by the system, taking into account the priorities of all associated ContainerRequests.||
  43 |exit_code|integer|Process exit code.|Null if state!="Complete"|
  44 |auth_uuid|string|UUID of a token to be passed into the container itself, used to access Keep-backed mounts, etc.|Null if state∉{"Locked","Running"}|
  45 |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"}|
  46
  47 h2(#container_states). Container states
  48
  49 table(table table-bordered table-condensed).
  50 |_. State|_. Sgnificance|_. Allowed next|
  51 |Queued|Waiting for a dispatcher to lock it and try to run the container.|Locked, Cancelled|
  52 |Locked|A dispatcher has "taken" the container and is allocating resources for it. The container has not started yet.|Queued, Running, Cancelled|
  53 |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|
  54 |Complete|Container was running, and the contained process/command has exited.|-|
  55 |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).|-|
  56
  57 h2(#mount_types). {% include 'mount_types' %}
  58
  59 h2(#runtime_constraints). {% include 'container_runtime_constraints' %}
  60
  61 h2. Methods
  62 h2(#create). create
  63
  64 Create a new Container.
  65
  66 Arguments:
  67
  68 table(table table-bordered table-condensed).
  69 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  70 {background:#ccffcc}.|container|object|See "Container resource":{{site.baseurl}}/api/schema/Container.html|request body||
  71
  72 h3. delete
  73
  74 Delete an existing Container.
  75
  76 Arguments:
  77
  78 table(table table-bordered table-condensed).
  79 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  80 {background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
  81
  82 h3. get
  83
  84 Get a Container's metadata by UUID.
  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 Container in question.|path||
  91
  92 h3. list
  93
  94 List containers.
  95
  96 Arguments:
  97
  98 table(table table-bordered table-condensed).
  99 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 100 |limit|integer (default 100)|Maximum number of containers to return.|query||
 101 |order|string|Order in which to return matching containers.|query||
 102 |filters|array|Conditions for filtering containers.|query||
 103
 104 See the create method documentation for more information about Container-specific filters.
 105
 106 h3. update
 107
 108 Update attributes of an existing Container.
 109
 110 Arguments:
 111
 112 table(table table-bordered table-condensed).
 113 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 114 {background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
 115 |container|object||query||
 116
 117 h3. auth
 118
 119 Get the api_client_authorization record indicated by this container's auth_uuid, which belongs to the container's locked_by_uuid.
 120
 121 table(table table-bordered table-condensed).
 122 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 123 {background:#ccffcc}.|uuid|string||path||