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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the cloud dispatcher
   5
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 The cloud dispatch service is an *experimental* service for running containers on cloud VMs. It eliminates the need for SLURM, Node Manager, and SLURM dispatcher. It works with Microsoft Azure and Amazon EC2; future versions will also support Google Compute Engine.
  14
  15 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.
  16
  17 *Only one dispatch process should be running at a time.* If you are migrating a system that currently runs @crunch-dispatch-slurm@, it is safest to remove the @crunch-dispatch-slurm@ service entirely before installing @arvados-dispatch-cloud@.
  18
  19 <notextile>
  20 <pre><code>~$ <span class="userinput">sudo systemctl --now disable crunch-dispatch-slurm</span>
  21 ~$ <span class="userinput">sudo apt-get remove crunch-dispatch-slurm</span>
  22 </code></pre>
  23 </notextile>
  24
  25 h2. Create a dispatcher token
  26
  27 If you haven't already done so, create an Arvados superuser token to use as SystemRootToken in your cluster config file.
  28
  29 {% include 'create_superuser_token' %}
  30
  31 h2. Create a private key
  32
  33 Generate an SSH private key with no passphrase. Save it in the cluster configuration file (see @PrivateKey@ in the example below).
  34
  35 <notextile>
  36 <pre><code>~$ <span class="userinput">ssh-keygen -N '' -f ~/.ssh/id_dispatcher</span>
  37 Generating public/private rsa key pair.
  38 Your identification has been saved in /home/user/.ssh/id_dispatcher.
  39 Your public key has been saved in /home/user/.ssh/id_dispatcher.pub.
  40 The key fingerprint is:
  41 [...]
  42 ~$ <span class="userinput">cat ~/.ssh/id_dispatcher</span>
  43 -----BEGIN RSA PRIVATE KEY-----
  44 MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
  45 ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
  46 ...
  47 oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
  48 foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
  49 -----END RSA PRIVATE KEY-----
  50 </code></pre>
  51 </notextile>
  52
  53 You can delete the key files after you have copied the private key to your configuration file.
  54
  55 <notextile>
  56 <pre><code>~$ <span class="userinput">rm ~/.ssh/id_dispatcher ~/.ssh/id_dispatcher.pub</span>
  57 </code></pre>
  58 </notextile>
  59
  60 h2. Configure the dispatcher
  61
  62 Add or update the following portions of your cluster configuration file, @/etc/arvados/config.yml@. Refer to "config.defaults.yml":{{site.baseurl}}/admin/config.html for information about additional configuration options.
  63
  64 <notextile>
  65 <pre><code>Clusters:
  66   <span class="userinput">uuid_prefix</span>:
  67     ManagementToken: xyzzy
  68     SystemRootToken: <span class="userinput">zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</span>
  69     Services:
  70       Controller:
  71         ExternalURL: "https://<span class="userinput">uuid_prefix.arvadosapi.com</span>"
  72       DispatchCloud:
  73         InternalURLs:
  74           "http://localhost:9006": {}
  75     Containers:
  76       CloudVMs:
  77         # BootProbeCommand is a shell command that succeeds when an instance is ready for service
  78         BootProbeCommand: "sudo systemctl status docker"
  79
  80         <b># --- driver-specific configuration goes here --- see Amazon and Azure examples below ---</b>
  81
  82       DispatchPrivateKey: |
  83         -----BEGIN RSA PRIVATE KEY-----
  84         MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
  85         ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
  86         FJ+amZ7oYMDof6QEdwl6KNDfIddL+NfBCLQTVInOAaNss7GRrxLTuTV7HcRaIUUI
  87         jYg0Ibg8ZZTzQxCvFXXnjseTgmOcTv7CuuGdt91OVdoq8czG/w8TwOhymEb7mQlt
  88         lXuucwQvYgfoUgcnTgpJr7j+hafp75g2wlPozp8gJ6WQ2yBWcfqL2aw7m7Ll88Nd
  89         [...]
  90         oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
  91         foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
  92         -----END RSA PRIVATE KEY-----
  93     InstanceTypes:
  94       x1md:
  95         ProviderType: x1.medium
  96         VCPUs: 8
  97         RAM: 64GiB
  98         IncludedScratch: 64GB
  99         Price: 0.62
 100       x1lg:
 101         ProviderType: x1.large
 102         VCPUs: 16
 103         RAM: 128GiB
 104         IncludedScratch: 128GB
 105         Price: 1.23
 106 </code></pre>
 107 </notextile>
 108
 109 Minimal configuration example for Amazon EC2:
 110
 111 <notextile>
 112 <pre><code>Clusters:
 113   <span class="userinput">uuid_prefix</span>:
 114     Containers:
 115       CloudVMs:
 116         ImageID: ami-01234567890abcdef
 117         Driver: ec2
 118         DriverParameters:
 119           AccessKeyID: EALMF21BJC7MKNF9FVVR
 120           SecretAccessKey: yKJAPmoCQOMtYWzEUQ1tKTyrocTcbH60CRvGP3pM
 121           SecurityGroupIDs:
 122           - sg-0123abcd
 123           SubnetID: subnet-0123abcd
 124           Region: us-east-1
 125           EBSVolumeType: gp2
 126           AdminUsername: debian
 127 </code></pre>
 128 </notextile>
 129
 130 Minimal configuration example for Azure:
 131
 132 <notextile>
 133 <pre><code>Clusters:
 134   <span class="userinput">uuid_prefix</span>:
 135     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: 2WyXt0XFbEtutnf2hp528t6Wk9S5bOHWkRaaWwavKQo=
 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 h2. Test your configuration
 157
 158 First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos.
 159
 160 Next, install the arvados-server package.
 161
 162 On Red Hat-based systems:
 163
 164 <notextile>
 165 <pre><code>~$ <span class="userinput">sudo yum install arvados-server</span>
 166 </code></pre>
 167 </notextile>
 168
 169 On Debian-based systems:
 170
 171 <notextile>
 172 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-server</span>
 173 </code></pre>
 174 </notextile>
 175
 176 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.
 177
 178 <notextile>
 179 <pre><code>~$ <span class="userinput">arvados-server cloudtest && echo "OK!"</span>
 180 </code></pre>
 181 </notextile>
 182
 183 Refer to the "cloudtest tool documentation":../admin/cloudtest.html for more information.
 184
 185 h2. Install the dispatcher
 186
 187 On Red Hat-based systems:
 188
 189 <notextile>
 190 <pre><code>~$ <span class="userinput">sudo yum install arvados-dispatch-cloud</span>
 191 ~$ <span class="userinput">sudo systemctl enable arvados-dispatch-cloud</span>
 192 </code></pre>
 193 </notextile>
 194
 195 On Debian-based systems:
 196
 197 <notextile>
 198 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-dispatch-cloud</span>
 199 </code></pre>
 200 </notextile>
 201
 202 {% include 'notebox_begin' %}
 203
 204 The arvados-dispatch-cloud package includes configuration files for systemd. If you're using a different init system, configure a service to start and stop an @arvados-dispatch-cloud@ process as desired.
 205
 206 {% include 'notebox_end' %}
 207
 208 h2. Verify the dispatcher is running
 209
 210 Use your ManagementToken to test the dispatcher's metrics endpoint.
 211
 212 <notextile>
 213 <pre><code>~$ <span class="userinput">token="xyzzy"</span>
 214 ~$ <span class="userinput">curl -H "Authorization: Bearer $token" http://localhost:9006/metrics</span>
 215 # HELP arvados_dispatchcloud_containers_running Number of containers reported running by cloud VMs.
 216 # TYPE arvados_dispatchcloud_containers_running gauge
 217 arvados_dispatchcloud_containers_running 0
 218 [...]
 219 </code></pre>
 220 </notextile>