doc/install/crunch2-cloud/install-dispatch-cloud.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the cloud dispatcher
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 {% include 'notebox_begin_warning' %}
  13 arvados-dispatch-cloud is only relevant for cloud installations. Skip this section if you are installing an on premises cluster that will spool jobs to Slurm.
  14 {% include 'notebox_end' %}
  15
  16 # "Introduction":#introduction
  17 # "Create compute node VM image":#create-image
  18 # "Update config.yml":#update-config
  19 # "Install arvados-dispatch-cloud":#install-packages
  20 # "Start the service":#start-service
  21 # "Restart the API server and controller":#restart-api
  22 # "Confirm working installation":#confirm-working
  23
  24 h2(#introduction). Introduction
  25
  26 The cloud dispatch service is for running containers on cloud VMs. It works with Microsoft Azure and Amazon EC2; future versions will also support Google Compute Engine.
  27
  28 The cloud dispatch service can run on any node that can connect to the Arvados API service, the cloud provider's API, and the SSH service on cloud VMs.  It is not resource-intensive, so you can run it on the API server node.
  29
  30 h2(#update-config). Update config.yml
  31
  32 h3. Configure CloudVMs
  33
  34 Add or update the following portions of your cluster configuration file, @config.yml@. Refer to "config.defaults.yml":{{site.baseurl}}/admin/config.html for information about additional configuration options. The @DispatchPrivateKey@ should be the *private* key generated in "the previous section":install-compute-node.html#sshkeypair.
  35
  36 <notextile>
  37 <pre><code>    Services:
  38       DispatchCloud:
  39         InternalURLs:
  40           "http://localhost:9006": {}
  41     Containers:
  42       CloudVMs:
  43         # BootProbeCommand is a shell command that succeeds when an instance is ready for service
  44         BootProbeCommand: "sudo systemctl status docker"
  45
  46         <b># --- driver-specific configuration goes here --- see Amazon and Azure examples below ---</b>
  47
  48       DispatchPrivateKey: |
  49         -----BEGIN RSA PRIVATE KEY-----
  50         MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
  51         ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
  52         FJ+amZ7oYMDof6QEdwl6KNDfIddL+NfBCLQTVInOAaNss7GRrxLTuTV7HcRaIUUI
  53         jYg0Ibg8ZZTzQxCvFXXnjseTgmOcTv7CuuGdt91OVdoq8czG/w8TwOhymEb7mQlt
  54         lXuucwQvYgfoUgcnTgpJr7j+hafp75g2wlPozp8gJ6WQ2yBWcfqL2aw7m7Ll88Nd
  55         [...]
  56         oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
  57         foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
  58         -----END RSA PRIVATE KEY-----
  59     InstanceTypes:
  60       x1md:
  61         ProviderType: x1.medium
  62         VCPUs: 8
  63         RAM: 64GiB
  64         IncludedScratch: 64GB
  65         Price: 0.62
  66       x1lg:
  67         ProviderType: x1.large
  68         VCPUs: 16
  69         RAM: 128GiB
  70         IncludedScratch: 128GB
  71         Price: 1.23
  72 </code></pre>
  73 </notextile>
  74
  75 h4. Minimal configuration example for Amazon EC2
  76
  77 The <span class="userinput">ImageID</span> value is the compute node image that was built in "the previous section":install-compute-node.html#aws.
  78
  79 <notextile>
  80 <pre><code>    Containers:
  81       CloudVMs:
  82         ImageID: <span class="userinput">ami-01234567890abcdef</span>
  83         Driver: ec2
  84         DriverParameters:
  85           # If you are not using an IAM role for authentication, specify access
  86           # credentials here. Otherwise, omit or set AccessKeyID and
  87           # SecretAccessKey to an empty value.
  88           AccessKeyID: XXXXXXXXXXXXXXXXXXXX
  89           SecretAccessKey: YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
  90
  91           SecurityGroupIDs:
  92           - sg-0123abcd
  93           SubnetID: subnet-0123abcd
  94           Region: us-east-1
  95           EBSVolumeType: gp2
  96           AdminUsername: arvados
  97 </code></pre>
  98 </notextile>
  99
 100 h4. Minimal configuration example for Azure
 101
 102 Using managed disks:
 103
 104 The <span class="userinput">ImageID</span> value is the compute node image that was built in "the previous section":install-compute-node.html#azure.
 105
 106 <notextile>
 107 <pre><code>    Containers:
 108       CloudVMs:
 109         ImageID: <span class="userinput">"zzzzz-compute-v1597349873"</span>
 110         Driver: azure
 111         # (azure) managed disks: set MaxConcurrentInstanceCreateOps to 20 to avoid timeouts, cf
 112         # https://docs.microsoft.com/en-us/azure/virtual-machines/linux/capture-image
 113         MaxConcurrentInstanceCreateOps: 20
 114         DriverParameters:
 115           # Credentials.
 116           SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 117           ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 118           ClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 119           TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 120
 121           # Data center where VMs will be allocated
 122           Location: centralus
 123
 124           # The resource group where the VM and virtual NIC will be
 125           # created.
 126           ResourceGroup: zzzzz
 127           NetworkResourceGroup: yyyyy   # only if different from ResourceGroup
 128           Network: xxxxx
 129           Subnet: xxxxx-subnet-private
 130
 131           # The resource group where the disk image is stored, only needs to
 132           # be specified if it is different from ResourceGroup
 133           ImageResourceGroup: aaaaa
 134
 135 </code></pre>
 136 </notextile>
 137
 138 Azure recommends using managed images. If you plan to start more than 20 VMs simultaneously, Azure recommends using a shared image gallery instead to avoid slowdowns and timeouts during the creation of the VMs.
 139
 140 Using an image from a shared image gallery:
 141
 142 <notextile>
 143 <pre><code>    Containers:
 144       CloudVMs:
 145         ImageID: <span class="userinput">"shared_image_gallery_image_definition_name"</span>
 146         Driver: azure
 147         DriverParameters:
 148           # Credentials.
 149           SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 150           ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 151           ClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 152           TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 153
 154           # Data center where VMs will be allocated
 155           Location: centralus
 156
 157           # The resource group where the VM and virtual NIC will be
 158           # created.
 159           ResourceGroup: zzzzz
 160           NetworkResourceGroup: yyyyy   # only if different from ResourceGroup
 161           Network: xxxxx
 162           Subnet: xxxxx-subnet-private
 163
 164           # The resource group where the disk image is stored, only needs to
 165           # be specified if it is different from ResourceGroup
 166           ImageResourceGroup: aaaaa
 167
 168           # (azure) shared image gallery: the name of the gallery
 169           SharedImageGalleryName: "shared_image_gallery_1"
 170           # (azure) shared image gallery: the version of the image definition
 171           SharedImageGalleryImageVersion: "0.0.1"
 172
 173 </code></pre>
 174 </notextile>
 175
 176 Using unmanaged disks (deprecated):
 177
 178 The <span class="userinput">ImageID</span> value is the compute node image that was built in "the previous section":install-compute-node.html#azure.
 179
 180 <notextile>
 181 <pre><code>    Containers:
 182       CloudVMs:
 183         ImageID: <span class="userinput">"https://zzzzzzzz.blob.core.windows.net/system/Microsoft.Compute/Images/images/zzzzz-compute-osDisk.55555555-5555-5555-5555-555555555555.vhd"</span>
 184         Driver: azure
 185         DriverParameters:
 186           # Credentials.
 187           SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 188           ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 189           ClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 190           TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 191
 192           # Data center where VMs will be allocated
 193           Location: centralus
 194
 195           # The resource group where the VM and virtual NIC will be
 196           # created.
 197           ResourceGroup: zzzzz
 198           NetworkResourceGroup: yyyyy   # only if different from ResourceGroup
 199           Network: xxxxx
 200           Subnet: xxxxx-subnet-private
 201
 202           # Where to store the VM VHD blobs
 203           StorageAccount: example
 204           BlobContainer: vhds
 205
 206 </code></pre>
 207 </notextile>
 208
 209 Get the @SubscriptionID@ and @TenantID@:
 210
 211 <pre>
 212 $ az account list
 213 [
 214   {
 215     "cloudName": "AzureCloud",
 216     "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
 217     "isDefault": true,
 218     "name": "Your Subscription",
 219     "state": "Enabled",
 220     "tenantId": "YYYYYYYY-YYYY-YYYY-YYYYYYYY",
 221     "user": {
 222       "name": "you@example.com",
 223       "type": "user"
 224     }
 225   }
 226 ]
 227 </pre>
 228
 229 You will need to create a "service principal" to use as a delegated authority for API access.
 230
 231 <notextile><pre><code>$ az ad app create --display-name "Arvados Dispatch Cloud (<span class="userinput">ClusterID</span>)" --homepage "https://arvados.org" --identifier-uris "https://<span class="userinput">ClusterID.example.com</span>" --end-date 2299-12-31 --password <span class="userinput">Your_Password</span>
 232 $ az ad sp create "<span class="userinput">appId</span>"
 233 (appId is part of the response of the previous command)
 234 $ az role assignment create --assignee "<span class="userinput">objectId</span>" --role Owner --scope /subscriptions/{subscriptionId}/
 235 (objectId is part of the response of the previous command)
 236 </code></pre></notextile>
 237
 238 Now update your @config.yml@ file:
 239
 240 @ClientID@ is the 'appId' value.
 241
 242 @ClientSecret@ is what was provided as <span class="userinput">Your_Password</span>.
 243
 244 h3. Test your configuration
 245
 246 Run the @cloudtest@ tool to verify that your configuration works. This creates a new cloud VM, confirms that it boots correctly and accepts your configured SSH private key, and shuts it down.
 247
 248 <notextile>
 249 <pre><code>~$ <span class="userinput">arvados-server cloudtest && echo "OK!"</span>
 250 </code></pre>
 251 </notextile>
 252
 253 Refer to the "cloudtest tool documentation":../../admin/cloudtest.html for more information.
 254
 255 {% assign arvados_component = 'arvados-dispatch-cloud' %}
 256
 257 {% include 'install_packages' %}
 258
 259 {% include 'start_service' %}
 260
 261 {% include 'restart_api' %}
 262
 263 h2(#confirm-working). Confirm working installation
 264
 265 On the dispatch node, start monitoring the arvados-dispatch-cloud logs:
 266
 267 <notextile>
 268 <pre><code>~$ <span class="userinput">sudo journalctl -o cat -fu arvados-dispatch-cloud.service</span>
 269 </code></pre>
 270 </notextile>
 271
 272 "Make sure to install the arvados/jobs image.":../install-jobs-image.html
 273
 274 Submit a simple container request:
 275
 276 <notextile>
 277 <pre><code>shell:~$ <span class="userinput">arv container_request create --container-request '{
 278   "name":            "test",
 279   "state":           "Committed",
 280   "priority":        1,
 281   "container_image": "arvados/jobs:latest",
 282   "command":         ["echo", "Hello, Crunch!"],
 283   "output_path":     "/out",
 284   "mounts": {
 285     "/out": {
 286       "kind":        "tmp",
 287       "capacity":    1000
 288     }
 289   },
 290   "runtime_constraints": {
 291     "vcpus": 1,
 292     "ram": 1048576
 293   }
 294 }'</span>
 295 </code></pre>
 296 </notextile>
 297
 298 This command should return a record with a @container_uuid@ field.  Once @arvados-dispatch-cloud@ polls the API server for new containers to run, you should see it dispatch that same container.
 299
 300 The @arvados-dispatch-cloud@ API provides a list of queued and running jobs and cloud instances. Use your @ManagementToken@ to test the dispatcher's endpoint. For example, when one container is running:
 301
 302 <notextile>
 303 <pre><code>~$ <span class="userinput">curl -sH "Authorization: Bearer $token" http://localhost:9006/arvados/v1/dispatch/containers</span>
 304 {
 305   "items": [
 306     {
 307       "container": {
 308         "uuid": "zzzzz-dz642-hdp2vpu9nq14tx0",
 309         ...
 310         "state": "Running",
 311         "scheduling_parameters": {
 312           "partitions": null,
 313           "preemptible": false,
 314           "max_run_time": 0
 315         },
 316         "exit_code": 0,
 317         "runtime_status": null,
 318         "started_at": null,
 319         "finished_at": null
 320       },
 321       "instance_type": {
 322         "Name": "Standard_D2s_v3",
 323         "ProviderType": "Standard_D2s_v3",
 324         "VCPUs": 2,
 325         "RAM": 8589934592,
 326         "Scratch": 16000000000,
 327         "IncludedScratch": 16000000000,
 328         "AddedScratch": 0,
 329         "Price": 0.11,
 330         "Preemptible": false
 331       }
 332     }
 333   ]
 334 }
 335 </code></pre>
 336 </notextile>
 337
 338 A similar request can be made to the @http://localhost:9006/arvados/v1/dispatch/instances@ endpoint.
 339
 340 When the container finishes, the dispatcher will log it.
 341
 342 After the container finishes, you can get the container record by UUID *from a shell server* to see its results:
 343
 344 <notextile>
 345 <pre><code>shell:~$ <span class="userinput">arv get <b>zzzzz-dz642-hdp2vpu9nq14tx0</b></span>
 346 {
 347  ...
 348  "exit_code":0,
 349  "log":"a01df2f7e5bc1c2ad59c60a837e90dc6+166",
 350  "output":"d41d8cd98f00b204e9800998ecf8427e+0",
 351  "state":"Complete",
 352  ...
 353 }
 354 </code></pre>
 355 </notextile>
 356
 357 You can use standard Keep tools to view the container's output and logs from their corresponding fields.  For example, to see the logs from the collection referenced in the @log@ field:
 358
 359 <notextile>
 360 <pre><code>~$ <span class="userinput">arv keep ls <b>a01df2f7e5bc1c2ad59c60a837e90dc6+166</b></span>
 361 ./crunch-run.txt
 362 ./stderr.txt
 363 ./stdout.txt
 364 ~$ <span class="userinput">arv-get <b>a01df2f7e5bc1c2ad59c60a837e90dc6+166</b>/stdout.txt</span>
 365 2016-08-05T13:53:06.201011Z Hello, Crunch!
 366 </code></pre>
 367 </notextile>
 368
 369 If the container does not dispatch successfully, refer to the @arvados-dispatch-cloud@ logs for information about why it failed.