doc/install/salt-multi-host.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Multi host Arvados
   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 # "Introduction":#introduction
  13 # "Prerequisites and planning":#prerequisites
  14 # "Download the installer":#download
  15 # "Copy and customize the configuration files":#copy_config
  16 # "Choose the SSL configuration":#certificates
  17 ## "Using a self-signed certificates":#self-signed
  18 ## "Using a Let's Encrypt certificates":#lets-encrypt
  19 ## "Bring your own certificates":#bring-your-own
  20 # "Create a compute image":#create_a_compute_image
  21 # "Further customization of the installation (modifying the salt pillars and states)":#further_customization
  22 # "Installation order":#installation_order
  23 # "Run the provision.sh script":#run_provision_script
  24 # "Install the CA root certificate":#ca_root_certificate
  25 # "Initial user and login":#initial_user
  26 # "Test the installed cluster running a simple workflow":#test_install
  27 # "After the installation":#post_install
  28
  29 h2(#introduction). Introduction
  30
  31 This multi host installer is an AWS specific example that is generally useful, but will likely need to be adapted for your environment. The installer is highly configurable.
  32
  33 h2(#prerequisites). Prerequisites and planning
  34
  35 Prerequisites:
  36
  37 * git
  38 * a number of (virtual) machines for your Arvados cluster with at least 2 cores and 8 GiB of RAM, running a "supported Arvados distribution":{{site.baseurl}}/install/install-manual-prerequisites.html#supportedlinux
  39 * a number of DNS hostnames that resolve to the IP addresses of your Arvados hosts
  40 * ports 443 need to be reachable from your client (configurable in @local.params@, see below)
  41 * port 80 needs to be reachable from everywhere on the internet (only when using "Let's Encrypt":#lets-encrypt without Route53 integration)
  42 * SSL certificatse matching the hostnames in use (only when using "bring your own certificates":#bring-your-own)
  43
  44 Planning:
  45
  46 We suggest distributing the Arvados components in the following way, creating at least 6 hosts:
  47
  48 # Database server:
  49 ## postgresql server
  50 # API node:
  51 ## arvados api server
  52 ## arvados controller
  53 ## arvados websocket
  54 ## arvados cloud dispatcher
  55 ## arvados keepbalance
  56 # WORKBENCH node:
  57 ## arvados workbench
  58 ## arvados workbench2
  59 ## arvados webshell
  60 # KEEPPROXY node:
  61 ## arvados keepproxy
  62 ## arvados keepweb
  63 # KEEPSTORE nodes (at least 2)
  64 ## arvados keepstore
  65 # SHELL node (optional):
  66 ## arvados shell
  67
  68 If your infrastructure differs from the setup proposed above (ie, using RDS or an existing DB server), remember that you will need to edit the configuration files for the scripts so they work with your infrastructure.
  69
  70 h2(#download). Download the installer
  71
  72 {% include 'download_installer' %}
  73
  74 h2(#copy_config). Copy and customize the configuration files
  75
  76 <notextile>
  77 <pre><code>cp local.params.example.multiple_hosts local.params
  78 cp -r config_examples/multi_host/aws local_config_dir
  79 </code></pre>
  80 </notextile>
  81
  82 Edit the variables in the <i>local.params</i> file. Pay attention to the <notextile><b>*_INT_IP, *_TOKEN</b> and <b>*_KEY</b></notextile> variables. The *SSL_MODE* variable is discussed in the next section.
  83
  84 {% include 'ssl_config_multi' %}
  85
  86 h2(#create_a_compute_image). Create a compute image
  87
  88 {% include 'branchname' %}
  89
  90 In a multi-host installation, containers are dispatched in docker daemons running in the <i>compute instances</i>, which need some special setup. We provide a "compute image builder script":https://github.com/arvados/arvados/tree/{{ branchname }}/tools/compute-images that you can use to build a template image following "these instructions":https://doc.arvados.org/install/crunch2-cloud/install-compute-node.html. Once you have that image created, you will need to update the <i>pillars/arvados.sls</i> file with the AMI ID and the private ssh key for the dispatcher.
  91
  92 h2(#further_customization). Further customization of the installation (modifying the salt pillars and states)
  93
  94 You will need further customization to suit your environment, which can be done editing the Saltstack pillars and states files. Pay particular attention to the <i>pillars/arvados.sls</i> file, where you will need to provide some information that describes your environment.
  95
  96 Any extra <i>state</i> file you add under <i>local_config_dir/states</i> will be added to the salt run and applied to the hosts.
  97
  98 h2(#installation_order). Installation order
  99
 100 A few Arvados nodes need to be installed in certain order. The required order is
 101
 102 * Database
 103 * API server
 104 * The other nodes can be installed in any order after the two above
 105
 106 h2(#run_provision_script). Run the provision.sh script
 107
 108 When you finished customizing the configuration, you are ready to copy the files to the hosts and run the @provision.sh@ script. The script allows you to specify the <i>role/s</i> a node will have and it will install only the Arvados components required for such role. The general format of the command is:
 109
 110 <notextile>
 111 <pre><code>scp -r provision.sh local* user@host:
 112 ssh user@host sudo ./provision.sh --roles comma,separated,list,of,roles,to,apply
 113 </code></pre>
 114 </notextile>
 115
 116 and wait for it to finish.
 117
 118 If everything goes OK, you'll get some final lines stating something like:
 119
 120 <notextile>
 121 <pre><code>arvados: Succeeded: 109 (changed=9)
 122 arvados: Failed:      0
 123 </code></pre>
 124 </notextile>
 125
 126 The distribution of role as described above can be applied running these commands:
 127
 128 h4. Database
 129 <notextile>
 130 <pre><code>scp -r provision.sh local* user@host:
 131 ssh user@host sudo ./provision.sh --config local.params --roles database
 132 </code></pre>
 133 </notextile>
 134
 135 h4. API
 136 <notextile>
 137 <pre><code>scp -r provision.sh local* user@host:
 138 ssh user@host sudo ./provision.sh --config local.params --roles api,controller,websocket,dispatcher,keepbalance
 139 </code></pre>
 140 </notextile>
 141
 142 h4. Keepstore(s)
 143 <notextile>
 144 <pre><code>scp -r provision.sh local* user@host:
 145 ssh user@host sudo ./provision.sh --config local.params --roles keepstore
 146 </code></pre>
 147 </notextile>
 148
 149 h4. Workbench
 150 <notextile>
 151 <pre><code>scp -r provision.sh local* user@host:
 152 ssh user@host sudo ./provision.sh --config local.params --roles workbench,workbench2,webshell
 153 </code></pre>
 154 </notextile>
 155
 156 h4. Keepproxy / Keepweb
 157 <notextile>
 158 <pre><code>scp -r provision.sh local* user@host:
 159 ssh user@host sudo ./provision.sh --config local.params --roles keepproxy,keepweb
 160 </code></pre>
 161 </notextile>
 162
 163 h4. Shell (here we copy the CLI test workflow too)
 164 <notextile>
 165 <pre><code>scp -r provision.sh local* tests user@host:
 166 ssh user@host sudo ./provision.sh --config local.params --roles shell
 167 </code></pre>
 168 </notextile>
 169
 170 {% include 'install_ca_cert' %}
 171
 172 h2(#initial_user). Initial user and login
 173
 174 At this point you should be able to log into the Arvados cluster. The initial URL will be:
 175
 176 * https://workbench.arva2.arv.local
 177
 178 or, in general, the url format will be:
 179
 180 * https://workbench.@<cluster>.<domain>@
 181
 182 By default, the provision script creates an initial user for testing purposes. This user is configured as administrator of the newly created cluster.
 183
 184 Assuming you didn't change these values in the @local.params@ file, the initial credentials are:
 185
 186 * User: 'admin'
 187 * Password: 'password'
 188 * Email: 'admin@arva2.arv.local'
 189
 190 h2(#test_install). Test the installed cluster running a simple workflow
 191
 192 If you followed the instructions above, the @provision.sh@ script saves a simple example test workflow in the @/tmp/cluster_tests@ directory in the @shell@ node. If you want to run it, just ssh to the node, change to that directory and run:
 193
 194 <notextile>
 195 <pre><code>cd /tmp/cluster_tests
 196 sudo /run-test.sh
 197 </code></pre>
 198 </notextile>
 199
 200 It will create a test user (by default, the same one as the admin user), upload a small workflow and run it. If everything goes OK, the output should similar to this (some output was shortened for clarity):
 201
 202 <notextile>
 203 <pre><code>Creating Arvados Standard Docker Images project
 204 Arvados project uuid is 'arva2-j7d0g-0prd8cjlk6kfl7y'
 205 {
 206  ...
 207  "uuid":"arva2-o0j2j-n4zu4cak5iifq2a",
 208  "owner_uuid":"arva2-tpzed-000000000000000",
 209  ...
 210 }
 211 Uploading arvados/jobs' docker image to the project
 212 2.1.1: Pulling from arvados/jobs
 213 8559a31e96f4: Pulling fs layer
 214 ...
 215 Status: Downloaded newer image for arvados/jobs:2.1.1
 216 docker.io/arvados/jobs:2.1.1
 217 2020-11-23 21:43:39 arvados.arv_put[32678] INFO: Creating new cache file at /home/vagrant/.cache/arvados/arv-put/c59256eda1829281424c80f588c7cc4d
 218 2020-11-23 21:43:46 arvados.arv_put[32678] INFO: Collection saved as 'Docker image arvados jobs:2.1.1 sha256:0dd50'
 219 arva2-4zz18-1u5pvbld7cvxuy2
 220 Creating initial user ('admin')
 221 Setting up user ('admin')
 222 {
 223  "items":[
 224   {
 225    ...
 226    "owner_uuid":"arva2-tpzed-000000000000000",
 227    ...
 228    "uuid":"arva2-o0j2j-1ownrdne0ok9iox"
 229   },
 230   {
 231    ...
 232    "owner_uuid":"arva2-tpzed-000000000000000",
 233    ...
 234    "uuid":"arva2-o0j2j-1zbeyhcwxc1tvb7"
 235   },
 236   {
 237    ...
 238    "email":"admin@arva2.arv.local",
 239    ...
 240    "owner_uuid":"arva2-tpzed-000000000000000",
 241    ...
 242    "username":"admin",
 243    "uuid":"arva2-tpzed-3wrm93zmzpshrq2",
 244    ...
 245   }
 246  ],
 247  "kind":"arvados#HashList"
 248 }
 249 Activating user 'admin'
 250 {
 251  ...
 252  "email":"admin@arva2.arv.local",
 253  ...
 254  "username":"admin",
 255  "uuid":"arva2-tpzed-3wrm93zmzpshrq2",
 256  ...
 257 }
 258 Running test CWL workflow
 259 INFO /usr/bin/cwl-runner 2.1.1, arvados-python-client 2.1.1, cwltool 3.0.20200807132242
 260 INFO Resolved 'hasher-workflow.cwl' to 'file:///tmp/cluster_tests/hasher-workflow.cwl'
 261 ...
 262 INFO Using cluster arva2 (https://arva2.arv.local:8443/)
 263 INFO Upload local files: "test.txt"
 264 INFO Uploaded to ea34d971b71d5536b4f6b7d6c69dc7f6+50 (arva2-4zz18-c8uvwqdry4r8jao)
 265 INFO Using collection cache size 256 MiB
 266 INFO [container hasher-workflow.cwl] submitted container_request arva2-xvhdp-v1bkywd58gyocwm
 267 INFO [container hasher-workflow.cwl] arva2-xvhdp-v1bkywd58gyocwm is Final
 268 INFO Overall process status is success
 269 INFO Final output collection d6c69a88147dde9d52a418d50ef788df+123
 270 {
 271     "hasher_out": {
 272         "basename": "hasher3.md5sum.txt",
 273         "class": "File",
 274         "location": "keep:d6c69a88147dde9d52a418d50ef788df+123/hasher3.md5sum.txt",
 275         "size": 95
 276     }
 277 }
 278 INFO Final process status is success
 279 </code></pre>
 280 </notextile>
 281
 282 h2(#post_install). After the installation
 283
 284 Once the installation is complete, it is recommended to keep a copy of your local configuration files. Committing them to version control is a good idea.
 285
 286 Re-running the Salt-based installer is not recommended for maintaining and upgrading Arvados, please see "Maintenance and upgrading":{{site.baseurl}}/admin/maintenance-and-upgrading.html for more information.