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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the Crunch 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 dispatcher normally runs on the same host/VM as the API server.
  14
  15 h2. Test the Arvados job queue
  16
  17 Crunch dispatches work from the job queue on the Arvados API server.  Before you start installing the Crunch dispatcher, now's a good time to check that the API server and Git server can coordinate to create job records.  Run these commands *on your shell server* to create a collection, and a job to calculate the MD5 checksum of every file in it:
  18
  19 <notextile>
  20 <pre><code>~$ <span class="userinput">echo 'Hello, Crunch!' | arv-put --portable-data-hash -</span>
  21 &hellip;
  22 d40c7f35d80da669afb9db1896e760ad+49
  23 ~$ <span class="userinput">read -rd $'\000' newjob &lt;&lt;EOF; arv job create --job "$newjob"
  24 {"script_parameters":{"input":"d40c7f35d80da669afb9db1896e760ad+49"},
  25  "script_version":"0988acb472849dc0",
  26  "script":"hash",
  27  "repository":"arvados"}
  28 EOF</span>
  29 </code></pre>
  30 </notextile>
  31
  32 If you get the error
  33
  34 <pre>
  35 ArgumentError: Specified script_version does not resolve to a commit
  36 </pre>
  37
  38 it often means that the API server can't read the specified repository&mdash;either because it doesn't exist, or because the user running the API server doesn't have permission to read the repository files.  Check the API server's log (@/var/www/arvados-api/current/log/production.log@) for details, and double-check the instructions in the "Git server installation guide":install-arv-git-httpd.html.
  39
  40 If everything goes well, the API server should create a job record, and your @arv@ command will output the JSON for that record.  It should have state @Queued@ and script_version @0988acb472849dc08d576ee40493e70bde2132ca@.  If the job JSON includes those fields, you can proceed to install the Crunch dispatcher and a compute node.  This job will remain queued until you install those services.
  41
  42 h2. Perl SDK dependencies
  43
  44 Install the Perl SDK on the controller.
  45
  46 * See "Perl SDK":{{site.baseurl}}/sdk/perl/index.html page for details.
  47
  48 h2. Python SDK dependencies
  49
  50 Install the Python SDK and CLI tools on controller and all compute nodes.
  51
  52 * See "Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html page for details.
  53
  54 h2(#slurm). Set up SLURM
  55
  56 On the API server, install SLURM and munge, and generate a munge key.
  57
  58 On Debian-based systems:
  59
  60 <notextile>
  61 <pre><code>~$ <span class="userinput">sudo /usr/bin/apt-get install slurm-llnl munge</span>
  62 ~$ <span class="userinput">sudo /usr/sbin/create-munge-key</span>
  63 </code></pre>
  64 </notextile>
  65
  66 On Red Hat-based systems:
  67
  68 <notextile>
  69 <pre><code>~$ <span class="userinput">sudo yum install slurm munge slurm-munge</span>
  70 </code></pre>
  71 </notextile>
  72
  73 Now we need to give SLURM a configuration file.  On Debian-based systems, this is installed at @/etc/slurm-llnl/slurm.conf@.  On Red Hat-based systems, this is installed at @/etc/slurm/slurm.conf@.  Here's an example @slurm.conf@:
  74
  75 <notextile>
  76 <pre>
  77 ControlMachine=uuid_prefix.your.domain
  78 SlurmctldPort=6817
  79 SlurmdPort=6818
  80 AuthType=auth/munge
  81 StateSaveLocation=/tmp
  82 SlurmdSpoolDir=/tmp/slurmd
  83 SwitchType=switch/none
  84 MpiDefault=none
  85 SlurmctldPidFile=/var/run/slurmctld.pid
  86 SlurmdPidFile=/var/run/slurmd.pid
  87 ProctrackType=proctrack/pgid
  88 CacheGroups=0
  89 ReturnToService=2
  90 TaskPlugin=task/affinity
  91 #
  92 # TIMERS
  93 SlurmctldTimeout=300
  94 SlurmdTimeout=300
  95 InactiveLimit=0
  96 MinJobAge=300
  97 KillWait=30
  98 Waittime=0
  99 #
 100 # SCHEDULING
 101 SchedulerType=sched/backfill
 102 SchedulerPort=7321
 103 SelectType=select/linear
 104 FastSchedule=0
 105 #
 106 # LOGGING
 107 SlurmctldDebug=3
 108 #SlurmctldLogFile=
 109 SlurmdDebug=3
 110 #SlurmdLogFile=
 111 JobCompType=jobcomp/none
 112 #JobCompLoc=
 113 JobAcctGatherType=jobacct_gather/none
 114 #
 115 # COMPUTE NODES
 116 NodeName=DEFAULT
 117 PartitionName=DEFAULT MaxTime=INFINITE State=UP
 118
 119 NodeName=compute[0-255]
 120 PartitionName=compute Nodes=compute[0-255] Default=YES Shared=YES
 121 </pre>
 122 </notextile>
 123
 124 h3. SLURM configuration essentials
 125
 126 Whenever you change this file, you will need to update the copy _on every compute node_ as well as the controller node, and then run @sudo scontrol reconfigure@.
 127
 128 *@ControlMachine@* should be a DNS name that resolves to the SLURM controller (dispatch/API server). This must resolve correctly on all SLURM worker nodes as well as the controller itself. In general SLURM is very sensitive about all of the nodes being able to communicate with the controller _and one another_, all using the same DNS names.
 129
 130 *@NodeName=compute[0-255]@* establishes that the hostnames of the worker nodes will be compute0, compute1, etc. through compute255.
 131 * There are several ways to compress sequences of names, like @compute[0-9,80,100-110]@. See the "hostlist" discussion in the @slurm.conf(5)@ and @scontrol(1)@ man pages for more information.
 132 * It is not necessary for all of the nodes listed here to be alive in order for SLURM to work, although you should make sure the DNS entries exist. It is easiest to define lots of hostnames up front, assigning them to real nodes and updating your DNS records as the nodes appear. This minimizes the frequency of @slurm.conf@ updates and use of @scontrol reconfigure@.
 133
 134 Each hostname in @slurm.conf@ must also resolve correctly on all SLURM worker nodes as well as the controller itself. Furthermore, the hostnames used in the configuration file must match the hostnames reported by @hostname@ or @hostname -s@ on the nodes themselves. This applies to the ControlMachine as well as the worker nodes.
 135
 136 For example:
 137 * In @slurm.conf@ on control and worker nodes: @ControlMachine=uuid_prefix.your.domain@
 138 * In @slurm.conf@ on control and worker nodes: @NodeName=compute[0-255]@
 139 * In @/etc/resolv.conf@ on control and worker nodes: @search uuid_prefix.your.domain@
 140 * On the control node: @hostname@ reports @uuid_prefix.your.domain@
 141 * On worker node 123: @hostname@ reports @compute123.uuid_prefix.your.domain@
 142
 143 h3. Automatic hostname assignment
 144
 145 If your worker node bootstrapping script (see "Installing a compute node":install-compute-node.html) does not send the worker's current hostname, the API server will choose an unused hostname from the set given in @application.yml@, which defaults to @compute[0-255]@.
 146
 147 If it is not feasible to give your compute nodes hostnames like compute0, compute1, etc., you can accommodate other naming schemes with a bit of extra configuration.
 148
 149 If you want Arvados to assign names to your nodes with a different consecutive numeric series like @{worker1-0000, worker1-0001, worker1-0002}@, add an entry to @application.yml@; see @/var/www/arvados-api/current/config/application.default.yml@ for details. Example:
 150 * In @application.yml@: <code>assign_node_hostname: worker1-%<slot_number>04d</code>
 151 * In @slurm.conf@: <code>NodeName=worker1-[0000-0255]</code>
 152
 153 If your worker hostnames are already assigned by other means, and the full set of names is known in advance, have your worker node bootstrapping script (see "Installing a compute node":install-compute-node.html) send its current hostname, rather than expect Arvados to assign one.
 154 * In @application.yml@: <code>assign_node_hostname: false</code>
 155 * In @slurm.conf@: <code>NodeName=alice,bob,clay,darlene</code>
 156
 157 If your worker hostnames are already assigned by other means, but the full set of names is _not_ known in advance, you can use the @slurm.conf@ and @application.yml@ settings in the previous example, but you must also update @slurm.conf@ (both on the controller and on all worker nodes) and run @sudo scontrol reconfigure@ whenever a new node comes online.
 158
 159 h2. Enable SLURM job dispatch
 160
 161 In your API server's @application.yml@ configuration file, add the line @crunch_job_wrapper: :slurm_immediate@ under the appropriate section.  (The second colon is not a typo.  It denotes a Ruby symbol.)
 162
 163 h2. Crunch user account
 164
 165 Run @sudo adduser crunch@.  The crunch user should have the same UID, GID, and home directory on all compute nodes and on the dispatcher (API server).
 166
 167 h2. Run the Crunch dispatcher service
 168
 169 To dispatch Arvados jobs:
 170
 171 * The API server script @crunch-dispatch.rb@ must be running.
 172 * @crunch-job@ needs the installation path of the Perl SDK in its @PERLLIB@.
 173 * @crunch-job@ needs the @ARVADOS_API_HOST@ (and, if necessary, @ARVADOS_API_HOST_INSECURE@) environment variable set.
 174
 175 Install runit to monitor the Crunch dispatch daemon.  {% include 'install_runit' %}
 176
 177 Install the script below as the run script for the Crunch dispatch service, modifying it as directed by the comments.
 178
 179 <notextile>
 180 <pre><code>#!/bin/sh
 181 set -e
 182
 183 rvmexec=""
 184 ## Uncomment this line if you use RVM:
 185 #rvmexec="/usr/local/rvm/bin/rvm-exec default"
 186
 187 export ARVADOS_API_HOST=<span class="userinput">uuid_prefix.your.domain</span>
 188 export CRUNCH_DISPATCH_LOCKFILE=/var/lock/crunch-dispatch
 189 export HOME=$(pwd)
 190 export RAILS_ENV=production
 191
 192 ## Uncomment and edit this line if your compute nodes have cgroup info
 193 ## somewhere other than /sys/fs/cgroup (e.g., "/cgroup" for CentOS 7)
 194 #export CRUNCH_CGROUP_ROOT="/sys/fs/cgroup"
 195
 196 ## Uncomment this line if your cluster uses self-signed SSL certificates:
 197 #export ARVADOS_API_HOST_INSECURE=yes
 198
 199 # This is the path to docker on your compute nodes. You might need to
 200 # change it to "docker", "/opt/bin/docker", etc.
 201 export CRUNCH_JOB_DOCKER_BIN=<span class="userinput">docker.io</span>
 202
 203 fuser -TERM -k $CRUNCH_DISPATCH_LOCKFILE || true
 204 cd /var/www/arvados-api/current
 205 exec $rvmexec bundle exec ./script/crunch-dispatch.rb 2>&1
 206 </code></pre>
 207 </notextile>