(aws-s3): Allow specifying a custom IAM Role for bucket replication #33974
Description
Describe the feature
Currently, when configuring replication rules for an S3 bucket using the AWS CDK aws-s3 module, there is no option to specify a custom IAM Role to be used for the replication process. The replication role is automatically created and managed by CDK.
This feature request is to allow users to explicitly specify an iam.IRole when setting up bucket replication.
Use Case
In some situations, we need to use a predefined IAM Role for replication—such as one that is managed outside of CDK, shared across multiple stacks/accounts, or controlled by organizational policies. Not being able to provide a custom role limits integration flexibility and makes it harder to align with existing IAM infrastructure.
A more concrete use case is when reusing the same Stack class across multiple deployment environments (e.g., dev, qa, prod) and replication is required between environments (e.g., from prod to qa). In such cases, being able to assign a predictable physical name to the IAM Role used for replication can be very helpful.
This predictability allows us to configure the destination bucket policy in advance to allow access from the replication role, even before deploying the source environment (e.g., prod). Without this, deployment becomes more complex as it requires coordination or post-deployment updates to permissions.
Proposed Solution
Introduce an optional property (e.g., replicationRole?: iam.IRole) in the BucketProps interface, allowing users to provide a custom IAM Role to be used for bucket replication.
If this property is specified, CDK should:
- Use the provided IAM Role instead of creating a new one automatically
- Automatically attach the necessary replication permissions to the given role, just as it would with the auto-created role
Prototype-style API:
declare const props: s3.BucketProps;
declare const replicationRole: iam.IRole;
const bucket = new s3.Bucket(this, 'Bucket', {
...props,
replicationRole,
replicationRules: [
/* ... */
],
});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