3 navsection: installguide
4 title: Install Keep-balance
7 Copyright (C) The Arvados Authors. All rights reserved.
9 SPDX-License-Identifier: CC-BY-SA-3.0
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).
14 {% include 'notebox_begin' %}
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@.
18 {% include 'notebox_end' %}
20 h2. Install keep-balance
22 Keep-balance can be installed anywhere with network access to Keep services. Typically it runs on the same host as keepproxy.
24 *A cluster should have only one keep-balance process running at a time.*
26 On Debian-based systems:
29 <pre><code>~$ <span class="userinput">sudo apt-get install keep-balance</span>
33 On Red Hat-based systems:
36 <pre><code>~$ <span class="userinput">sudo yum install keep-balance</span>
40 Verify that @keep-balance@ is functional:
43 <pre><code>~$ <span class="userinput">keep-balance -h</span>
45 Usage: keep-balance [options]
49 send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
51 send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
56 h3. Create a keep-balance configuration file
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:
61 <pre><code>Listen: :9005
63 APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
64 AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
67 ManagementToken: <span class="userinput">xyzzy</span>
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.
75 If your API server's SSL certificate is not signed by a recognized CA, add the @Insecure@ option to the @Client@ section:
79 <span class="userinput">Insecure: true</span>
84 h3. Start the service (option 1: systemd)
86 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
88 If your system uses systemd, the keep-balance service should already be set up. Start it and check its status:
91 <pre><code>~$ <span class="userinput">sudo systemctl restart keep-balance</span>
92 ~$ <span class="userinput">sudo systemctl status keep-balance</span>
93 ● 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
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
108 h3(#runit). Start the service (option 2: runit)
110 Install runit to supervise the keep-balance daemon. {% include 'install_runit' %}
112 Create a supervised service.
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>
126 Use @sv stat@ and check the log file to verify the service is running.
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
139 h2. Enable garbage collection
141 Ensure your cluster configuration has @Collections.BlobTrash: true@ (this is the default).
144 <pre><code>~$ arvados-server config-dump | grep BlobTrash:
149 If BlobTrash is false, unneeded blocks will be counted and logged by keep-balance, but they will not be deleted.