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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the LSF dispatcher
   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 {% include 'notebox_begin_warning' %}
  13 @arvados-dispatch-lsf@ is only relevant for on premises clusters that will spool jobs to LSF. Skip this section if you use Slurm or if you are installing a cloud cluster.
  14 {% include 'notebox_end' %}
  15
  16 h2(#overview). Overview
  17
  18 Containers can be dispatched to an LSF cluster.  The dispatcher sends work to the cluster using LSF's @bsub@ command, so it works in a variety of LSF configurations.
  19
  20 In order to run containers, you must choose a user that has permission to set up FUSE mounts and run Singularity/Docker containers on each compute node.  This install guide refers to this user as the @crunch@ user.  We recommend you create this user on each compute node with the same UID and GID, and add it to the @fuse@ and @docker@ system groups to grant it the necessary permissions.  However, you can run the dispatcher under any account with sufficient permissions across the cluster.
  21
  22 Set up all of your compute nodes with "Docker":../crunch2/install-compute-node-singularity.html or "Singularity":../crunch2/install-compute-node-docker.html.
  23
  24 *Current limitations*:
  25 * Arvados container priority is not propagated to LSF job priority. This can cause inefficient use of compute resources, and even deadlock if there are fewer compute nodes than concurrent Arvados workflows.
  26 * Combining LSF with docker may not work, depending on LSF configuration and user/group IDs (if LSF only sets up the configured user's primary group ID when executing the crunch-run process on a compute node, it may not have permission to connect to the docker daemon).
  27
  28 h2(#update-config). Update config.yml
  29
  30 Arvados-dispatch-lsf reads the common configuration file at @/etc/arvados/config.yml@.
  31
  32 Add a DispatchLSF entry to the Services section, using the hostname where @arvados-dispatch-lsf@ will run, and an available port:
  33
  34 <notextile>
  35 <pre>    Services:
  36       DispatchLSF:
  37         InternalURLs:
  38           "http://<code class="userinput">hostname.zzzzz.arvadosapi.com:9007</code>": {}</pre>
  39 </notextile>
  40
  41 Review the following configuration parameters and adjust as needed.
  42
  43 {% include 'hpc_max_gateway_tunnels' %}
  44
  45 h3(#BsubSudoUser). Containers.LSF.BsubSudoUser
  46
  47 arvados-dispatch-lsf uses @sudo@ to execute @bsub@, for example @sudo -E -u crunch bsub [...]@. This means the @crunch@ account must exist on the hosts where LSF jobs run ("execution hosts"), as well as on the host where you are installing the Arvados LSF dispatcher (the "submission host"). To use a user account other than @crunch@, configure @BsubSudoUser@:
  48
  49 <notextile>
  50 <pre>    Containers:
  51       LSF:
  52         <code class="userinput">BsubSudoUser: <b>lsfuser</b>
  53 </code></pre>
  54 </notextile>
  55
  56 Alternatively, you can arrange for the arvados-dispatch-lsf process to run as an unprivileged user that has a corresponding account on all compute nodes, and disable the use of @sudo@ by specifying an empty string:
  57
  58 <notextile>
  59 <pre>    Containers:
  60       LSF:
  61         # Don't use sudo
  62         <code class="userinput">BsubSudoUser: <b>""</b>
  63 </code></pre>
  64 </notextile>
  65
  66
  67 h3(#BsubArgumentsList). Containers.LSF.BsubArgumentsList
  68
  69 When arvados-dispatch-lsf invokes @bsub@, you can add arguments to the command by specifying @BsubArgumentsList@.  You can use this to send the jobs to specific cluster partitions or add resource requests.  Set @BsubArgumentsList@ to an array of strings.
  70
  71 Template variables starting with % will be substituted as follows:
  72
  73 %U uuid
  74 %C number of VCPUs
  75 %M memory in MB
  76 %T tmp in MB
  77 %G number of GPU devices (@runtime_constraints.cuda.device_count@)
  78 %W maximum job run time in minutes, suitable for use with @-W@ or @-We@ flags (see MaxRunTimeOverhead MaxRunTimeDefault below)
  79
  80 Use %% to express a literal %. The %%J in the default will be changed to %J, which is interpreted by @bsub@ itself.
  81
  82 For example:
  83
  84 <notextile>
  85 <pre>    Containers:
  86       LSF:
  87         <code class="userinput">BsubArgumentsList: <b>["-o", "/tmp/crunch-run.%%J.out", "-e", "/tmp/crunch-run.%%J.err", "-J", "%U", "-n", "%C", "-D", "%MMB", "-R", "rusage[mem=%MMB:tmp=%TMB] span[hosts=1]", "-R", "select[mem>=%MMB]", "-R", "select[tmp>=%TMB]", "-R", "select[ncpus>=%C]", "-We", "%W"]</b></code>
  88 </pre>
  89 </notextile>
  90
  91 Note that the default value for @BsubArgumentsList@ uses the @-o@ and @-e@ arguments to write stdout/stderr data to files in @/tmp@ on the compute nodes, which is helpful for troubleshooting installation/configuration problems. Ensure you have something in place to delete old files from @/tmp@, or adjust these arguments accordingly.
  92
  93 h3(#BsubCUDAArguments). Containers.LSF.BsubCUDAArguments
  94
  95 If the container requests access to GPUs (@runtime_constraints.cuda.device_count@ of the container request is greater than zero), the command line arguments in @BsubCUDAArguments@ will be added to the command line _after_ @BsubArgumentsList@.  This should consist of the additional @bsub@ flags your site requires to schedule the job on a node with GPU support.  Set @BsubCUDAArguments@ to an array of strings.  For example:
  96
  97 <notextile>
  98 <pre>    Containers:
  99       LSF:
 100         <code class="userinput">BsubCUDAArguments: <b>["-gpu", "num=%G"]</b></code>
 101 </pre>
 102 </notextile>
 103
 104 h3(#MaxRunTimeOverhead). Containers.LSF.MaxRunTimeOverhead
 105
 106 Extra time to add to each container's @scheduling_parameters.max_run_time@ value when substituting for @%W@ in @BsubArgumentsList@, to account for time spent setting up the container image, copying output files, etc.
 107
 108 h3(#MaxRunTimeDefault). Containers.LSF.MaxRunTimeDefault
 109
 110 Default @max_run_time@ value to use for containers that do not specify one in @scheduling_parameters.max_run_time@. If this is zero, and @BsubArgumentsList@ contains @"-W", "%W"@ or @"-We", "%W"@, those arguments will be dropped when submitting containers that do not specify @scheduling_parameters.max_run_time@.
 111
 112 h3(#PollInterval). Containers.PollInterval
 113
 114 arvados-dispatch-lsf 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 @s@, @m@, or @h@.  For example:
 115
 116 <notextile>
 117 <pre>    Containers:
 118       <code class="userinput">PollInterval: <b>10s</b>
 119 </code></pre>
 120 </notextile>
 121
 122
 123 h3(#ReserveExtraRAM). Containers.ReserveExtraRAM: Extra RAM for jobs
 124
 125 Extra RAM to reserve (in bytes) on each LSF 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.
 126
 127 Supports suffixes @KB@, @KiB@, @MB@, @MiB@, @GB@, @GiB@, @TB@, @TiB@, @PB@, @PiB@, @EB@, @EiB@ (where @KB@ is 10[^3^], @KiB@ is 2[^10^], @MB@ is 10[^6^], @MiB@ is 2[^20^] and so forth).
 128
 129 <notextile>
 130 <pre>    Containers:
 131       <code class="userinput">ReserveExtraRAM: <b>256MiB</b></code>
 132 </pre>
 133 </notextile>
 134
 135
 136 h3(#CrunchRunArgumentList). Containers.CrunchRunArgumentList: Using host networking for containers
 137
 138 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.
 139
 140 <notextile>
 141 <pre>    Containers:
 142       <code class="userinput">CrunchRunArgumentsList:
 143         - <b>"-container-enable-networking=always"</b>
 144         - <b>"-container-network-mode=host"</b></code>
 145 </pre>
 146 </notextile>
 147
 148
 149 h3(#InstanceTypes). InstanceTypes: Avoid submitting jobs with unsatisfiable resource constraints
 150
 151 LSF does not provide feedback when a submitted job's RAM, CPU, or disk space constraints cannot be satisfied by any node: the job will wait in the queue indefinitely with "pending" status, reported by Arvados as "queued".
 152
 153 As a workaround, you can configure @InstanceTypes@ with your LSF cluster's compute node sizes. Arvados will use these sizes to determine when a container is impossible to run, and cancel it instead of submitting an LSF job.
 154
 155 Apart from detecting non-runnable containers, the configured instance types will not have any effect on scheduling.
 156
 157 <notextile>
 158 <pre>    InstanceTypes:
 159       most-ram:
 160         VCPUs: 8
 161         RAM: 640GiB
 162         IncludedScratch: 640GB
 163       most-cpus:
 164         VCPUs: 32
 165         RAM: 256GiB
 166         IncludedScratch: 640GB
 167       gpu:
 168         VCPUs: 8
 169         RAM: 256GiB
 170         IncludedScratch: 640GB
 171         CUDA:
 172           DriverVersion: "11.4"
 173           HardwareCapability: "7.5"
 174           DeviceCount: 1
 175 </pre>
 176 </notextile>
 177
 178
 179 {% assign arvados_component = 'arvados-dispatch-lsf' %}
 180
 181 {% include 'install_packages' %}
 182
 183 {% include 'start_service' %}
 184
 185 {% include 'restart_api' %}
 186
 187 h2(#confirm-working). Confirm working installation
 188
 189 On the dispatch node, start monitoring the arvados-dispatch-lsf logs:
 190
 191 <notextile>
 192 <pre><code># <span class="userinput">journalctl -o cat -fu arvados-dispatch-lsf.service</span>
 193 </code></pre>
 194 </notextile>
 195
 196 In another terminal window, use the diagnostics tool to run a simple container.
 197
 198 <notextile>
 199 <pre><code># <span class="userinput">arvados-client sudo diagnostics</span>
 200 INFO       5: running health check (same as `arvados-server check`)
 201 INFO      10: getting discovery document from https://zzzzz.arvadosapi.com/discovery/v1/apis/arvados/v1/rest
 202 ...
 203 INFO     160: running a container
 204 INFO      ... container request submitted, waiting up to 10m for container to run
 205 </code></pre>
 206 </notextile>
 207
 208 After performing a number of other quick tests, this will submit a new container request and wait for it to finish.
 209
 210 While the diagnostics tool is waiting, the @arvados-dispatch-lsf@ logs will show details about submitting an LSF job to run the container.