diff --git a/docs/development/extensions-core/s3.md b/docs/development/extensions-core/s3.md index a8dbaef1a3b..e347952e205 100644 --- a/docs/development/extensions-core/s3.md +++ b/docs/development/extensions-core/s3.md @@ -56,7 +56,7 @@ To use S3 for Deep Storage, you must supply [connection information](#configurat |`druid.storage.type`|Global deep storage provider. Must be set to `s3` to make use of this extension.|Must be set (likely `s3`).| |`druid.storage.archiveBucket`|S3 bucket name for archiving when running the *archive task*.|none| |`druid.storage.archiveBaseKey`|S3 object key prefix for archiving.|none| -|`druid.storage.disableAcl`|Boolean flag to disable ACL. If this is set to `false`, the full control would be granted to the bucket owner. This may require to set additional permissions. See [S3 permissions settings](#s3-permissions-settings).|false| +|`druid.storage.disableAcl`|Boolean flag for how object permissions are handled. To use ACLs, set this property to `false`. To use Object Ownership, set it to `true`. The permission requirements for ACLs and Object Ownership are different. For more information, see [S3 permissions settings](#s3-permissions-settings).|false| |`druid.storage.useS3aSchema`|If true, use the "s3a" filesystem when using Hadoop-based ingestion. If false, the "s3n" filesystem will be used. Only affects Hadoop-based ingestion.|false| ## Configuration @@ -85,9 +85,31 @@ Use the property [`druid.startup.logging.maskProperties`](../../configuration/in ### S3 permissions settings -`s3:GetObject` and `s3:PutObject` are required for pushing or pulling segments to or from S3. +To manage the permissions for objects in an S3 bucket, you can use either ACLs or Object Ownership. The permissions required for each method are different. -If `druid.storage.disableAcl` is set to `false`, then `s3:GetBucketAcl` and `s3:PutObjectAcl` are additionally required to set ACL for objects. +By default, Druid uses ACLs. With ACLs, any object that Druid puts into the bucket inherits the ACL settings from the bucket. + +You can switch from using ACLs to Object Ownership by setting `druid.storage.disableAcl` to `true`. The bucket owner owns any object that gets created, so you need to use S3's bucket policies to manage permissions. + +Note that this setting only affects Druid's behavior. Changing S3 to use Object Ownership requires additional configuration. For more information, see the AWS documentation on [Controlling ownership of objects and disabling ACLs for your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html). + +#### ACL permissions + +If you're using ACLs, Druid needs the following permissions: + +- `s3:GetObject` +- `s3:PutObject` +- `s3:DeleteObject` +- `s3:GetBucketAcl` +- `s3:PutObjectAcl` + +#### Object Ownership permissions + +If you're using Object Ownership, Druid needs the following permissions: + +- `s3:GetObject` +- `s3:PutObject` +- `s3:DeleteObject` ### AWS region