doc/install/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 a on premise 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(#create-image). Create compute node VM image
  31
  32 Create a VM image following the steps "to set up a compute node":crunch2-slurm/install-compute-node.html
  33
  34 On the compute VM image, add the API server's internal IP address to @/etc/hosts@, this will ensure that it contacts the API server on the private network and not through the public interface.  For example:
  35
  36 <notextile><pre><code>10.20.30.40     <span class="userinput">ClusterID.example.com</span>
  37 </code></pre></notextile>
  38
  39 h2(#update-config). Update config.yml
  40
  41 h3. Create a private key
  42
  43 Generate an SSH private key with no passphrase. Save it in the cluster configuration file (see @PrivateKey@ in the example below).
  44
  45 <notextile>
  46 <pre><code>~$ <span class="userinput">ssh-keygen -N '' -f ~/.ssh/id_dispatcher</span>
  47 Generating public/private rsa key pair.
  48 Your identification has been saved in /home/user/.ssh/id_dispatcher.
  49 Your public key has been saved in /home/user/.ssh/id_dispatcher.pub.
  50 The key fingerprint is:
  51 [...]
  52 ~$ <span class="userinput">cat ~/.ssh/id_dispatcher</span>
  53 -----BEGIN RSA PRIVATE KEY-----
  54 MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
  55 ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
  56 ...
  57 oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
  58 foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
  59 -----END RSA PRIVATE KEY-----
  60 </code></pre>
  61 </notextile>
  62
  63 You can delete the key files after you have copied the private key to your configuration file.
  64
  65 <notextile>
  66 <pre><code>~$ <span class="userinput">rm ~/.ssh/id_dispatcher ~/.ssh/id_dispatcher.pub</span>
  67 </code></pre>
  68 </notextile>
  69
  70 h3. Configure CloudVMs
  71
  72 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.
  73
  74 <notextile>
  75 <pre><code>    Services:
  76       DispatchCloud:
  77         InternalURLs:
  78           "http://localhost:9006": {}
  79     Containers:
  80       CloudVMs:
  81         # BootProbeCommand is a shell command that succeeds when an instance is ready for service
  82         BootProbeCommand: "sudo systemctl status docker"
  83
  84         <b># --- driver-specific configuration goes here --- see Amazon and Azure examples below ---</b>
  85
  86       DispatchPrivateKey: |
  87         -----BEGIN RSA PRIVATE KEY-----
  88         MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
  89         ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
  90         FJ+amZ7oYMDof6QEdwl6KNDfIddL+NfBCLQTVInOAaNss7GRrxLTuTV7HcRaIUUI
  91         jYg0Ibg8ZZTzQxCvFXXnjseTgmOcTv7CuuGdt91OVdoq8czG/w8TwOhymEb7mQlt
  92         lXuucwQvYgfoUgcnTgpJr7j+hafp75g2wlPozp8gJ6WQ2yBWcfqL2aw7m7Ll88Nd
  93         [...]
  94         oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
  95         foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
  96         -----END RSA PRIVATE KEY-----
  97     InstanceTypes:
  98       x1md:
  99         ProviderType: x1.medium
 100         VCPUs: 8
 101         RAM: 64GiB
 102         IncludedScratch: 64GB
 103         Price: 0.62
 104       x1lg:
 105         ProviderType: x1.large
 106         VCPUs: 16
 107         RAM: 128GiB
 108         IncludedScratch: 128GB
 109         Price: 1.23
 110 </code></pre>
 111 </notextile>
 112
 113 h4. Minimal configuration example for Amazon EC2
 114
 115 <notextile>
 116 <pre><code>    Containers:
 117       CloudVMs:
 118         ImageID: ami-01234567890abcdef
 119         Driver: ec2
 120         DriverParameters:
 121           AccessKeyID: XXXXXXXXXXXXXXXXXXXX
 122           SecretAccessKey: YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
 123           SecurityGroupIDs:
 124           - sg-0123abcd
 125           SubnetID: subnet-0123abcd
 126           Region: us-east-1
 127           EBSVolumeType: gp2
 128           AdminUsername: arvados
 129 </code></pre>
 130 </notextile>
 131
 132 h4. Minimal configuration example for Azure
 133
 134 <notextile>
 135 <pre><code>    Containers:
 136       CloudVMs:
 137         ImageID: "https://zzzzzzzz.blob.core.windows.net/system/Microsoft.Compute/Images/images/zzzzz-compute-osDisk.55555555-5555-5555-5555-555555555555.vhd"
 138         Driver: azure
 139         DriverParameters:
 140           SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 141           ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 142           ClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 143           TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 144           CloudEnvironment: AzurePublicCloud
 145           ResourceGroup: zzzzz
 146           Location: centralus
 147           Network: zzzzz
 148           Subnet: zzzzz-subnet-private
 149           StorageAccount: example
 150           BlobContainer: vhds
 151           DeleteDanglingResourcesAfter: 20s
 152           AdminUsername: arvados
 153 </code></pre>
 154 </notextile>
 155
 156 Get the @SubscriptionID@ and @TenantID@:
 157
 158 <pre>
 159 $ az account list
 160 [
 161   {
 162     "cloudName": "AzureCloud",
 163     "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
 164     "isDefault": true,
 165     "name": "Your Subscription",
 166     "state": "Enabled",
 167     "tenantId": "YYYYYYYY-YYYY-YYYY-YYYYYYYY",
 168     "user": {
 169       "name": "you@example.com",
 170       "type": "user"
 171     }
 172   }
 173 ]
 174 </pre>
 175
 176 You will need to create a "service principal" to use as a delegated authority for API access.
 177
 178 <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>
 179 $ az ad sp create "<span class="userinput">appId</span>"
 180 (appId is part of the response of the previous command)
 181 $ az role assignment create --assignee "<span class="userinput">objectId</span>" --role Owner --scope /subscriptions/{subscriptionId}/
 182 (objectId is part of the response of the previous command)
 183 </code></pre></notextile>
 184
 185 Now update your @config.yml@ file:
 186
 187 @ClientID@ is the 'appId' value.
 188
 189 @ClientSecret@ is what was provided as <span class="userinput">Your_Password</span>.
 190
 191 h3. Test your configuration
 192
 193 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.
 194
 195 <notextile>
 196 <pre><code>~$ <span class="userinput">arvados-server cloudtest && echo "OK!"</span>
 197 </code></pre>
 198 </notextile>
 199
 200 Refer to the "cloudtest tool documentation":../admin/cloudtest.html for more information.
 201
 202 {% assign arvados_component = 'arvados-dispatch-cloud' %}
 203
 204 {% include 'install_packages' %}
 205
 206 {% include 'start_service' %}
 207
 208 {% include 'restart_api' %}
 209
 210 h2(#confirm-working). Confirm working installation
 211
 212 On the dispatch node, start monitoring the arvados-dispatch-cloud logs:
 213
 214 <notextile>
 215 <pre><code>~$ <span class="userinput">sudo journalctl -o cat -fu arvados-dispatch-cloud.service</span>
 216 </code></pre>
 217 </notextile>
 218
 219 "Make sure to install the arvados/jobs image.":install-jobs-image.html
 220
 221 Submit a simple container request:
 222
 223 <notextile>
 224 <pre><code>shell:~$ <span class="userinput">arv container_request create --container-request '{
 225   "name":            "test",
 226   "state":           "Committed",
 227   "priority":        1,
 228   "container_image": "arvados/jobs:latest",
 229   "command":         ["echo", "Hello, Crunch!"],
 230   "output_path":     "/out",
 231   "mounts": {
 232     "/out": {
 233       "kind":        "tmp",
 234       "capacity":    1000
 235     }
 236   },
 237   "runtime_constraints": {
 238     "vcpus": 1,
 239     "ram": 1048576
 240   }
 241 }'</span>
 242 </code></pre>
 243 </notextile>
 244
 245 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.
 246
 247 The @arvados-dispatch-cloud@ API a list of queued and running jobs.  For example:
 248
 249 <notextile>
 250 <pre><code>~$ <span class="userinput">curl ...</span>
 251 </code></pre>
 252 </notextile>
 253
 254 When the container finishes, the dispatcher will log it.
 255
 256 After the container finishes, you can get the container record by UUID *from a shell server* to see its results:
 257
 258 <notextile>
 259 <pre><code>shell:~$ <span class="userinput">arv get <b>zzzzz-dz642-hdp2vpu9nq14tx0</b></span>
 260 {
 261  ...
 262  "exit_code":0,
 263  "log":"a01df2f7e5bc1c2ad59c60a837e90dc6+166",
 264  "output":"d41d8cd98f00b204e9800998ecf8427e+0",
 265  "state":"Complete",
 266  ...
 267 }
 268 </code></pre>
 269 </notextile>
 270
 271 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:
 272
 273 <notextile>
 274 <pre><code>~$ <span class="userinput">arv keep ls <b>a01df2f7e5bc1c2ad59c60a837e90dc6+166</b></span>
 275 ./crunch-run.txt
 276 ./stderr.txt
 277 ./stdout.txt
 278 ~$ <span class="userinput">arv-get <b>a01df2f7e5bc1c2ad59c60a837e90dc6+166</b>/stdout.txt</span>
 279 2016-08-05T13:53:06.201011Z Hello, Crunch!
 280 </code></pre>
 281 </notextile>
 282
 283 If the container does not dispatch successfully, refer to the @arvados-dispatch-cloud@ logs for information about why it failed.