navsection: installguide
title: Install Keep-balance
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
-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).
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+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). See "Balancing Keep servers":{{site.baseurl}}/admin/keep-balance.html for usage details.
{% include 'notebox_begin' %}
-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.
+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@.
{% include 'notebox_end' %}
Keep-balance can be installed anywhere with network access to Keep services. Typically it runs on the same host as keepproxy.
+*A cluster should have only one keep-balance process running at a time.*
+
On Debian-based systems:
<notextile>
<notextile>
<pre><code>~$ <span class="userinput">keep-balance -h</span>
...
-Usage: keep-balance [options]
-
-Options:
+Usage of ./keep-balance:
-commit-pulls
- send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
+ send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
-commit-trash
- send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
+ send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
...
</code></pre>
</notextile>
-h3. Create a keep-balance token
-
-Create a privileged Arvados API token for use by keep-balance. *On the API server*, run:
-
-<notextile>
-<pre><code>apiserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
-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>
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-</code></pre>
-</notextile>
-
-h3. Create a configuration file
+h3. Update the cluster config
-On the host running keep-balance, create @/etc/arvados/keep-balance/keep-balance.yml@ using the token you generated in the previous step. Follow this YAML format:
+Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Keepbalance.InternalURLs@. Replace @uuid_prefix@ with your cluster id.
<notextile>
-<pre><code>Client:
- APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
- AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-KeepServiceTypes:
- - disk
-RunPeriod: 10m
-CollectionBatchSize: 100000
-CollectionBuffers: 1000
+<pre><code>Clusters:
+ <span class="userinput">uuid_prefix</span>:
+ Services:
+ Keepbalance:
+ InternalURLs:
+ "http://localhost:9005/": {}
+ TLS:
+ Insecure: false
</code></pre>
</notextile>
-If your API server's SSL certificate is not signed by a recognized CA, add the @Insecure@ option to the @Client@ section:
-
-<notextile>
-<pre><code>Client:
- <span class="userinput">Insecure: true</span>
- APIHost: ...
-</code></pre>
-</notextile>
+Set @TLS.Insecure: true@ if your API server’s TLS certificate is not signed by a recognized CA.
h3. Start the service (option 1: systemd)
</code></pre>
</notextile>
-h2. Enable delete operations on keepstore volumes
+h2. Enable garbage collection
-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.
-
-Either use the @EnableDelete@ flag in your YAML configuration file @/etc/arvados/keepstore/keepstore.yml@:
+Ensure your cluster configuration has @Collections.BlobTrash: true@ (this is the default).
<notextile>
-<pre><code>...
-BlobSigningKeyFile: /etc/keepstore/blob-signing.key
-<span class="userinput">EnableDelete: true</span>
-Listen: :25107
-...
+<pre><code>~$ arvados-server config-dump | grep BlobTrash:
+ BlobTrash: true
</code></pre>
</notextile>
-Or use the @-never-delete=false@ command line flag in your run script:
-
-<notextile>
-<pre><code>keepstore <span class="userinput">-never-delete=false</span> -volume=...
-</code></pre>
-</notextile>
+If BlobTrash is false, unneeded blocks will be counted and logged by keep-balance, but they will not be deleted.
projects / arvados.git / blobdiff