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 <[email protected]>
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.
