19215: Fixes IAM policy example for Keepstore S3 access.

[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 76a2f3ab5723121cb2d0ae9d7e4724c5b2c14d06..288a9a48291ff92ca2ad2320348d4474bec300e6 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:
@@ -43,12 +48,12 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
 
           # 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>
+          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>
+          Region: <span class="userinput">us-east-1</span>
 
           # Storage provider endpoint. For Amazon S3, use "" or
           # omit. For Google Cloud Storage, use
@@ -67,6 +72,23 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
           # Use the AWS S3 v2 Go driver instead of the goamz driver.
           UseAWSS3v2Driver: 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
 
@@ -103,3 +125,25 @@ Two S3 drivers are available. Historically, Arvados has used the @goamz@ driver
 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.
 
 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.
+
+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>