18903: Merge branch 'main' into 18903-fix-activity-script
[arvados.git] / 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 or LSF.
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 More detail about the internal operation of the dispatcher can be found in the "architecture section":{{site.baseurl}}/architecture/dispatchcloud.html.
31
32 h2(#update-config). Update config.yml
33
34 h3. Configure CloudVMs
35
36 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.
37
38 <notextile>
39 <pre><code>    Services:
40       DispatchCloud:
41         InternalURLs:
42           "http://localhost:9006": {}
43     Containers:
44       CloudVMs:
45         # BootProbeCommand is a shell command that succeeds when an instance is ready for service
46         BootProbeCommand: "sudo systemctl status docker"
47
48         <b># --- driver-specific configuration goes here --- see Amazon and Azure examples below ---</b>
49
50       DispatchPrivateKey: |
51         -----BEGIN RSA PRIVATE KEY-----
52         MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
53         ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
54         FJ+amZ7oYMDof6QEdwl6KNDfIddL+NfBCLQTVInOAaNss7GRrxLTuTV7HcRaIUUI
55         jYg0Ibg8ZZTzQxCvFXXnjseTgmOcTv7CuuGdt91OVdoq8czG/w8TwOhymEb7mQlt
56         lXuucwQvYgfoUgcnTgpJr7j+hafp75g2wlPozp8gJ6WQ2yBWcfqL2aw7m7Ll88Nd
57         [...]
58         oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
59         foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
60         -----END RSA PRIVATE KEY-----
61     InstanceTypes:
62       x1md:
63         ProviderType: x1.medium
64         VCPUs: 8
65         RAM: 64GiB
66         IncludedScratch: 64GB
67         Price: 0.62
68       x1lg:
69         ProviderType: x1.large
70         VCPUs: 16
71         RAM: 128GiB
72         IncludedScratch: 128GB
73         Price: 1.23
74 </code></pre>
75 </notextile>
76
77 h4(#GPUsupport). NVIDIA GPU support
78
79 To specify instance types with NVIDIA GPUs, you must include an additional @CUDA@ section:
80
81 <notextile>
82 <pre><code>    InstanceTypes:
83       g4dn:
84         ProviderType: g4dn.xlarge
85         VCPUs: 4
86         RAM: 16GiB
87         IncludedScratch: 125GB
88         Price: 0.56
89         CUDA:
90           DriverVersion: "11.4"
91           HardwareCapability: "7.5"
92           DeviceCount: 1
93 </code></pre>
94 </notextile>
95
96 The @DriverVersion@ is the version of the CUDA toolkit installed in your compute image (in X.Y format, do not include the patchlevel).  The @HardwareCapability@ is the CUDA compute capability of the GPUs available for this instance type.  The @DeviceCount@ is the number of GPU cores available for this instance type.
97
98 h4. Minimal configuration example for Amazon EC2
99
100 The <span class="userinput">ImageID</span> value is the compute node image that was built in "the previous section":install-compute-node.html#aws.
101
102 <notextile>
103 <pre><code>    Containers:
104       CloudVMs:
105         ImageID: <span class="userinput">ami-01234567890abcdef</span>
106         Driver: ec2
107         DriverParameters:
108           # If you are not using an IAM role for authentication, specify access
109           # credentials here. Otherwise, omit or set AccessKeyID and
110           # SecretAccessKey to an empty value.
111           AccessKeyID: XXXXXXXXXXXXXXXXXXXX
112           SecretAccessKey: YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
113
114           SecurityGroupIDs:
115           - sg-0123abcd
116           SubnetID: subnet-0123abcd
117           Region: us-east-1
118           EBSVolumeType: gp2
119           AdminUsername: arvados
120 </code></pre>
121 </notextile>
122
123 Example policy for the IAM role used by the cloud dispatcher:
124
125 <notextile>
126 <pre>
127 {
128     "Version": "2012-10-17",
129     "Id": "arvados-dispatch-cloud policy",
130     "Statement": [
131         {
132             "Effect": "Allow",
133             "Action": [
134                 "iam:PassRole",
135                 "ec2:DescribeKeyPairs",
136                 "ec2:ImportKeyPair",
137                 "ec2:RunInstances",
138                 "ec2:DescribeInstances",
139                 "ec2:CreateTags",
140                 "ec2:TerminateInstances"
141             ],
142             "Resource": "*"
143         }
144     ]
145 }
146 </pre>
147 </notextile>
148
149 h4. Minimal configuration example for Azure
150
151 Using managed disks:
152
153 The <span class="userinput">ImageID</span> value is the compute node image that was built in "the previous section":install-compute-node.html#azure.
154
155 <notextile>
156 <pre><code>    Containers:
157       CloudVMs:
158         ImageID: <span class="userinput">"zzzzz-compute-v1597349873"</span>
159         Driver: azure
160         # (azure) managed disks: set MaxConcurrentInstanceCreateOps to 20 to avoid timeouts, cf
161         # https://docs.microsoft.com/en-us/azure/virtual-machines/linux/capture-image
162         MaxConcurrentInstanceCreateOps: 20
163         DriverParameters:
164           # Credentials.
165           SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
166           ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
167           ClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
168           TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
169
170           # Data center where VMs will be allocated
171           Location: centralus
172
173           # The resource group where the VM and virtual NIC will be
174           # created.
175           ResourceGroup: zzzzz
176           NetworkResourceGroup: yyyyy   # only if different from ResourceGroup
177           Network: xxxxx
178           Subnet: xxxxx-subnet-private
179
180           # The resource group where the disk image is stored, only needs to
181           # be specified if it is different from ResourceGroup
182           ImageResourceGroup: aaaaa
183
184 </code></pre>
185 </notextile>
186
187 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.
188
189 Using an image from a shared image gallery:
190
191 <notextile>
192 <pre><code>    Containers:
193       CloudVMs:
194         ImageID: <span class="userinput">"shared_image_gallery_image_definition_name"</span>
195         Driver: azure
196         DriverParameters:
197           # Credentials.
198           SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
199           ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
200           ClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
201           TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
202
203           # Data center where VMs will be allocated
204           Location: centralus
205
206           # The resource group where the VM and virtual NIC will be
207           # created.
208           ResourceGroup: zzzzz
209           NetworkResourceGroup: yyyyy   # only if different from ResourceGroup
210           Network: xxxxx
211           Subnet: xxxxx-subnet-private
212
213           # The resource group where the disk image is stored, only needs to
214           # be specified if it is different from ResourceGroup
215           ImageResourceGroup: aaaaa
216
217           # (azure) shared image gallery: the name of the gallery
218           SharedImageGalleryName: "shared_image_gallery_1"
219           # (azure) shared image gallery: the version of the image definition
220           SharedImageGalleryImageVersion: "0.0.1"
221
222 </code></pre>
223 </notextile>
224
225 Using unmanaged disks (deprecated):
226
227 The <span class="userinput">ImageID</span> value is the compute node image that was built in "the previous section":install-compute-node.html#azure.
228
229 <notextile>
230 <pre><code>    Containers:
231       CloudVMs:
232         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>
233         Driver: azure
234         DriverParameters:
235           # Credentials.
236           SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
237           ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
238           ClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
239           TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
240
241           # Data center where VMs will be allocated
242           Location: centralus
243
244           # The resource group where the VM and virtual NIC will be
245           # created.
246           ResourceGroup: zzzzz
247           NetworkResourceGroup: yyyyy   # only if different from ResourceGroup
248           Network: xxxxx
249           Subnet: xxxxx-subnet-private
250
251           # Where to store the VM VHD blobs
252           StorageAccount: example
253           BlobContainer: vhds
254
255 </code></pre>
256 </notextile>
257
258 Get the @SubscriptionID@ and @TenantID@:
259
260 <pre>
261 $ az account list
262 [
263   {
264     "cloudName": "AzureCloud",
265     "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
266     "isDefault": true,
267     "name": "Your Subscription",
268     "state": "Enabled",
269     "tenantId": "YYYYYYYY-YYYY-YYYY-YYYYYYYY",
270     "user": {
271       "name": "you@example.com",
272       "type": "user"
273     }
274   }
275 ]
276 </pre>
277
278 You will need to create a "service principal" to use as a delegated authority for API access.
279
280 <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>
281 $ az ad sp create "<span class="userinput">appId</span>"
282 (appId is part of the response of the previous command)
283 $ az role assignment create --assignee "<span class="userinput">objectId</span>" --role Owner --scope /subscriptions/{subscriptionId}/
284 (objectId is part of the response of the previous command)
285 </code></pre></notextile>
286
287 Now update your @config.yml@ file:
288
289 @ClientID@ is the 'appId' value.
290
291 @ClientSecret@ is what was provided as <span class="userinput">Your_Password</span>.
292
293 h3. Test your configuration
294
295 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.
296
297 <notextile>
298 <pre><code>~$ <span class="userinput">arvados-server cloudtest && echo "OK!"</span>
299 </code></pre>
300 </notextile>
301
302 Refer to the "cloudtest tool documentation":../../admin/cloudtest.html for more information.
303
304 {% assign arvados_component = 'arvados-dispatch-cloud' %}
305
306 {% include 'install_packages' %}
307
308 {% include 'start_service' %}
309
310 {% include 'restart_api' %}
311
312 h2(#confirm-working). Confirm working installation
313
314 On the dispatch node, start monitoring the arvados-dispatch-cloud logs:
315
316 <notextile>
317 <pre><code>~$ <span class="userinput">sudo journalctl -o cat -fu arvados-dispatch-cloud.service</span>
318 </code></pre>
319 </notextile>
320
321 "Make sure to install the arvados/jobs image.":../install-jobs-image.html
322
323 Submit a simple container request:
324
325 <notextile>
326 <pre><code>shell:~$ <span class="userinput">arv container_request create --container-request '{
327   "name":            "test",
328   "state":           "Committed",
329   "priority":        1,
330   "container_image": "arvados/jobs:latest",
331   "command":         ["echo", "Hello, Crunch!"],
332   "output_path":     "/out",
333   "mounts": {
334     "/out": {
335       "kind":        "tmp",
336       "capacity":    1000
337     }
338   },
339   "runtime_constraints": {
340     "vcpus": 1,
341     "ram": 1048576
342   }
343 }'</span>
344 </code></pre>
345 </notextile>
346
347 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.
348
349 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:
350
351 <notextile>
352 <pre><code>~$ <span class="userinput">curl -sH "Authorization: Bearer $token" http://localhost:9006/arvados/v1/dispatch/containers</span>
353 {
354   "items": [
355     {
356       "container": {
357         "uuid": "zzzzz-dz642-hdp2vpu9nq14tx0",
358         ...
359         "state": "Running",
360         "scheduling_parameters": {
361           "partitions": null,
362           "preemptible": false,
363           "max_run_time": 0
364         },
365         "exit_code": 0,
366         "runtime_status": null,
367         "started_at": null,
368         "finished_at": null
369       },
370       "instance_type": {
371         "Name": "Standard_D2s_v3",
372         "ProviderType": "Standard_D2s_v3",
373         "VCPUs": 2,
374         "RAM": 8589934592,
375         "Scratch": 16000000000,
376         "IncludedScratch": 16000000000,
377         "AddedScratch": 0,
378         "Price": 0.11,
379         "Preemptible": false
380       }
381     }
382   ]
383 }
384 </code></pre>
385 </notextile>
386
387 A similar request can be made to the @http://localhost:9006/arvados/v1/dispatch/instances@ endpoint.
388
389 When the container finishes, the dispatcher will log it.
390
391 After the container finishes, you can get the container record by UUID *from a shell server* to see its results:
392
393 <notextile>
394 <pre><code>shell:~$ <span class="userinput">arv get <b>zzzzz-dz642-hdp2vpu9nq14tx0</b></span>
395 {
396  ...
397  "exit_code":0,
398  "log":"a01df2f7e5bc1c2ad59c60a837e90dc6+166",
399  "output":"d41d8cd98f00b204e9800998ecf8427e+0",
400  "state":"Complete",
401  ...
402 }
403 </code></pre>
404 </notextile>
405
406 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:
407
408 <notextile>
409 <pre><code>~$ <span class="userinput">arv keep ls <b>a01df2f7e5bc1c2ad59c60a837e90dc6+166</b></span>
410 ./crunch-run.txt
411 ./stderr.txt
412 ./stdout.txt
413 ~$ <span class="userinput">arv-get <b>a01df2f7e5bc1c2ad59c60a837e90dc6+166</b>/stdout.txt</span>
414 2016-08-05T13:53:06.201011Z Hello, Crunch!
415 </code></pre>
416 </notextile>
417
418 If the container does not dispatch successfully, refer to the @arvados-dispatch-cloud@ logs for information about why it failed.