doc/install/configure-s3-object-storage.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Configure S3 object storage
   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 can store data in object storage compatible with the S3 API, such as Amazon S3, Google Cloud Storage, or Ceph RADOS.
  13
  14 Volumes are configured in the @Volumes@ section of the cluster configuration file.
  15
  16 {% include 'assign_volume_uuid' %}
  17
  18 <notextile><pre><code>    Volumes:
  19       <span class="userinput">ClusterID</span>-nyw5e-<span class="userinput">000000000000000</span>:
  20         AccessViaHosts:
  21           # This section determines which keepstore servers access the
  22           # volume. In this example, keep0 has read/write access, and
  23           # keep1 has read-only access.
  24           #
  25           # If the AccessViaHosts section is empty or omitted, all
  26           # keepstore servers will have read/write access to the
  27           # volume.
  28           "http://<span class="userinput">keep0.ClusterID.example.com</span>:25107": {}
  29           "http://<span class="userinput">keep1.ClusterID.example.com</span>:25107": {ReadOnly: true}
  30
  31         Driver: <span class="userinput">S3</span>
  32         DriverParameters:
  33           # Bucket name.
  34           Bucket: <span class="userinput">example-bucket-name</span>
  35
  36           # IAM role name to use when retrieving credentials from
  37           # instance metadata. It can be omitted, in which case the
  38           # role name itself will be retrieved from instance metadata
  39           # -- but setting it explicitly may protect you from using
  40           # the wrong credentials in the event of an
  41           # installation/configuration error.
  42           IAMRole: <span class="userinput">""</span>
  43
  44           # If you are not using an IAM role for authentication,
  45           # specify access credentials here instead.
  46           AccessKey: <span class="userinput">""</span>
  47           SecretKey: <span class="userinput">""</span>
  48
  49           # Storage provider region. For Google Cloud Storage, use ""
  50           # or omit.
  51           Region: <span class="userinput">us-east-1a</span>
  52
  53           # Storage provider endpoint. For Amazon S3, use "" or
  54           # omit. For Google Cloud Storage, use
  55           # "https://storage.googleapis.com".
  56           Endpoint: ""
  57
  58           # Change to true if the region requires a LocationConstraint
  59           # declaration.
  60           LocationConstraint: false
  61
  62           # Use V2 signatures instead of the default V4. Amazon S3
  63           # supports V4 signatures in all regions, but this option
  64           # might be needed for other S3-compatible services.
  65           V2Signature: false
  66
  67           # Use the AWS S3 Go driver instead of the goamz driver.
  68           AlternateDriver: false
  69
  70           # Requested page size for "list bucket contents" requests.
  71           IndexPageSize: 1000
  72
  73           # Maximum time to wait while making the initial connection
  74           # to the backend before failing the request.
  75           ConnectTimeout: 1m
  76
  77           # Maximum time to wait for a complete response from the
  78           # backend before failing the request.
  79           ReadTimeout: 2m
  80
  81           # Maximum eventual consistency latency
  82           RaceWindow: 24h
  83
  84         # How much replication is provided by the underlying bucket.
  85         # This is used to inform replication decisions at the Keep
  86         # layer.
  87         Replication: 2
  88
  89         # If true, do not accept write or trash operations, even if
  90         # AccessViaHosts.*.ReadOnly is false.
  91         #
  92         # If false or omitted, enable write access (subject to
  93         # AccessViaHosts.*.ReadOnly, where applicable).
  94         ReadOnly: false
  95
  96         # Storage classes to associate with this volume.  See "Storage
  97         # classes" in the "Admin" section of doc.arvados.org.
  98         StorageClasses: null
  99 </code></pre></notextile>
 100
 101 Two S3 drivers are available. Historically, Arvados has used the @goamz@ driver to talk to S3-compatible services. More recently, support for the @aws-sdk-go-v2@ driver was added. This driver can be activated by setting the @AlternateDriver@ flag to @true@.
 102
 103 The @aws-sdk-go-v2@ does not support the old S3 v2 signing algorithm. This will not affect interacting with AWS S3, but it might be an issue when Keep is backed by a very old version of a third party S3-compatible service.
 104
 105 The @aws-sdk-go-v2@ driver has faster _single thread_ read and write performance than the @goamz@ driver. Here are some benchmark numbers against AWS S3, as measured in July 2020. They were generated with the @keep-exercise@ tool in an Arvados installation with one dedicated Keepstore node (c5n.2xlarge) and one dedicated node for running @keep-exercise@ (c5n.2xlarge). The Keepstore node was backed by one S3 bucket, in a VPC with an S3 endpoint installed. Versioning, Server Access logging, Static website hosting, Object-level logging and Default encryption were disabled. Object lock, Transfer acceleration and Requester pays were also disabled. There were no Active notifications. Each test consisted of 4 one minute runs, which were averaged into one number. The tests were repeated 3 times, and of those 3 runs, the highest average speed was selected and included in the table below.
 106
 107 table(table table-bordered table-condensed).
 108 ||_. goamz |_. aws-sdk-go-v2 |_. command line|
 109 |single thread read performance (average)|32.53 MiB/s|79.48 MiB/s|keep-exercise -repeat 4 -run-time 60s -vary-request -use-index -rthreads 1 -wthreads 1|
 110 |single thread write performance (average)|39.75 MiB/s|49.58 MiB/s|keep-exercise -repeat 4 -run-time 60s -vary-request -use-index -rthreads 1 -wthreads 1|
 111
 112 Because both S3 and Keep are optimized for _aggregate_ througput, the single thread performance is not as important as it may seem at first glance. When using 20 concurrent read or write threads, the numbers from both drivers are more closely aligned:
 113
 114 table(table table-bordered table-condensed).
 115 ||_. goamz |_. aws-sdk-go-v2 |_. command line|
 116 |20 thread read performance (average)|585.60 MiB/s|898.93 MiB/s|keep-exercise -repeat 4 -run-time 60s -vary-request -use-index -rthreads 20 -wthreads 0|
 117 |20 thread write performance (average)|610.40 MiB/s|542.40 MiB/s|keep-exercise -repeat 4 -run-time 60s -vary-request -use-index -rthreads 0 -wthreads 20|