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.
 120 PullWorkers: 0
 121
 122 # Honor read requests only if a valid signature is provided.  This
 123 # should be true, except for development use and when migrating from
 124 # a very old version.
 125 RequireSignatures: true
 126
 127 # Local file containing the Arvados API token used by keep-balance
 128 # or data manager.  Delete, trash, and index requests are honored
 129 # only for this token.
 130 SystemAuthTokenFile: ""
 131
 132 # Path to server certificate file in X509 format. Enables TLS mode.
 133 #
 134 # Example: /var/lib/acme/live/keep0.example.com/fullchain
 135 TLSCertificateFile: ""
 136
 137 # Path to server key file in X509 format. Enables TLS mode.
 138 #
 139 # The key pair is read from disk during startup, and whenever SIGHUP
 140 # is received.
 141 #
 142 # Example: /var/lib/acme/live/keep0.example.com/privkey
 143 TLSKeyFile: ""
 144
 145 # How often to check for (and delete) trashed blocks whose
 146 # TrashLifetime has expired.
 147 TrashCheckInterval: 24h0m0s
 148
 149 # Time duration after a block is trashed during which it can be
 150 # recovered using an /untrash request.
 151 TrashLifetime: 336h0m0s
 152
 153 # Maximum number of concurrent trash operations. Default is 1, i.e.,
 154 # trash lists are processed serially.
 155 TrashWorkers: 1
 156 </pre>
 157
 158 h3. Notes on storage management
 159
 160 On its own, a keepstore server never deletes data.  The "keep-balance":install-keep-balance.html service service determines which blocks are candidates for deletion and instructs the keepstore to move those blocks to the trash.
 161
 162 When a block is newly written, it is protected from deletion for the duration in @BlobSignatureTTL@.  During this time, it cannot be trashed.
 163
 164 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 has been moved out of the way and 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@.
 165
 166 h3. Configure storage volumes
 167
 168 Available storage volume types include cloud object storage and POSIX filesystems.
 169
 170 If you are using S3-compatible object storage (including Amazon S3, Google Cloud Storage, and Ceph RADOS), follow the setup instructions "S3 Object Storage":configure-s3-object-storage.html page instead and then "Run keepstore as a supervised service.":#keepstoreservice
 171
 172 If you are using Azure Blob Storage, follow the setup instructions "Azure Blob Storage":configure-azure-blob-storage.html and then proceed to "Run keepstore as a supervised service.":#keepstoreservice
 173
 174 To use a POSIX filesystem, including both local filesystems (ext4, xfs) and network file system such as GPFS or Lustre, continue reading this section.
 175
 176 h4. Setting up filesystem mounts
 177
 178 Volumes are configured in the @Volumes@ section of the configuration
 179 file.  You may provide multiple volumes for a single keepstore process
 180 to manage multiple disks.  Keepstore distributes blocks among volumes
 181 in round-robin fashion.
 182
 183 <pre>
 184 Volumes:
 185 - # The volume type, indicates this is a filesystem directory.
 186   Type: Directory
 187
 188   # The actual directory that will be used as the backing store.
 189   Root: /mnt/local-disk
 190
 191   # How much replication is performed by the underlying filesystem.
 192   # (for example, a network filesystem may provide its own replication).
 193   # This is used to inform replication decisions at the Keep layer.
 194   DirectoryReplication: 1
 195
 196   # If true, do not accept write or trash operations, only reads.
 197   ReadOnly: false
 198
 199   # When true, read and write operations (for whole 64MiB blocks) on
 200   # an individual volume will queued and issued sequentially.  When
 201   # false, read and write operations will be issued concurrently as
 202   # they come in.
 203   #
 204   # When using spinning disks where storage partitions map 1:1 to
 205   # physical disks that are dedicated to Keepstore, enabling this may
 206   # reduce contention and improve throughput by minimizing seeks.
 207   #
 208   # When using SSDs, RAID, or a parallel network filesystem, you probably
 209   # don't want this.
 210   Serialize: true
 211
 212   # Storage classes to associate with this volume.  See "Configuring
 213   # storage classes" in the "Admin" section of doc.arvados.org.
 214   StorageClasses: null
 215
 216   # Example of a second volume section
 217 - DirectoryReplication: 2
 218   ReadOnly: false
 219   Root: /mnt/network-disk
 220   Serialize: false
 221   StorageClasses: null
 222   Type: Directory
 223 </pre>
 224
 225 h3(#keepstoreservice). Run keepstore as a supervised service
 226
 227 Install runit to supervise the keepstore daemon.  {% include 'install_runit' %}
 228
 229 Install this script as the run script @/etc/sv/keepstore/run@ for the keepstore service:
 230
 231 <notextile>
 232 <pre><code>#!/bin/sh
 233
 234 exec 2>&1
 235 GOGC=10 exec keepstore -config /etc/arvados/keepstore/keepstore.yml
 236 </code></pre>
 237 </notextile>
 238
 239 h3. Set up additional servers
 240
 241 Repeat the above sections to prepare volumes and bring up supervised services on each Keepstore server you are setting up.
 242
 243 h3. Tell the API server about the Keepstore servers
 244
 245 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>.
 246
 247 Make sure to update the @service_host@ value to match each of your Keepstore servers.
 248
 249 <notextile>
 250 <pre><code>~$ <span class="userinput">prefix=`arv --format=uuid user current | cut -d- -f1`</span>
 251 ~$ <span class="userinput">echo "Site prefix is '$prefix'"</span>
 252 ~$ <span class="userinput">read -rd $'\000' keepservice &lt;&lt;EOF; arv keep_service create --keep-service "$keepservice"</span>
 253 <span class="userinput">{
 254  "service_host":"<strong>keep0.$prefix.your.domain</strong>",
 255  "service_port":25107,
 256  "service_ssl_flag":false,
 257  "service_type":"disk"
 258 }
 259 EOF</span>
 260 </code></pre></notextile>