feat(s3): add grantReplicationPermission for IAM Role permissions

[hassaku63]

Issue # (if applicable)

Closes #34119

Reason for this change

This change introduces a new method, grantReplicationPermission, to the aws-cdk-lib.aws_s3.Bucket construct. The purpose of this addition is to provide a more convenient and programmatic way for AWS CDK users to grant the necessary IAM permissions to a user-provided IAM Role that will be used for S3 bucket replication.

Description of changes

This pull request includes the following code changes:

• Added a new public method grantReplicationPermission to the Bucket class.
• The implementation of this method programmatically attaches the necessary IAM permissions for S3 bucket replication to the provided identity. This change refactors the renderReplicationConfiguration method by extracting the IAM permission granting functionality into a dedicated grantReplicationPermission method.
• unit and integ test
• The README was updated to show that users can now grant replication rights to custom IAM roles.

Describe any new or updated permissions being added

No new IAM permissions are being added at the CDK level. The permissions granted by the grantReplicationPermission method are the same as those already handled internally by the existing replication configuration logic. This change simply exposes that functionality through a dedicated method.

Description of how you validated changes

• Added unit tests to verify the functionality of the grantReplicationPermission method, ensuring that the correct IAM policies are attached to the provided role. Notably, the unit tests specifically cover scenarios where an explicit replicationRole is provided.
• Existing integration tests were run to confirm that no regressions were introduced by this change. In addition, the existing test scenario integ.bucket-replication-use-custom-role.ts was refactored to use the new grantReplicationPermission method instead of manually attaching the required permissions to the IAM role, and its behavior was verified to remain equivalent.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[hassaku63]

Regarding the design of the grantReplicationPermission method, I've aimed to follow the common patterns of other grant methods in the CDK, where returning an iam.Grant object is prevalent. However, this method currently has a void return type. While I intend to explore and implement the refactoring to return iam.Grant myself, I'm currently unsure about the best way to structure the Grant object for this feature, especially given the need to grant multiple distinct permissions. If the reviewers have any insights or suggestions on the most appropriate approach, I would be grateful for the guidance, as I work towards a suitable implementation.

[badmintoncryer]

Thank you for your contribution! I've added a small comment.

[badmintoncryer]

Could you please add unit test for throwing this error?

[hassaku63]

@badmintoncryer Thank you for your review, yes I have added a unit test that you noted.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 40b6e2b
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository