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, Ceph RADOS, NetApp StorageGRID, and others.
  13
  14 Volumes are configured in the @Volumes@ section of the cluster configuration file.
  15
  16 # "Configuration example":#example
  17 # "IAM Policy":#IAM
  18
  19 h2(#example). Configuration example
  20
  21 {% include 'assign_volume_uuid' %}
  22
  23 <notextile><pre><code>    Volumes:
  24       <span class="userinput">ClusterID</span>-nyw5e-<span class="userinput">000000000000000</span>:
  25         AccessViaHosts:
  26           # This section determines which keepstore servers access the
  27           # volume. In this example, keep0 has read/write access, and
  28           # keep1 has read-only access.
  29           #
  30           # If the AccessViaHosts section is empty or omitted, all
  31           # keepstore servers will have read/write access to the
  32           # volume.
  33           "http://<span class="userinput">keep0.ClusterID.example.com</span>:25107": {}
  34           "http://<span class="userinput">keep1.ClusterID.example.com</span>:25107": {ReadOnly: true}
  35
  36         Driver: <span class="userinput">S3</span>
  37         DriverParameters:
  38           # Bucket name.
  39           Bucket: <span class="userinput">example-bucket-name</span>
  40
  41           # IAM role name to use when retrieving credentials from
  42           # instance metadata. It can be omitted, in which case the
  43           # role name itself will be retrieved from instance metadata
  44           # -- but setting it explicitly may protect you from using
  45           # the wrong credentials in the event of an
  46           # installation/configuration error.
  47           IAMRole: <span class="userinput">""</span>
  48
  49           # If you are not using an IAM role for authentication,
  50           # specify access credentials here instead.
  51           AccessKeyID: <span class="userinput">""</span>
  52           SecretAccessKey: <span class="userinput">""</span>
  53
  54           # Storage provider region. If Endpoint is specified, the
  55           # region determines the request signing method, and defaults
  56           # to "us-east-1".
  57           Region: <span class="userinput">us-east-1</span>
  58
  59           # Storage provider endpoint. For Amazon S3, use "" or
  60           # omit. For Google Cloud Storage, use
  61           # "https://storage.googleapis.com".
  62           Endpoint: ""
  63
  64           # Change to true if the region requires a LocationConstraint
  65           # declaration.
  66           LocationConstraint: false
  67
  68           # Use V2 signatures instead of the default V4. Amazon S3
  69           # supports V4 signatures in all regions, but this option
  70           # might be needed for other S3-compatible services.
  71           V2Signature: false
  72
  73           # Use the AWS S3 v2 Go driver instead of the goamz driver.
  74           UseAWSS3v2Driver: false
  75
  76           # By default keepstore stores data using the MD5 checksum
  77           # (32 hexadecimal characters) as the object name, e.g.,
  78           # "0123456abc...". Setting PrefixLength to 3 changes this
  79           # naming scheme to "012/0123456abc...". This can improve
  80           # performance, depending on the S3 service being used. For
  81           # example, PrefixLength 3 is recommended to avoid AWS
  82           # limitations on the number of read/write operations per
  83           # second per prefix (see
  84           # https://aws.amazon.com/premiumsupport/knowledge-center/s3-request-limit-avoid-throttling/).
  85           #
  86           # Note that changing PrefixLength on an existing volume is
  87           # not currently supported. Once you have started using a
  88           # bucket as an Arvados volume, you should not change its
  89           # configured PrefixLength, or configure another volume using
  90           # the same bucket and a different PrefixLength.
  91           PrefixLength: 0
  92
  93           # Requested page size for "list bucket contents" requests.
  94           IndexPageSize: 1000
  95
  96           # Maximum time to wait while making the initial connection
  97           # to the backend before failing the request.
  98           ConnectTimeout: 1m
  99
 100           # Maximum time to wait for a complete response from the
 101           # backend before failing the request.
 102           ReadTimeout: 2m
 103
 104           # Maximum eventual consistency latency
 105           RaceWindow: 24h
 106
 107         # How much replication is provided by the underlying bucket.
 108         # This is used to inform replication decisions at the Keep
 109         # layer.
 110         Replication: 2
 111
 112         # If true, do not accept write or trash operations, even if
 113         # AccessViaHosts.*.ReadOnly is false.
 114         #
 115         # If false or omitted, enable write access (subject to
 116         # AccessViaHosts.*.ReadOnly, where applicable).
 117         ReadOnly: false
 118
 119         # Storage classes to associate with this volume.  See "Storage
 120         # classes" in the "Admin" section of doc.arvados.org.
 121         StorageClasses: null
 122 </code></pre></notextile>
 123
 124 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@.
 125
 126 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.
 127
 128 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.
 129
 130 h2(#IAM). IAM Policy
 131
 132 On Amazon, VMs which will access the S3 bucket (these include keepstore and compute nodes) will need an IAM policy with "permission that can read, write, list and delete objects in the bucket":https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html .  Here is an example policy:
 133
 134 <notextile>
 135 <pre>
 136 {
 137     "Id": "arvados-keepstore policy",
 138     "Statement": [
 139         {
 140             "Effect": "Allow",
 141             "Action": [
 142                   "s3:*"
 143             ],
 144             "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume"
 145             "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume/*"
 146         }
 147     ]
 148 }
 149 </pre>
 150 </notextile>