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":https://dev.arvados.org/projects/arvados/repository/revisions/13996-new-api-config/entry/lib/config/config.defaults.yml 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     CloudVMs:
  76       # BootProbeCommand is a shell command that succeeds when an instance is ready for service
  77       BootProbeCommand: "sudo systemctl status docker"
  78
  79       <b># --- driver-specific configuration goes here --- see Amazon and Azure examples below ---</b>
  80
  81     Dispatch:
  82       PrivateKey: |
  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     CloudVMs:
 115       ImageID: ami-01234567890abcdef
 116       Driver: ec2
 117       DriverParameters:
 118         AccessKeyID: EALMF21BJC7MKNF9FVVR
 119         SecretAccessKey: yKJAPmoCQOMtYWzEUQ1tKTyrocTcbH60CRvGP3pM
 120         SecurityGroupIDs:
 121         - sg-0123abcd
 122         SubnetID: subnet-0123abcd
 123         Region: us-east-1
 124         EBSVolumeType: gp2
 125         AdminUsername: debian
 126 </code></pre>
 127 </notextile>
 128
 129 Minimal configuration example for Azure:
 130
 131 <notextile>
 132 <pre><code>Clusters:
 133   <span class="userinput">uuid_prefix</span>:
 134     CloudVMs:
 135       ImageID: "https://zzzzzzzz.blob.core.windows.net/system/Microsoft.Compute/Images/images/zzzzz-compute-osDisk.55555555-5555-5555-5555-555555555555.vhd"
 136       Driver: azure
 137       DriverParameters:
 138         SubscriptionID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 139         ClientID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 140         ClientSecret: 2WyXt0XFbEtutnf2hp528t6Wk9S5bOHWkRaaWwavKQo=
 141         TenantID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 142         CloudEnvironment: AzurePublicCloud
 143         ResourceGroup: zzzzz
 144         Location: centralus
 145         Network: zzzzz
 146         Subnet: zzzzz-subnet-private
 147         StorageAccount: example
 148         BlobContainer: vhds
 149         DeleteDanglingResourcesAfter: 20s
 150         AdminUsername: arvados
 151 </code></pre>
 152 </notextile>
 153
 154 h2. Install the dispatcher
 155
 156 First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos.
 157
 158 On Red Hat-based systems:
 159
 160 <notextile>
 161 <pre><code>~$ <span class="userinput">sudo yum install arvados-dispatch-cloud</span>
 162 ~$ <span class="userinput">sudo systemctl enable arvados-dispatch-cloud</span>
 163 </code></pre>
 164 </notextile>
 165
 166 On Debian-based systems:
 167
 168 <notextile>
 169 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-dispatch-cloud</span>
 170 </code></pre>
 171 </notextile>
 172
 173 {% include 'notebox_begin' %}
 174
 175 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.
 176
 177 {% include 'notebox_end' %}
 178
 179 h2. Verify the dispatcher is running
 180
 181 Use your ManagementToken to test the dispatcher's metrics endpoint.
 182
 183 <notextile>
 184 <pre><code>~$ <span class="userinput">token="xyzzy"</span>
 185 ~$ <span class="userinput">curl -H "Authorization: Bearer $token" http://localhost:9006/metrics</span>
 186 # HELP arvados_dispatchcloud_containers_running Number of containers reported running by cloud VMs.
 187 # TYPE arvados_dispatchcloud_containers_running gauge
 188 arvados_dispatchcloud_containers_running 0
 189 [...]
 190 </code></pre>
 191 </notextile>