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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the Crunch dispatcher
   5
   6 ...
   7
   8 The dispatcher normally runs on the same host/VM as the API server.
   9
  10 h2. Perl SDK dependencies
  11
  12 Install the Perl SDK on the controller.
  13
  14 * See "Perl SDK":{{site.baseurl}}/sdk/perl/index.html page for details.
  15
  16 h2. Python SDK dependencies
  17
  18 Install the Python SDK and CLI tools on controller and all compute nodes.
  19
  20 * See "Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html page for details.
  21
  22 h2(#slurm). Set up SLURM
  23
  24 On the API server, install SLURM and munge, and generate a munge key.
  25
  26 On Debian-based systems:
  27
  28 <notextile>
  29 <pre><code>~$ <span class="userinput">sudo /usr/bin/apt-get install slurm-llnl munge</span>
  30 ~$ <span class="userinput">sudo /usr/sbin/create-munge-key</span>
  31 </code></pre>
  32 </notextile>
  33
  34 On Red Hat-based systems, "install SLURM and munge from source following their installation guide":https://computing.llnl.gov/linux/slurm/quickstart_admin.html.
  35
  36 Now we need to give SLURM a configuration file in @/etc/slurm-llnl/slurm.conf@. Here's an example:
  37
  38 <notextile>
  39 <pre>
  40 ControlMachine=uuid_prefix.your.domain
  41 SlurmctldPort=6817
  42 SlurmdPort=6818
  43 AuthType=auth/munge
  44 StateSaveLocation=/tmp
  45 SlurmdSpoolDir=/tmp/slurmd
  46 SwitchType=switch/none
  47 MpiDefault=none
  48 SlurmctldPidFile=/var/run/slurmctld.pid
  49 SlurmdPidFile=/var/run/slurmd.pid
  50 ProctrackType=proctrack/pgid
  51 CacheGroups=0
  52 ReturnToService=2
  53 TaskPlugin=task/affinity
  54 #
  55 # TIMERS
  56 SlurmctldTimeout=300
  57 SlurmdTimeout=300
  58 InactiveLimit=0
  59 MinJobAge=300
  60 KillWait=30
  61 Waittime=0
  62 #
  63 # SCHEDULING
  64 SchedulerType=sched/backfill
  65 SchedulerPort=7321
  66 SelectType=select/cons_res
  67 SelectTypeParameters=CR_CPU_Memory
  68 FastSchedule=1
  69 #
  70 # LOGGING
  71 SlurmctldDebug=3
  72 #SlurmctldLogFile=
  73 SlurmdDebug=3
  74 #SlurmdLogFile=
  75 JobCompType=jobcomp/none
  76 #JobCompLoc=
  77 JobAcctGatherType=jobacct_gather/none
  78 #
  79 # COMPUTE NODES
  80 NodeName=DEFAULT
  81 PartitionName=DEFAULT MaxTime=INFINITE State=UP
  82 PartitionName=compute Default=YES Shared=yes
  83
  84 NodeName=compute[0-255]
  85 PartitionName=compute Nodes=compute[0-255]
  86 </pre>
  87 </notextile>
  88
  89 h3. SLURM configuration essentials
  90
  91 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@.
  92
  93 *@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.
  94
  95 *@NodeName=compute[0-255]@* establishes that the hostnames of the worker nodes will be compute0, compute1, etc. through compute255.
  96 * 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.
  97 * 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@.
  98
  99 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.
 100
 101 For example:
 102 * In @/etc/slurm-llnl/slurm.conf@ on control and worker nodes: @ControlMachine=uuid_prefix.your.domain@
 103 * In @/etc/slurm-llnl/slurm.conf@ on control and worker nodes: @NodeName=compute[0-255]@
 104 * In @/etc/resolv.conf@ on control and worker nodes: @search uuid_prefix.your.domain@
 105 * On the control node: @hostname@ reports @uuid_prefix.your.domain@
 106 * On worker node 123: @hostname@ reports @compute123.uuid_prefix.your.domain@
 107
 108 h3. Automatic hostname assignment
 109
 110 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]@.
 111
 112 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.
 113
 114 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:
 115 * In @application.yml@: <code>assign_node_hostname: worker1-%<slot_number>04d</code>
 116 * In @slurm.conf@: <code>NodeName=worker1-[0000-0255]</code>
 117
 118 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.
 119 * In @application.yml@: <code>assign_node_hostname: false</code>
 120 * In @slurm.conf@: <code>NodeName=alice,bob,clay,darlene</code>
 121
 122 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.
 123
 124 h2. Enable SLURM job dispatch
 125
 126 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.)
 127
 128 h2. Crunch user account
 129
 130 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).
 131
 132 h2. Git Repositories
 133
 134 Crunch scripts must be in Git repositories in the directory configured as @git_repositories_dir@/*.git (see the "API server installation":install-api-server.html#git_repositories_dir).
 135
 136 Once you have a repository with commits -- and you have read access to the repository -- you should be able to create a new job:
 137
 138 <pre>
 139 read -rd $'\000' newjob <<EOF; arv job create --job "$newjob"
 140 {"script_parameters":{"input":"f815ec01d5d2f11cb12874ab2ed50daa"},
 141  "script_version":"master",
 142  "script":"hash",
 143  "repository":"arvados"}
 144 EOF
 145 </pre>
 146
 147 Without getting this error:
 148
 149 <pre>
 150 ArgumentError: Specified script_version does not resolve to a commit
 151 </pre>
 152
 153 h2. Running jobs
 154
 155 * @services/api/script/crunch-dispatch.rb@ must be running.
 156 * @crunch-dispatch.rb@ needs @services/crunch/crunch-job@ in its @PATH@.
 157 * @crunch-job@ needs the installation path of the Perl SDK in its @PERLLIB@.
 158 * @crunch-job@ needs the @ARVADOS_API_HOST@ (and, if necessary in a development environment, @ARVADOS_API_HOST_INSECURE@) environment variable set.
 159
 160 Example @/var/service/arvados_crunch_dispatch/run@ script:
 161
 162 <pre>
 163 #!/bin/sh
 164 set -e
 165
 166 rvmexec=""
 167 ## uncomment this line if you use rvm:
 168 #rvmexec="/usr/local/rvm/bin/rvm-exec 2.1.1"
 169
 170 export PATH="$PATH":/path/to/arvados/services/crunch
 171 export ARVADOS_API_HOST={{ site.arvados_api_host }}
 172 export CRUNCH_DISPATCH_LOCKFILE=/var/lock/crunch-dispatch
 173
 174 # This is the path to docker on your compute nodes. You might need to
 175 # change it to "docker", "/opt/bin/docker", etc.
 176 export CRUNCH_JOB_DOCKER_BIN=docker.io
 177
 178 fuser -TERM -k $CRUNCH_DISPATCH_LOCKFILE || true
 179
 180 ## Only if your SSL cert is unverifiable:
 181 # export ARVADOS_API_HOST_INSECURE=yes
 182
 183 cd /path/to/arvados/services/api
 184 export RAILS_ENV=production
 185 exec $rvmexec bundle exec ./script/crunch-dispatch.rb 2>&1
 186 </pre>