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 v2 Go driver instead of the goamz driver.
  68           UseAWSS3v2Driver: 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 @UseAWSS3v2Driver@ 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 can improve read performance by 50-100% over the @goamz@ driver, but it has not had as much production use. See the "wiki":https://dev.arvados.org/projects/arvados/wiki/Keep_real_world_performance_numbers for details.