diff --git a/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts b/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts index f9875c7a48ae9..72aaaedf9191f 100644 --- a/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts +++ b/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts @@ -31,7 +31,20 @@ export interface BucketPolicyProps { * policy if one doesn't exist yet, otherwise it will add to the existing * policy. * - * Prefer to use `addToResourcePolicy()` instead. + * The bucket policy method is implemented differently than `addToResourcePolicy()` + * as `BucketPolicy()` creates a new policy without knowing one earlier existed. + * e.g. if during Bucket creation, if `autoDeleteObject:true`, these policies are + * added to the bucket policy: + * ["s3:DeleteObject*", "s3:GetBucket*", "s3:List*", "s3:PutBucketPolicy"], + * and when you add a new BucketPolicy with ["s3:GetObject", "s3:ListBucket"] on + * this existing bucket, invoking `BucketPolicy()` will create a new Policy + * without knowing one earlier exists already, so it creates a new one. + * In this case, the custom resource handler will not have access to + * `s3:GetBucketTagging` action which will cause failure during deletion of stack. + * + * Hence its strongly recommended to use `addToResourcePolicy()` method to add + * new permissions to existing policy. + * */ export class BucketPolicy extends Resource { /**