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 token
  57
  58 Create an Arvados superuser token for use by keep-balance. *On the API server*, run:
  59
  60 <notextile>
  61 <pre><code>apiserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
  62 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>
  63 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  64 </code></pre>
  65 </notextile>
  66
  67 h3. Update keepstore configuration files
  68
  69 On each node that runs keepstore, save the token you generated in the previous step in a text file like @/etc/arvados/keepstore/system-auth-token.txt@ and then create or update @/etc/arvados/keepstore/keepstore.yml@ with the following key:
  70
  71 <notextile>
  72 <pre><code>SystemAuthTokenFile: /etc/arvados/keepstore/system-auth-token.txt
  73 </code></pre>
  74 </notextile>
  75
  76 Restart all keepstore services to apply the updated configuration.
  77
  78 h3. Create a keep-balance configuration file
  79
  80 On the host running keep-balance, create @/etc/arvados/keep-balance/keep-balance.yml@ using the token you generated above.  Follow this YAML format:
  81
  82 <notextile>
  83 <pre><code>Client:
  84   APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
  85   AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  86 KeepServiceTypes:
  87   - disk
  88 RunPeriod: 10m
  89 CollectionBatchSize: 100000
  90 CollectionBuffers: 1000
  91 </code></pre>
  92 </notextile>
  93
  94 If your API server's SSL certificate is not signed by a recognized CA, add the @Insecure@ option to the @Client@ section:
  95
  96 <notextile>
  97 <pre><code>Client:
  98   <span class="userinput">Insecure: true</span>
  99   APIHost: ...
 100 </code></pre>
 101 </notextile>
 102
 103 h3. Start the service (option 1: systemd)
 104
 105 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
 106
 107 If your system uses systemd, the keep-balance service should already be set up. Start it and check its status:
 108
 109 <notextile>
 110 <pre><code>~$ <span class="userinput">sudo systemctl restart keep-balance</span>
 111 ~$ <span class="userinput">sudo systemctl status keep-balance</span>
 112 &#x25cf; keep-balance.service - Arvados Keep Balance
 113    Loaded: loaded (/lib/systemd/system/keep-balance.service; enabled)
 114    Active: active (running) since Sat 2017-02-14 18:46:01 UTC; 3 days ago
 115      Docs: https://doc.arvados.org/
 116  Main PID: 541 (keep-balance)
 117    CGroup: /system.slice/keep-balance.service
 118            └─541 /usr/bin/keep-balance -commit-pulls -commit-trash
 119
 120 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
 121 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 Run: start
 122 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"
 123 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
 124 </code></pre>
 125 </notextile>
 126
 127 h3(#runit). Start the service (option 2: runit)
 128
 129 Install runit to supervise the keep-balance daemon.  {% include 'install_runit' %}
 130
 131 Create a supervised service.
 132
 133 <notextile>
 134 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/keep-balance</span>
 135 ~$ <span class="userinput">cd /etc/service/keep-balance</span>
 136 ~$ <span class="userinput">sudo mkdir log log/main</span>
 137 ~$ <span class="userinput">printf '#!/bin/sh\nexec keep-balance -commit-pulls -commit-trash 2>&1\n' | sudo tee run</span>
 138 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 139 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 140 ~$ <span class="userinput">sudo sv exit .</span>
 141 ~$ <span class="userinput">cd -</span>
 142 </code></pre>
 143 </notextile>
 144
 145 Use @sv stat@ and check the log file to verify the service is running.
 146
 147 <notextile>
 148 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/keep-balance</span>
 149 run: /etc/service/keep-balance: (pid 12520) 2s; run: log: (pid 12519) 2s
 150 ~$ <span class="userinput">tail /etc/service/keep-balance/log/main/current</span>
 151 2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
 152 2017/02/14 18:56:01 Run: start
 153 2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
 154 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
 155 </code></pre>
 156 </notextile>
 157
 158 h2. Enable delete operations on keepstore volumes
 159
 160 Ensure your keepstore services have the "delete" operation enabled. If it is disabled (which is the default), unneeded blocks will be identified by keep-balance, but will never be deleted from the underlying storage devices.
 161
 162 Add the @-never-delete=false@ command line flag to your keepstore run script:
 163
 164 <notextile>
 165 <pre><code>keepstore <span class="userinput">-never-delete=false</span> -volume=...
 166 </code></pre>
 167 </notextile>
 168
 169 {% comment %}
 170 // To replace the above section when the keepstore page recommends YAML...
 171
 172 Use the @EnableDelete@ flag in your YAML configuration file @/etc/arvados/keepstore/keepstore.yml@:
 173
 174 <notextile>
 175 <pre><code>...
 176 BlobSigningKeyFile: /etc/keepstore/blob-signing.key
 177 <span class="userinput">EnableDelete: true</span>
 178 Listen: :25107
 179 ...
 180 </code></pre>
 181 </notextile>
 182 {% endcomment %}