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
  35 h2. Configure the dispatcher
  36
  37 Edit @/etc/arvados/config.yml@.
  38
  39 <notextile>
  40 <pre><code class="userinput">Client:
  41   APIHost: <b>zzzzz.arvadosapi.com</b>
  42   AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
  43 </code></pre>
  44 </notextile>
  45
  46 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.
  47
  48 h3(#KeepServiceURIs). Containers.SLURM.KeepServices
  49
  50 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:
  51
  52 <notextile>
  53 <pre>
  54 Clusters:
  55   zzzzz:
  56     Containers:
  57       SLURM:
  58         <span class="userinput">KeepServices:
  59           00000-bi6l4-000000000000000:
  60             InternalURLs:
  61               "http://127.0.0.1:25107": {}</span>
  62 </code></pre>
  63 </notextile>
  64
  65 h3(#PollPeriod). Containers.PollInterval
  66
  67 crunch-dispatch-slurm polls the API server periodically for new containers to run.  The @PollInterval@ 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:
  68
  69 <notextile>
  70 <pre>
  71 Clusters:
  72   zzzzz:
  73     Containers:
  74       <code class="userinput">PollInterval: <b>3m30s</b>
  75 </code></pre>
  76 </notextile>
  77
  78 h3(#PrioritySpread). Containers.SLURM.PrioritySpread
  79
  80 crunch-dispatch-slurm adjusts the "nice" values of its SLURM jobs to ensure containers are prioritized correctly relative to one another. This option tunes the adjustment mechanism.
  81 * If non-Arvados jobs run on your SLURM cluster, and your Arvados containers are waiting too long in the SLURM queue because their "nice" values are too high for them to compete with other SLURM jobs, you should use a smaller PrioritySpread value.
  82 * If you have an older SLURM system that limits nice values to 10000, a smaller @PrioritySpread@ can help avoid reaching that limit.
  83 * In other cases, a larger value is beneficial because it reduces the total number of adjustments made by executing @scontrol@.
  84
  85 The smallest usable value is @1@. The default value of @10@ is used if this option is zero or negative. Example:
  86
  87 <notextile>
  88 <pre>
  89 Clusters:
  90   zzzzz:
  91     Containers:
  92       SLURM:
  93         <code class="userinput">PrioritySpread: <b>1000</b></code></pre>
  94 </notextile>
  95
  96 h3(#SbatchArguments). Containers.SLURM.SbatchArgumentsList
  97
  98 When crunch-dispatch-slurm invokes @sbatch@, you can add arguments 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:
  99
 100 <notextile>
 101 <pre>
 102 Clusters:
 103   zzzzz:
 104     Containers:
 105       SLURM:
 106         <code class="userinput">SbatchArgumentsList:
 107           - <b>"--partition=PartitionName"</b></code>
 108 </pre>
 109 </notextile>
 110
 111 Note: If an argument is supplied multiple times, @slurm@ uses the value of the last occurrence of the argument on the command line.  Arguments specified through Arvados are added after the arguments listed in SbatchArguments.  This means, for example, an Arvados container with that specifies @partitions@ in @scheduling_parameter@ will override an occurrence of @--partition@ in SbatchArguments.  As a result, for container parameters that can be specified through Arvados, SbatchArguments can be used to specify defaults but not enforce specific policy.
 112
 113 h3(#CrunchRunCommand-cgroups). Containers.CrunchRunArgumentList: Dispatch to SLURM cgroups
 114
 115 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:
 116
 117 <notextile>
 118 <pre>
 119 Clusters:
 120   zzzzz:
 121     Containers:
 122       <code class="userinput">CrunchRunArgumentsList:
 123         - <b>"-cgroup-parent-subsystem=memory"</b></code>
 124 </pre>
 125 </notextile>
 126
 127 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.  When doing this, you should also set "ReserveExtraRAM":#ReserveExtraRAM .
 128
 129 {% include 'notebox_begin' %}
 130
 131 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.
 132
 133 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@.
 134
 135 {% include 'notebox_end' %}
 136
 137 h3(#CrunchRunCommand-network). Containers.CrunchRunArgumentList: Using host networking for containers
 138
 139 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.
 140
 141 <notextile>
 142 <pre>
 143 Clusters:
 144   zzzzz:
 145     Containers:
 146       <code class="userinput">CrunchRunArgumentsList:
 147         - <b>"-container-enable-networking=always"</b>
 148         - <b>"-container-network-mode=host"</b></code>
 149 </pre>
 150 </notextile>
 151
 152 h3(#MinRetryPeriod). Containers.MinRetryPeriod: Rate-limit repeated attempts to start containers
 153
 154 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.
 155
 156 <notextile>
 157 <pre>
 158 Clusters:
 159   zzzzz:
 160     Containers:
 161       <code class="userinput">MinRetryPeriod: <b>30s</b></code>
 162 </pre>
 163 </notextile>
 164
 165 h3(#ReserveExtraRAM). Containers.ReserveExtraRAM: Extra RAM for jobs
 166
 167 Extra RAM to reserve (in bytes) on each SLURM job submitted by Arvados, which is added to the amount specified in the container's @runtime_constraints@.  If not provided, the default value is zero.  Helpful when using @-cgroup-parent-subsystem@, where @crunch-run@ and @arv-mount@ share the control group memory limit with the user process.  In this situation, at least 256MiB is recommended to accomodate each container's @crunch-run@ and @arv-mount@ processes.
 168
 169 <notextile>
 170 <pre>
 171 Clusters:
 172   zzzzz:
 173     Containers:
 174       <code class="userinput">ReserveExtraRAM: <b>256MiB</b></code>
 175 </pre>
 176 </notextile>
 177
 178 h2. Restart the dispatcher
 179
 180 {% include 'notebox_begin' %}
 181
 182 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.
 183
 184 {% include 'notebox_end' %}
 185
 186 Restart the dispatcher to run with your new configuration:
 187
 188 <notextile>
 189 <pre><code>~$ <span class="userinput">sudo systemctl restart crunch-dispatch-slurm</span>
 190 </code></pre>
 191 </notextile>