X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/84bd6883a5bab065c88d4ed495b8c03ab7ba5f97..e3566cdd48dd5c67ef9d0b1a45321f773b44b2a6:/doc/install/install-keep-balance.html.textile.liquid
diff --git a/doc/install/install-keep-balance.html.textile.liquid b/doc/install/install-keep-balance.html.textile.liquid
index 85fe300305..4a35f448e2 100644
--- a/doc/install/install-keep-balance.html.textile.liquid
+++ b/doc/install/install-keep-balance.html.textile.liquid
@@ -3,13 +3,25 @@ layout: default
navsection: installguide
title: Install Keep-balance
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+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).
+{% 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, edit your keep-balance startup script to use the flags @-commit-pulls=false -commit-trash=false@.
+
+{% include 'notebox_end' %}
h2. Install keep-balance
-Keep-balance can be installed anywhere with access to Keep services. Typically it runs on the same host as keepproxy.
+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:
@@ -43,28 +55,37 @@ Options:
h3. Create a keep-balance token
-Create a privileged Arvados API token for use by keep-balance. *On the API server*, run:
+Create an Arvados superuser token for use by keep-balance.
+
+{% include 'create_superuser_token' %}
+
+h3. Update keepstore configuration files
+
+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:
-apiserver:~$ cd /var/www/arvados-api/current
-apiserver:/var/www/arvados-api/current$ sudo -u webserver-user RAILS_ENV=production bundle exec script/create_superuser_token.rb
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+SystemAuthTokenFile: /etc/arvados/keepstore/system-auth-token.txt
-h3. Create a configuration file
+Restart all keepstore services to apply the updated configuration.
+
+h3. Create a keep-balance configuration file
-Create @/etc/arvados/keep-balance/keep-balance.yml@ using the token you generated in the previous step. Follow this YAML format:
+On the host running keep-balance, create @/etc/arvados/keep-balance/keep-balance.yml@ using the token you generated above. Follow this YAML format:
-Client:
+Listen: :9005
+Client:
APIHost: uuid_prefix.your.domain:443
AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
KeepServiceTypes:
- disk
+ManagementToken: xyzzy
RunPeriod: 10m
CollectionBatchSize: 100000
CollectionBuffers: 1000
+LostBlocksFile: /tmp/keep-balance-lost-blocks.txt # If given, this file will be updated atomically during each successful run.
@@ -134,22 +155,26 @@ run: /etc/service/keep-balance: (pid 12520) 2s; run: log: (pid 12519) 2s
h2. Enable delete operations on keepstore volumes
-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.
+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.
-Either use the @EnableDelete@ flag in your YAML configuration file @/etc/arvados/keepstore/keepstore.yml@:
+Add the @-never-delete=false@ command line flag to your keepstore run script:
-...
-BlobSigningKeyFile: /etc/keepstore/blob-signing.key
-EnableDelete: true
-Listen: :25107
-...
+keepstore -never-delete=false -volume=...
-Or use the @-never-delete=false@ command line flag in your run script:
+{% comment %}
+// To replace the above section when the keepstore page recommends YAML...
+
+Use the @EnableDelete@ flag in your YAML configuration file @/etc/arvados/keepstore/keepstore.yml@:
-keepstore -never-delete=false -volume=...
+...
+BlobSigningKeyFile: /etc/keepstore/blob-signing.key
+EnableDelete: true
+Listen: :25107
+...
+{% endcomment %}