(aws-s3): add a convenient way to grant permissions to an IAM Role for S3 replication

[hassaku63]

Describe the feature

This feature proposes adding a convenient way for AWS CDK users to grant the necessary permissions to an IAM Role that will be used for S3 bucket replication.

Currently, when a user provides their own IAM Role for replication, they need to manually attach the required permissions. This feature aims to simplify this process by providing a mechanism within the CDK to handle these permissions.

Use Case

Users who choose to provide their own IAM Role for S3 bucket replication need to understand and manually configure the necessary permissions. This can be error-prone and time-consuming, especially for users who are not deeply familiar with the specific IAM permissions required for S3 replication.

Furthermore, as discussed in issue #33974, there is an ongoing effort to enable the use of custom IAM Roles for replication within L2 Constructs. If that feature is implemented, this proposal would provide users with an easier way to configure custom IAM Roles and replication sources entirely within the L2 construct.

Proposed Solution

I propose introducing a method, potentially within the Bucket construct or a related interface, that allows users to easily grant the required S3 replication permissions to a user-supplied IAM Role. Two potential approaches are being considered (as mentioned in the prior discussion):

1. A dedicated method (grantReplicationPermission(role: iam.IRole)): This method could be called on the Bucket object, taking the IAM Role as an argument and attaching the necessary replication permissions to it. This approach would be explicit and user-initiated.

2. Automatic permission attachment within renderReplicationConfiguration: Since the replication configuration is finalized during the Bucket object's construction, the CDK could automatically attach the required permissions to the provided IAM Role within the renderReplicationConfiguration method. This approach would be more implicit.

Personally, I believe that providing a dedicated grantReplicationPermission method (option 1) would be the most user-friendly and transparent solution. It offers explicit control over the IAM Role's permissions and makes it clear when and how these permissions are being granted.

This feature proposal explicitly allows users to grant necessary permissions to their own IAM Role, which I anticipate will be a common use case, especially in conjunction with the ability to specify custom roles for replication (as proposed in #33974). In such scenarios, a user-initiated configuration method aligns well with the explicit nature of specifying a custom role. Therefore, an explicit approach like option 1, which aligns with common CDK patterns, is preferable to the implicit option 2.

Prototype-style API:

declare const props: s3.BucketProps;
declare const replicationRole: iam.IRole;

// This is a conceptual implementation based on the implementation of issue #33974 .
const bucket = new s3.Bucket(this, 'Bucket', {
  ...props,
  replicationRole,
  replicationRules: [
    /* ... */
  ],
});

bucket.grantReplicationPermission(replicationRole);

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

v2.186.0

Environment details (OS name and version, etc.)

MacOS 14.5

[pahud]

Hi @hassaku63,

Thank you for raising this feature request. Your proposal for a dedicated method to grant the necessary S3 replication permissions to a user-supplied IAM Role addresses an important usability gap in the current CDK implementation.

Currently, as you've identified, users need to manually attach the correct permissions to their custom IAM roles for S3 replication, which can indeed lead to mistakes and inefficiencies. While there is an addReplicationPolicy method for destination buckets, there isn't an equivalent helper for granting permissions to a source-side custom IAM Role.

Introducing a method like grantReplicationPermission(role: iam.IRole) on the Bucket construct would align well with other grant methods (such as grantRead and grantWrite), offering a more seamless and error-resistant way for users to adopt advanced replication configurations.

We encourage community contributions for this feature request! If you are able, we’d be happy to review a PR that implements this capability according to your proposed API, following the established patterns in the CDK codebase.

Thanks again for your detailed suggestion and willingness to help improve the CDK experience!

[hassaku63]

I have almost finished the implementation for this issue (such as feature method, unit and integ test, readme, confirming no regression).

I'm assuming that the preceding #33978 will be completed, so as soon as it's merged I'll get the local code in place and submit it for review.