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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install Keep-balance
   5 ...
   6
   7 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).
   8
   9 {% include 'notebox_begin' %}
  10
  11 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, use the @keepstore -never-delete=true@ flag or remove the @-commit-trash@ flag from your keep-balance startup script.
  12
  13 {% include 'notebox_end' %}
  14
  15 h2. Install keep-balance
  16
  17 Keep-balance can be installed anywhere with access to Keep services. Typically it runs on the same host as keepproxy.
  18
  19 On Debian-based systems:
  20
  21 <notextile>
  22 <pre><code>~$ <span class="userinput">sudo apt-get install keep-balance</span>
  23 </code></pre>
  24 </notextile>
  25
  26 On Red Hat-based systems:
  27
  28 <notextile>
  29 <pre><code>~$ <span class="userinput">sudo yum install keep-balance</span>
  30 </code></pre>
  31 </notextile>
  32
  33 Verify that @keep-balance@ is functional:
  34
  35 <notextile>
  36 <pre><code>~$ <span class="userinput">keep-balance -h</span>
  37 ...
  38 Usage: keep-balance [options]
  39
  40 Options:
  41   -commit-pulls
  42         send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
  43   -commit-trash
  44         send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
  45 ...
  46 </code></pre>
  47 </notextile>
  48
  49 h3. Create a keep-balance token
  50
  51 Create a privileged Arvados API token for use by keep-balance. *On the API server*, run:
  52
  53 <notextile>
  54 <pre><code>apiserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
  55 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>
  56 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  57 </code></pre>
  58 </notextile>
  59
  60 h3. Create a configuration file
  61
  62 Create @/etc/arvados/keep-balance/keep-balance.yml@ using the token you generated in the previous step.  Follow this YAML format:
  63
  64 <notextile>
  65 <pre><code>Client:
  66   APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
  67   AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  68 KeepServiceTypes:
  69   - disk
  70 RunPeriod: 10m
  71 CollectionBatchSize: 100000
  72 CollectionBuffers: 1000
  73 </code></pre>
  74 </notextile>
  75
  76 If your API server's SSL certificate is not signed by a recognized CA, add the @Insecure@ option to the @Client@ section:
  77
  78 <notextile>
  79 <pre><code>Client:
  80   <span class="userinput">Insecure: true</span>
  81   APIHost: ...
  82 </code></pre>
  83 </notextile>
  84
  85 h3. Start the service (option 1: systemd)
  86
  87 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
  88
  89 If your system uses systemd, the keep-balance service should already be set up. Start it and check its status:
  90
  91 <notextile>
  92 <pre><code>~$ <span class="userinput">sudo systemctl restart keep-balance</span>
  93 ~$ <span class="userinput">sudo systemctl status keep-balance</span>
  94 &#x25cf; keep-balance.service - Arvados Keep Balance
  95    Loaded: loaded (/lib/systemd/system/keep-balance.service; enabled)
  96    Active: active (running) since Sat 2017-02-14 18:46:01 UTC; 3 days ago
  97      Docs: https://doc.arvados.org/
  98  Main PID: 541 (keep-balance)
  99    CGroup: /system.slice/keep-balance.service
 100            └─541 /usr/bin/keep-balance -commit-pulls -commit-trash
 101
 102 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
 103 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 Run: start
 104 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"
 105 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
 106 </code></pre>
 107 </notextile>
 108
 109 h3(#runit). Start the service (option 2: runit)
 110
 111 Install runit to supervise the keep-balance daemon.  {% include 'install_runit' %}
 112
 113 Create a supervised service.
 114
 115 <notextile>
 116 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/keep-balance</span>
 117 ~$ <span class="userinput">cd /etc/service/keep-balance</span>
 118 ~$ <span class="userinput">sudo mkdir log log/main</span>
 119 ~$ <span class="userinput">printf '#!/bin/sh\nexec keep-balance -commit-pulls -commit-trash 2>&1\n' | sudo tee run</span>
 120 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 121 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 122 ~$ <span class="userinput">sudo sv exit .</span>
 123 ~$ <span class="userinput">cd -</span>
 124 </code></pre>
 125 </notextile>
 126
 127 Use @sv stat@ and check the log file to verify the service is running.
 128
 129 <notextile>
 130 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/keep-balance</span>
 131 run: /etc/service/keep-balance: (pid 12520) 2s; run: log: (pid 12519) 2s
 132 ~$ <span class="userinput">tail /etc/service/keep-balance/log/main/current</span>
 133 2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
 134 2017/02/14 18:56:01 Run: start
 135 2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
 136 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
 137 </code></pre>
 138 </notextile>
 139
 140 h2. Enable delete operations on keepstore volumes
 141
 142 Ensure your keepstore services have the "delete" operation enabled. Otherwise, even when unneeded data is identified by keep-balance, it will never be deleted from the underlying storage devices.
 143
 144 Either use the @EnableDelete@ flag in your YAML configuration file @/etc/arvados/keepstore/keepstore.yml@:
 145
 146 <notextile>
 147 <pre><code>...
 148 BlobSigningKeyFile: /etc/keepstore/blob-signing.key
 149 <span class="userinput">EnableDelete: true</span>
 150 Listen: :25107
 151 ...
 152 </code></pre>
 153 </notextile>
 154
 155 Or use the @-never-delete=false@ command line flag in your run script:
 156
 157 <notextile>
 158 <pre><code>keepstore <span class="userinput">-never-delete=false</span> -volume=...
 159 </code></pre>
 160 </notextile>