doc/api/dispatch.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "cloud dispatcher"
   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 The cloud dispatcher provides several management/diagnostic APIs, intended to be used by a system administrator.
  15
  16 These APIs are not normally exposed to external clients. To use them, connect directly to the dispatcher's internal URL (see Services.DispatchCloud.InternalURLs in the cluster config file). All requests must include the cluster's management token (@ManagementToken@ in the cluster config file).
  17
  18 Example:
  19
  20 <notextile><pre><code>curl -H "Authorization: Bearer $management_token" http://localhost:9006/arvados/v1/dispatch/containers</code></pre></notextile>
  21
  22 These APIs are not available via @arv@ CLI tool.
  23
  24 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.
  25
  26 h3. List containers
  27
  28 @GET /arvados/v1/dispatch/containers@
  29
  30 Return a list of containers that are either ready to dispatch, or being started/monitored by the dispatcher.
  31
  32 Each entry in the returned list of @items@ includes:
  33 * 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
  34 * 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":[],...}@).
  35
  36 Example response:
  37
  38 <notextile><pre>{
  39   "items": [
  40     {
  41       "container": {
  42         "uuid": "zzzzz-dz642-xz68ptr62m49au7",
  43         ...
  44         "priority": 562948375092493200,
  45         ...
  46         "state": "Locked",
  47         ...
  48       },
  49       "instance_type": {
  50         "Name": "Standard_E2s_v3",
  51         "ProviderType": "Standard_E2s_v3",
  52         "VCPUs": 2,
  53         "RAM": 17179869184,
  54         "Scratch": 32000000000,
  55         "IncludedScratch": 32000000000,
  56         "AddedScratch": 0,
  57         "Price": 0.146,
  58         "Preemptible": false
  59       }
  60     },
  61     ...
  62   ]
  63 }</pre></notextile>
  64
  65 h3. Terminate a container
  66
  67 @POST /arvados/v1/dispatch/containers/kill?container_uuid={uuid}&reason={string}@
  68
  69 Make a single attempt to terminate the indicated container on the relevant instance. (The caller can implement a delay-and-retry loop if needed.)
  70
  71 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.
  72
  73 The provided @reason@ string will appear in the dispatcher's log, but not in the user-visible container log.
  74
  75 If the provided @container_uuid@ is not scheduled/running on an instance, the response status will be 404.
  76
  77 h3. List instances
  78
  79 @GET /arvados/v1/dispatch/instances@
  80
  81 Return a list of cloud instances.
  82
  83 Example response:
  84
  85 <notextile><pre>{
  86   "items": [
  87     {
  88       "instance": "/subscriptions/abcdefab-abcd-abcd-abcd-abcdefabcdef/resourceGroups/zzzzz/providers/Microsoft.Compute/virtualMachines/compute-abcdef0123456789abcdef0123456789-abcdefghijklmno",
  89       "address": "10.23.45.67",
  90       "price": 0.073,
  91       "arvados_instance_type": "Standard_DS1_v2",
  92       "provider_instance_type": "Standard_DS1_v2",
  93       "last_container_uuid": "zzzzz-dz642-vp7scm21telkadq",
  94       "last_busy": "2020-01-13T15:20:21.775019617Z",
  95       "worker_state": "running",
  96       "idle_behavior": "run"
  97     },
  98     ...
  99 }</pre></notextile>
 100
 101 The @instance@ value is the instance's identifier, assigned by the cloud provider. It can be used with the instance APIs below.
 102
 103 The @worker_state@ value indicates the instance's capability to run containers.
 104 * @unknown@: instance was not created by this dispatcher, and a boot probe has not yet succeeded (this state typically appears briefly after the dispatcher restarts).
 105 * @booting@: cloud provider says the instance exists, but a boot probe has not yet succeeded.
 106 * @idle@: instance is idle and ready to run a container.
 107 * @running@: instance is running a container.
 108 * @shutdown@: cloud provider has been instructed to terminate the instance.
 109
 110 The @idle_behavior@ value determines what the dispatcher will do with the instance when it is idle; see hold/drain/run APIs below.
 111
 112 h3. Hold an instance
 113
 114 @POST /arvados/v1/dispatch/instances/hold?instance_id={instance}@
 115
 116 Set the indicated instance's idle behavior to @hold@. The instance will not be shut down automatically. If a container is currently running, it will be allowed to continue, but no new containers will be scheduled.
 117
 118 h3. Drain an instance
 119
 120 @POST /arvados/v1/dispatch/instances/drain?instance_id={instance}@
 121
 122 Set the indicated instance's idle behavior to @drain@. If a container is currently running, it will be allowed to continue, but when the instance becomes idle, it will be shut down.
 123
 124 h3. Resume an instance
 125
 126 @POST /arvados/v1/dispatch/instances/run?instance_id={instance}@
 127
 128 Set the indicated instance's idle behavior to @run@ (the normal behavior). When it becomes idle, it will be eligible to run new containers. It will be shut down automatically when the configured idle threshold is reached.
 129
 130 h3. Shut down an instance
 131
 132 @POST /arvados/v1/dispatch/instances/kill?instance_id={instance}&reason={string}@
 133
 134 Terminate the indicated instance.
 135
 136 If a container is running on the instance, it will be killed too; no effort is made to wait for it to end gracefully.
 137
 138 The provided @reason@ string will appear in the dispatcher's log.