(iceberg) branch main updated: AWS: Add S3 Access Grants Documentation (#9590)

[ja...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jackye pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg.git


The following commit(s) were added to refs/heads/main by this push:
     new 67a8f01bff AWS: Add S3 Access Grants Documentation (#9590)
67a8f01bff is described below

commit 67a8f01bff801f42be5cea303cf26667cecf4d79
Author: Adnan Hemani <ah...@amazon.com>
AuthorDate: Mon Feb 5 08:34:21 2024 -0800

    AWS: Add S3 Access Grants Documentation (#9590)
---
 docs/docs/aws.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/docs/aws.md b/docs/docs/aws.md
index d4cd2b22c4..2bd6636670 100644
--- a/docs/docs/aws.md
+++ b/docs/docs/aws.md
@@ -475,6 +475,30 @@ access-point for all S3 operations.
 
 For more details on using access-points, please refer [Using access points with compatible Amazon S3 operations](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-points-usage-examples.html).
 
+### S3 Access Grants
+
+[S3 Access Grants](https://aws.amazon.com/s3/features/access-grants/) can be used to grant accesses to S3 data using IAM Principals.
+In order to enable S3 Access Grants to work in Iceberg, you can set the `s3.access-grants.enabled` catalog property to `true` after
+you add the [S3 Access Grants Plugin jar](https://github.com/aws/aws-s3-accessgrants-plugin-java-v2) to your classpath. A link
+to the Maven listing for this plugin can be found [here](https://mvnrepository.com/artifact/software.amazon.s3.accessgrants/aws-s3-accessgrants-java-plugin).
+
+In addition, we allow the [fallback-to-IAM configuration](https://github.com/aws/aws-s3-accessgrants-plugin-java-v2) which allows
+you to fallback to using your IAM role (and its permission sets directly) to access your S3 data in the case the S3 Access Grants
+is unable to authorize your S3 call. This can be done using the `s3.access-grants.fallback-to-iam` boolean catalog property. By default,
+this property is set to `false`.
+
+For example, to add the S3 Access Grants Integration with Spark 3.3, you can start the Spark SQL shell with:
+```
+spark-sql --conf spark.sql.catalog.my_catalog=org.apache.iceberg.spark.SparkCatalog \
+    --conf spark.sql.catalog.my_catalog.warehouse=s3://my-bucket2/my/key/prefix \
+    --conf spark.sql.catalog.my_catalog.catalog-impl=org.apache.iceberg.aws.glue.GlueCatalog \
+    --conf spark.sql.catalog.my_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
+    --conf spark.sql.catalog.my_catalog.s3.access-grants.enabled=true \
+    --conf spark.sql.catalog.my_catalog.s3.access-grants.fallback-to-iam=true
+```
+
+For more details on using S3 Access Grants, please refer to [Managing access with S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants.html).
+
 ### S3 Acceleration
 
 [S3 Acceleration](https://aws.amazon.com/s3/transfer-acceleration/) can be used to speed up transfers to and from Amazon S3 by as much as 50-500% for long-distance transfer of larger objects.