doc/install/crunch2-slurm/install-dispatch.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the SLURM 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 SLURM dispatcher can run on any node that can submit requests to both the Arvados API server and the SLURM controller.  It is not resource-intensive, so you can run it on the API server node.
  14
  15 h2. Install the dispatcher
  16
  17 First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/install-manual-prerequisites.html#repos.
  18
  19 On Red Hat-based systems:
  20
  21 <notextile>
  22 <pre><code>~$ <span class="userinput">sudo yum install crunch-dispatch-slurm</span>
  23 ~$ <span class="userinput">sudo systemctl enable crunch-dispatch-slurm</span>
  24 </code></pre>
  25 </notextile>
  26
  27 On Debian-based systems:
  28
  29 <notextile>
  30 <pre><code>~$ <span class="userinput">sudo apt-get install crunch-dispatch-slurm</span>
  31 </code></pre>
  32 </notextile>
  33
  34 h2. Create a dispatcher token
  35
  36 Create an Arvados superuser token for use by the dispatcher. If you have multiple dispatch processes, you should give each one a different token.  *On the API server*, run:
  37
  38 <notextile>
  39 <pre><code>apiserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
  40 apiserver:/var/www/arvados-api/current$ <span class="userinput">sudo -u <b>webserver-user</b> RAILS_ENV=production bundle exec script/create_superuser_token.rb</span>
  41 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  42 </code></pre>
  43 </notextile>
  44
  45 h2. Configure the dispatcher
  46
  47 Set up crunch-dispatch-slurm's configuration directory:
  48
  49 <notextile>
  50 <pre><code>~$ <span class="userinput">sudo mkdir -p /etc/arvados</span>
  51 ~$ <span class="userinput">sudo install -d -o -root -g <b>crunch</b> -m 0750 /etc/arvados/crunch-dispatch-slurm</span>
  52 </code></pre>
  53 </notextile>
  54
  55 Edit @/etc/arvados/crunch-dispatch-slurm/crunch-dispatch-slurm.yml@ to authenticate to your Arvados API server, using the token you generated in the previous step.  Follow this YAML format:
  56
  57 <notextile>
  58 <pre><code class="userinput">Client:
  59   APIHost: <b>zzzzz.arvadosapi.com</b>
  60   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
  61 </code></pre>
  62 </notextile>
  63
  64 This is the only configuration required by crunch-dispatch-slurm.  The subsections below describe optional configuration flags you can set inside the main configuration object.
  65
  66 h3. Client::KeepServiceURIs
  67
  68 Override Keep service discovery with a predefined list of Keep URIs. This can be useful if the compute nodes run a local keepstore that should handle all Keep traffic. Example:
  69
  70 <notextile>
  71 <pre><code class="userinput">Client:
  72   APIHost: <b>zzzzz.arvadosapi.com</b>
  73   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
  74   KeepServiceURIs:
  75   - <b>http://127.0.0.1:25107</b>
  76 </code></pre>
  77 </notextile>
  78
  79 h3. PollPeriod
  80
  81 crunch-dispatch-slurm polls the API server periodically for new containers to run.  The @PollPeriod@ option controls how often this poll happens.  Set this to a string of numbers suffixed with one of the time units @ns@, @us@, @ms@, @s@, @m@, or @h@.  For example:
  82
  83 <notextile>
  84 <pre><code class="userinput">Client:
  85   APIHost: <b>zzzzz.arvadosapi.com</b>
  86   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
  87 PollPeriod: <b>3m30s</b>
  88 </code></pre>
  89 </notextile>
  90
  91 h3. SbatchArguments
  92
  93 When crunch-dispatch-slurm invokes @sbatch@, you can add switches to the command by specifying @SbatchArguments@.  You can use this to send the jobs to specific cluster partitions or add resource requests.  Set @SbatchArguments@ to an array of strings.  For example:
  94
  95 <notextile>
  96 <pre><code class="userinput">Client:
  97   APIHost: <b>zzzzz.arvadosapi.com</b>
  98   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
  99 SbatchArguments:
 100 - <b>"--partition=PartitionName"</b>
 101 </code></pre>
 102 </notextile>
 103
 104 h3. CrunchRunCommand: Dispatch to SLURM cgroups
 105
 106 If your SLURM cluster uses the @task/cgroup@ TaskPlugin, you can configure Crunch's Docker containers to be dispatched inside SLURM's cgroups.  This provides consistent enforcement of resource constraints.  To do this, use a crunch-dispatch-slurm configuration like the following:
 107
 108 <notextile>
 109 <pre><code class="userinput">Client:
 110   APIHost: <b>zzzzz.arvadosapi.com</b>
 111   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
 112 CrunchRunCommand:
 113 - <b>crunch-run</b>
 114 - <b>"-cgroup-parent-subsystem=memory"</b>
 115 </code></pre>
 116 </notextile>
 117
 118 The choice of subsystem ("memory" in this example) must correspond to one of the resource types enabled in SLURM's @cgroup.conf@. Limits for other resource types will also be respected.  The specified subsystem is singled out only to let Crunch determine the name of the cgroup provided by SLURM.
 119
 120 {% include 'notebox_begin' %}
 121
 122 Some versions of Docker (at least 1.9), when run under systemd, require the cgroup parent to be specified as a systemd slice.  This causes an error when specifying a cgroup parent created outside systemd, such as those created by SLURM.
 123
 124 You can work around this issue by disabling the Docker daemon's systemd integration.  This makes it more difficult to manage Docker services with systemd, but Crunch does not require that functionality, and it will be able to use SLURM's cgroups as container parents.  To do this, "configure the Docker daemon on all compute nodes":install-compute-node.html#configure_docker_daemon to run with the option @--exec-opt native.cgroupdriver=cgroupfs@.
 125
 126 {% include 'notebox_end' %}
 127
 128 h3. CrunchRunCommand: Using host networking for containers
 129
 130 Older Linux kernels (prior to 3.18) have bugs in network namespace handling which can lead to compute node lockups.  This by is indicated by blocked kernel tasks in "Workqueue: netns cleanup_net".   If you are experiencing this problem, as a workaround you can disable use of network namespaces by Docker across the cluster.  Be aware this reduces container isolation, which may be a security risk.
 131
 132 <notextile>
 133 <pre><code class="userinput">Client:
 134   APIHost: <b>zzzzz.arvadosapi.com</b>
 135   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
 136 CrunchRunCommand:
 137 - <b>crunch-run</b>
 138 - <b>"-container-enable-networking=always"</b>
 139 - <b>"-container-network-mode=host"</b>
 140 </code></pre>
 141 </notextile>
 142
 143 h3. MinRetryPeriod: Rate-limit repeated attempts to start containers
 144
 145 If SLURM is unable to run a container, the dispatcher will submit it again after the next PollPeriod. If PollPeriod is very short, this can be excessive. If MinRetryPeriod is set, the dispatcher will avoid submitting the same container to SLURM more than once in the given time span.
 146
 147 <notextile>
 148 <pre><code class="userinput">Client:
 149   APIHost: <b>zzzzz.arvadosapi.com</b>
 150   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
 151 MinRetryPeriod: <b>30s</b>
 152 </code></pre>
 153 </notextile>
 154
 155 h2. Restart the dispatcher
 156
 157 {% include 'notebox_begin' %}
 158
 159 The crunch-dispatch-slurm package includes configuration files for systemd.  If you're using a different init system, you'll need to configure a service to start and stop a @crunch-dispatch-slurm@ process as desired.  The process should run from a directory where the @crunch@ user has write permission on all compute nodes, such as its home directory or @/tmp@.  You do not need to specify any additional switches or environment variables.
 160
 161 {% include 'notebox_end' %}
 162
 163 Restart the dispatcher to run with your new configuration:
 164
 165 <notextile>
 166 <pre><code>~$ <span class="userinput">sudo systemctl restart crunch-dispatch-slurm</span>
 167 </code></pre>
 168 </notextile>