doc/install/install-keepstore.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install Keepstore servers
   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 Keepstore provides access to underlying storage for reading and writing content-addressed blocks, with enforcement of Arvados permissions.  Keepstore supports a variety of cloud object storage and POSIX filesystems for its backing store.
  13
  14 We recommend installing at least two Keepstore servers. By convention, we use the following hostname pattern:
  15
  16 <div class="offset1">
  17 table(table table-bordered table-condensed).
  18 |_Hostname_|
  19 |keep0.@uuid_prefix@.your.domain|
  20 |keep1.@uuid_prefix@.your.domain|
  21 </div>
  22
  23 Keepstore servers should not be directly accessible from the Internet (they are accessed via "keepproxy":install-keepproxy.html), so the hostnames only need to resolve on the private network.
  24
  25 h2. Install Keepstore
  26
  27 On Debian-based systems:
  28
  29 <notextile>
  30 <pre><code>~$ <span class="userinput">sudo apt-get install keepstore</span>
  31 </code></pre>
  32 </notextile>
  33
  34 On Red Hat-based systems:
  35
  36 <notextile>
  37 <pre><code>~$ <span class="userinput">sudo yum install keepstore</span>
  38 </code></pre>
  39 </notextile>
  40
  41 Verify that Keepstore is functional:
  42
  43 <notextile>
  44 <pre><code>~$ <span class="userinput">keepstore --version</span>
  45 </code></pre>
  46 </notextile>
  47
  48 h3. Create config file
  49
  50 By default, keepstore will look for its configuration file at @/etc/arvados/keepstore/keepstore.yml@
  51
  52 You can override the configuration file location using the @-config@ command line option to keepstore.
  53
  54 The following is a sample configuration file:
  55
  56 <pre>
  57 # Duration for which new permission signatures (returned in PUT
  58 # responses) will be valid.  This should be equal to the API
  59 # server's blob_signature_ttl configuration entry.
  60 BlobSignatureTTL: 336h0m0s
  61
  62 # Local file containing the secret blob signing key (used to generate
  63 # and verify blob signatures).  The contents of the key file must be
  64 # identical to the API server's blob_signing_key configuration entry.
  65 BlobSigningKeyFile: ""
  66
  67 # Print extra debug logging
  68 Debug: false
  69
  70 # Maximum number of concurrent block deletion operations (per
  71 # volume) when emptying trash. Default is 1.
  72 EmptyTrashWorkers: 1
  73
  74 # Enable trash and delete features. If false, trash lists will be
  75 # accepted but blocks will not be trashed or deleted.
  76 # Keepstore does not delete data on its own.  The keep-balance
  77 # service determines which blocks are candidates for deletion
  78 # and instructs the keepstore to move those blocks to the trash.
  79 EnableDelete: true
  80
  81 # Local port to listen on. Can be 'address:port' or ':port', where
  82 # 'address' is a host IP address or name and 'port' is a port number
  83 # or name.
  84 Listen: :25107
  85
  86 # Format of request/response and error logs: "json" or "text".
  87 LogFormat: json
  88
  89 # The secret key that must be provided by monitoring services
  90 # wishing to access the health check endpoint (/_health).
  91 ManagementToken: ""
  92
  93 # Maximum RAM to use for data buffers, given in multiples of block
  94 # size (64 MiB). When this limit is reached, HTTP requests requiring
  95 # buffers (like GET and PUT) will wait for buffer space to be
  96 # released.
  97 #
  98 # It should be set such that MaxBuffers * 64MiB + 10% fits
  99 # comfortably in memory. On a host dedicated to running keepstore,
 100 # divide total memory by 88MiB to suggest a suitable value. For example,
 101 # if grep MemTotal /proc/meminfo reports MemTotal: 7125440 kB,
 102 # compute 7125440 / (88 * 1024)=79 and configure MaxBuffers: 79
 103 MaxBuffers: 128
 104
 105 # Maximum concurrent requests. When this limit is reached, new
 106 # requests will receive 503 responses. Note: this limit does not
 107 # include idle connections from clients using HTTP keepalive, so it
 108 # does not strictly limit the number of concurrent connections. If
 109 # omitted or zero, the default is 2 * MaxBuffers.
 110 MaxRequests: 0
 111
 112 # Path to write PID file during startup. This file is kept open and
 113 # locked with LOCK_EX until keepstore exits, so "fuser -k pidfile" is
 114 # one way to shut down. Exit immediately if there is an error
 115 # opening, locking, or writing the PID file.
 116 PIDFile: ""
 117
 118 # Maximum number of concurrent pull operations. Default is 1, i.e.,
 119 # pull lists are processed serially.  A pull operation copies a block
 120 # from another keepstore server.
 121 PullWorkers: 1
 122
 123 # Honor read requests only if a valid signature is provided.  This
 124 # should be true, except for development use and when migrating from
 125 # a very old version.
 126 RequireSignatures: true
 127
 128 # Local file containing the Arvados API token used by keep-balance
 129 # or data manager.  Delete, trash, and index requests are honored
 130 # only for this token.
 131 SystemAuthTokenFile: ""
 132
 133 # Path to server certificate file in X509 format. Enables TLS mode.
 134 #
 135 # Example: /var/lib/acme/live/keep0.example.com/fullchain
 136 TLSCertificateFile: ""
 137
 138 # Path to server key file in X509 format. Enables TLS mode.
 139 #
 140 # The key pair is read from disk during startup, and whenever SIGHUP
 141 # is received.
 142 #
 143 # Example: /var/lib/acme/live/keep0.example.com/privkey
 144 TLSKeyFile: ""
 145
 146 # How often to check for (and delete) trashed blocks whose
 147 # TrashLifetime has expired.
 148 TrashCheckInterval: 24h0m0s
 149
 150 # Time duration after a block is trashed during which it can be
 151 # recovered using an /untrash request.
 152 TrashLifetime: 336h0m0s
 153
 154 # Maximum number of concurrent trash operations (moving a block to the
 155 # trash, or permanently deleting it) . Default is 1, i.e., trash lists
 156 # are processed serially.  If individual trash operations have high
 157 # latency (eg some cloud platforms) you should increase this.
 158 TrashWorkers: 1
 159 </pre>
 160
 161 h3. Notes on storage management
 162
 163 On its own, a keepstore server never deletes data.  The "keep-balance":install-keep-balance.html service determines which blocks are candidates for deletion and instructs the keepstore to move those blocks to the trash.
 164
 165 When a block is newly written, it is protected from deletion for the duration in @BlobSignatureTTL@.  During this time, it cannot be trashed.
 166
 167 If keep-balance instructs keepstore to trash a block which is older than @BlobSignatureTTL@, and @EnableDelete@ is true, the block will be moved to "trash".  A block which is in the trash is no longer accessible by read requests, but has not yet been permanently deleted.  Blocks which are in the trash may be recovered using the "untrash" API endpoint.  Blocks are permanently deleted after they have been in the trash for the duration in @TrashLifetime@.
 168
 169 Keep-balance is also responsible for balancing the distribution of blocks across keepstore servers by asking servers to pull blocks from other servers (as determined by their storage class and "rendezvous hashing order":{{site.baseurl}}/api/storage.html).  Pulling a block makes a copy.  If a block is overreplicated (i.e. there are excess copies) after pulling, it will be subsequently trashed on the original server.
 170
 171 h3. Configure storage volumes
 172
 173 Available storage volume types include POSIX filesystems and cloud object storage.
 174
 175 * To use a POSIX filesystem, including both local filesystems (ext4, xfs) and network file system such as GPFS or Lustre, follow the setup instructions on "Filesystem storage":configure-fs-storage.html
 176 * If you are using S3-compatible object storage (including Amazon S3, Google Cloud Storage, and Ceph RADOS), follow the setup instructions on "S3 Object Storage":configure-s3-object-storage.html
 177 * If you are using Azure Blob Storage, follow the setup instructions on "Azure Blob Storage":configure-azure-blob-storage.html
 178
 179 h3. Run keepstore as a supervised service
 180
 181 Install runit to supervise the keepstore daemon.  {% include 'install_runit' %}
 182
 183 Install this script as the run script @/etc/sv/keepstore/run@ for the keepstore service:
 184
 185 <notextile>
 186 <pre><code>#!/bin/sh
 187
 188 exec 2>&1
 189 GOGC=10 exec keepstore -config /etc/arvados/keepstore/keepstore.yml
 190 </code></pre>
 191 </notextile>
 192
 193 h3. Set up additional servers
 194
 195 Repeat the above sections to prepare volumes and bring up supervised services on each Keepstore server you are setting up.
 196
 197 h3. Tell the API server about the Keepstore servers
 198
 199 The API server needs to be informed about the presence of your Keepstore servers. For each of the Keepstore servers you have created, please execute the following commands on your <strong>shell server</strong>.
 200
 201 Make sure to update the @service_host@ value to match each of your Keepstore servers.
 202
 203 <notextile>
 204 <pre><code>~$ <span class="userinput">prefix=`arv --format=uuid user current | cut -d- -f1`</span>
 205 ~$ <span class="userinput">echo "Site prefix is '$prefix'"</span>
 206 ~$ <span class="userinput">read -rd $'\000' keepservice &lt;&lt;EOF; arv keep_service create --keep-service "$keepservice"</span>
 207 <span class="userinput">{
 208  "service_host":"<strong>keep0.$prefix.your.domain</strong>",
 209  "service_port":25107,
 210  "service_ssl_flag":false,
 211  "service_type":"disk"
 212 }
 213 EOF</span>
 214 </code></pre></notextile>