doc/install/install-keep-balance.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install Keep-balance
   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 Keep-balance deletes unreferenced and overreplicated blocks from Keep servers, makes additional copies of underreplicated blocks, and moves blocks into optimal locations as needed (e.g., after adding new servers).
  13
  14 {% include 'notebox_begin' %}
  15
  16 If you are installing keep-balance on an existing system with valuable data, you can run keep-balance in "dry run" mode first and review its logs as a precaution. To do this, edit your keep-balance startup script to use the flags @-commit-pulls=false -commit-trash=false@.
  17
  18 {% include 'notebox_end' %}
  19
  20 h2. Install keep-balance
  21
  22 Keep-balance can be installed anywhere with network access to Keep services. Typically it runs on the same host as keepproxy.
  23
  24 *A cluster should have only one keep-balance process running at a time.*
  25
  26 On Debian-based systems:
  27
  28 <notextile>
  29 <pre><code>~$ <span class="userinput">sudo apt-get install keep-balance</span>
  30 </code></pre>
  31 </notextile>
  32
  33 On Red Hat-based systems:
  34
  35 <notextile>
  36 <pre><code>~$ <span class="userinput">sudo yum install keep-balance</span>
  37 </code></pre>
  38 </notextile>
  39
  40 Verify that @keep-balance@ is functional:
  41
  42 <notextile>
  43 <pre><code>~$ <span class="userinput">keep-balance -h</span>
  44 ...
  45 Usage: keep-balance [options]
  46
  47 Options:
  48   -commit-pulls
  49         send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
  50   -commit-trash
  51         send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
  52 ...
  53 </code></pre>
  54 </notextile>
  55
  56 h3. Create a keep-balance configuration file
  57
  58 On the host running keep-balance, create @/etc/arvados/keep-balance/keep-balance.yml@ using the SystemRootToken from your cluster configuration file.  Follow this YAML format:
  59
  60 <notextile>
  61 <pre><code>Listen: :9005
  62 Client:
  63   APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
  64   AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  65 KeepServiceTypes:
  66   - disk
  67 ManagementToken: <span class="userinput">xyzzy</span>
  68 RunPeriod: 10m
  69 CollectionBatchSize: 100000
  70 CollectionBuffers: 1000
  71 LostBlocksFile: /tmp/keep-balance-lost-blocks.txt    # If given, this file will be updated atomically during each successful run.
  72 </code></pre>
  73 </notextile>
  74
  75 If your API server's SSL certificate is not signed by a recognized CA, add the @Insecure@ option to the @Client@ section:
  76
  77 <notextile>
  78 <pre><code>Client:
  79   <span class="userinput">Insecure: true</span>
  80   APIHost: ...
  81 </code></pre>
  82 </notextile>
  83
  84 h3. Start the service (option 1: systemd)
  85
  86 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
  87
  88 If your system uses systemd, the keep-balance service should already be set up. Start it and check its status:
  89
  90 <notextile>
  91 <pre><code>~$ <span class="userinput">sudo systemctl restart keep-balance</span>
  92 ~$ <span class="userinput">sudo systemctl status keep-balance</span>
  93 &#x25cf; keep-balance.service - Arvados Keep Balance
  94    Loaded: loaded (/lib/systemd/system/keep-balance.service; enabled)
  95    Active: active (running) since Sat 2017-02-14 18:46:01 UTC; 3 days ago
  96      Docs: https://doc.arvados.org/
  97  Main PID: 541 (keep-balance)
  98    CGroup: /system.slice/keep-balance.service
  99            └─541 /usr/bin/keep-balance -commit-pulls -commit-trash
 100
 101 Feb 14 18:46:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
 102 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 Run: start
 103 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
 104 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
 105 </code></pre>
 106 </notextile>
 107
 108 h3(#runit). Start the service (option 2: runit)
 109
 110 Install runit to supervise the keep-balance daemon.  {% include 'install_runit' %}
 111
 112 Create a supervised service.
 113
 114 <notextile>
 115 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/keep-balance</span>
 116 ~$ <span class="userinput">cd /etc/service/keep-balance</span>
 117 ~$ <span class="userinput">sudo mkdir log log/main</span>
 118 ~$ <span class="userinput">printf '#!/bin/sh\nexec keep-balance -commit-pulls -commit-trash 2>&1\n' | sudo tee run</span>
 119 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 120 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 121 ~$ <span class="userinput">sudo sv exit .</span>
 122 ~$ <span class="userinput">cd -</span>
 123 </code></pre>
 124 </notextile>
 125
 126 Use @sv stat@ and check the log file to verify the service is running.
 127
 128 <notextile>
 129 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/keep-balance</span>
 130 run: /etc/service/keep-balance: (pid 12520) 2s; run: log: (pid 12519) 2s
 131 ~$ <span class="userinput">tail /etc/service/keep-balance/log/main/current</span>
 132 2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
 133 2017/02/14 18:56:01 Run: start
 134 2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
 135 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
 136 </code></pre>
 137 </notextile>
 138
 139 h2. Enable garbage collection
 140
 141 Ensure your cluster configuration has @Collections.BlobTrash: true@ (this is the default).
 142
 143 <notextile>
 144 <pre><code>~$ arvados-server config-dump | grep BlobTrash:
 145       BlobTrash: true
 146 </code></pre>
 147 </notextile>
 148
 149 If BlobTrash is false, unneeded blocks will be counted and logged by keep-balance, but they will not be deleted.