Merge branch '21815-trigrams-exclude-ids'

[arvados.git] / doc / install / configure-s3-object-storage.html.textile.liquid

diff --git a/doc/install/configure-s3-object-storage.html.textile.liquid b/doc/install/configure-s3-object-storage.html.textile.liquid
index b960ac1fda0c2ab1fbaae77e4ae3c875b8dec0bc..1aec14984ec9cd80f39f88b53caa38f194023dde 100644 (file)
--- a/doc/install/configure-s3-object-storage.html.textile.liquid
+++ b/doc/install/configure-s3-object-storage.html.textile.liquid
@@ -9,10 +9,15 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-Keepstore can store data in object storage compatible with the S3 API, such as Amazon S3, Google Cloud Storage, or Ceph RADOS.
+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.
 
 Volumes are configured in the @Volumes@ section of the cluster configuration file.
 
+# "Configuration example":#example
+# "IAM Policy":#IAM
+
+h2(#example). Configuration example
+
 {% include 'assign_volume_uuid' %}
 
 <notextile><pre><code>    Volumes:
@@ -33,22 +38,16 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
           # Bucket name.
           Bucket: <span class="userinput">example-bucket-name</span>
 
-          # IAM role name to use when retrieving credentials from
-          # instance metadata. It can be omitted, in which case the
-          # role name itself will be retrieved from instance metadata
-          # -- but setting it explicitly may protect you from using
-          # the wrong credentials in the event of an
-          # installation/configuration error.
-          IAMRole: <span class="userinput">""</span>
-
-          # If you are not using an IAM role for authentication,
-          # specify access credentials here instead.
-          AccessKey: <span class="userinput">""</span>
-          SecretKey: <span class="userinput">""</span>
+          # Optionally, you can specify S3 access credentials here.
+          # If these are left blank, IAM role credentials will be
+          # retrieved from instance metadata (IMDSv2).
+          AccessKeyID: <span class="userinput">""</span>
+          SecretAccessKey: <span class="userinput">""</span>
 
-          # Storage provider region. For Google Cloud Storage, use ""
-          # or omit.
-          Region: <span class="userinput">us-east-1a</span>
+          # Storage provider region. If Endpoint is specified, the
+          # region determines the request signing method, and defaults
+          # to "us-east-1".
+          Region: <span class="userinput">us-east-1</span>
 
           # Storage provider endpoint. For Amazon S3, use "" or
           # omit. For Google Cloud Storage, use
@@ -64,6 +63,23 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
           # might be needed for other S3-compatible services.
           V2Signature: false
 
+          # By default keepstore stores data using the MD5 checksum
+          # (32 hexadecimal characters) as the object name, e.g.,
+          # "0123456abc...". Setting PrefixLength to 3 changes this
+          # naming scheme to "012/0123456abc...". This can improve
+          # performance, depending on the S3 service being used. For
+          # example, PrefixLength 3 is recommended to avoid AWS
+          # limitations on the number of read/write operations per
+          # second per prefix (see
+          # https://aws.amazon.com/premiumsupport/knowledge-center/s3-request-limit-avoid-throttling/).
+          #
+          # Note that changing PrefixLength on an existing volume is
+          # not currently supported. Once you have started using a
+          # bucket as an Arvados volume, you should not change its
+          # configured PrefixLength, or configure another volume using
+          # the same bucket and a different PrefixLength.
+          PrefixLength: 0
+
           # Requested page size for "list bucket contents" requests.
           IndexPageSize: 1000
 
@@ -94,3 +110,25 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
         # classes" in the "Admin" section of doc.arvados.org.
         StorageClasses: null
 </code></pre></notextile>
+
+h2(#IAM). IAM Policy
+
+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:
+
+<notextile>
+<pre>
+{
+    "Id": "arvados-keepstore policy",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                  "s3:*"
+            ],
+            "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume"
+            "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume/*"
+        }
+    ]
+}
+</pre>
+</notextile>