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           # Optionally, you can specify S3 access credentials here.
  42           # If these are left blank, IAM role credentials will be
  43           # retrieved from instance metadata (IMDSv2).
  44           AccessKeyID: <span class="userinput">""</span>
  45           SecretAccessKey: <span class="userinput">""</span>
  46
  47           # Storage provider region. If Endpoint is specified, the
  48           # region determines the request signing method, and defaults
  49           # to "us-east-1".
  50           Region: <span class="userinput">us-east-1</span>
  51
  52           # Storage provider endpoint. For Amazon S3, use "" or
  53           # omit. For Google Cloud Storage, use
  54           # "https://storage.googleapis.com".
  55           Endpoint: ""
  56
  57           # Change to true if the region requires a LocationConstraint
  58           # declaration.
  59           LocationConstraint: false
  60
  61           # Use V2 signatures instead of the default V4. Amazon S3
  62           # supports V4 signatures in all regions, but this option
  63           # might be needed for other S3-compatible services.
  64           V2Signature: false
  65
  66           # Use path-style requests instead of the default
  67           # virtual-hosted-style requests.  This might be needed for
  68           # S3-compatible services other than AWS.  If using AWS, see
  69           # https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access
  70           # for deprecation information.
  71           UsePathStyle: false
  72
  73           # By default keepstore stores data using the MD5 checksum
  74           # (32 hexadecimal characters) as the object name, e.g.,
  75           # "0123456abc...". Setting PrefixLength to 3 changes this
  76           # naming scheme to "012/0123456abc...". This can improve
  77           # performance, depending on the S3 service being used. For
  78           # example, PrefixLength 3 is recommended to avoid AWS
  79           # limitations on the number of read/write operations per
  80           # second per prefix (see
  81           # https://aws.amazon.com/premiumsupport/knowledge-center/s3-request-limit-avoid-throttling/).
  82           #
  83           # Note that changing PrefixLength on an existing volume is
  84           # not currently supported. Once you have started using a
  85           # bucket as an Arvados volume, you should not change its
  86           # configured PrefixLength, or configure another volume using
  87           # the same bucket and a different PrefixLength.
  88           PrefixLength: 0
  89
  90           # Requested page size for "list bucket contents" requests.
  91           IndexPageSize: 1000
  92
  93           # Maximum time to wait while making the initial connection
  94           # to the backend before failing the request.
  95           ConnectTimeout: 1m
  96
  97           # Maximum time to wait for a complete response from the
  98           # backend before failing the request.
  99           ReadTimeout: 2m
 100
 101           # Maximum eventual consistency latency
 102           RaceWindow: 24h
 103
 104         # How much replication is provided by the underlying bucket.
 105         # This is used to inform replication decisions at the Keep
 106         # layer.
 107         Replication: 2
 108
 109         # If true, do not accept write or trash operations, even if
 110         # AccessViaHosts.*.ReadOnly is false.
 111         #
 112         # If false or omitted, enable write access (subject to
 113         # AccessViaHosts.*.ReadOnly, where applicable).
 114         ReadOnly: false
 115
 116         # Storage classes to associate with this volume.  See "Storage
 117         # classes" in the "Admin" section of doc.arvados.org.
 118         StorageClasses: null
 119 </code></pre></notextile>
 120
 121 h2(#IAM). IAM Policy
 122
 123 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:
 124
 125 <notextile>
 126 <pre>
 127 {
 128     "Id": "arvados-keepstore policy",
 129     "Statement": [
 130         {
 131             "Effect": "Allow",
 132             "Action": [
 133                   "s3:*"
 134             ],
 135             "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume"
 136             "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume/*"
 137         }
 138     ]
 139 }
 140 </pre>
 141 </notextile>