feat(s3): allow specifying a custom IAM Role for bucket replication

[hassaku63]

Issue # (if applicable)

Closes #33974

Reason for this change

Currently, the aws-s3 module automatically creates and manages the IAM Role used for S3 replication. This limits integration flexibility, especially in environments where IAM Roles are provisioned externally or reused across stacks/accounts.

This change addresses that limitation by allowing users to provide a custom IAM Role for replication.

Description of changes

• Introduced an optional replicationRole?: iam.IRole property in BucketProps.
• When replicationRole is provided, the CDK uses it instead of creating a new role.
• Required permissions are NOT automatically attached to the provided role. It is the user's responsibility to attach the necessary IAM policies.
• Added validation to ensure that if replicationRole is specified, replicationRules must also be defined and non-empty, since both are required by CloudFormation when configuring replication.

Describe any new or updated permissions being added

No new IAM actions are introduced. When a custom role is provided, CDK does not attach any permissions automatically. Users are expected to grant the appropriate replication-related permissions manually.

Description of how you validated changes

Added unit and integ tests.

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

[aws-cdk-automation]

(This review is outdated)

[hassaku63]

Additional information

Behavior when replicationRole is specified without replicationRules

See: #33974 (comment)

As described in the comment above, this PR implements validation to throw an error when a replicationRole is provided without corresponding replicationRules. This is aligned with CloudFormation requirements, where both Role and Rules must be specified when enabling replication.

Whether CDK should automatically attach permissions to a user-supplied IAM Role

In the current implementation, the CDK does not automatically attach replication permissions to a user-supplied IAM Role.

While it might be reasonable to support this via a method like grantReplicationPermission(), I believe it would be best handled in a separate issue and follow-up PR. (That said, I’m also open to including it in this PR if the reviewers feel it makes sense to do so.)

Since replication-related settings are finalized during the construction of the Bucket object, another viable approach could be to automatically attach the required permissions inside the renderReplicationConfiguration method.

I'm currently undecided on which approach would be best, so I’d greatly appreciate any feedback or recommendations from the reviewers.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.98%. Comparing base (74cbe27) to head (e039e08).
Report is 26 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #33978   +/-   ##
=======================================
  Coverage   83.98%   83.98%           
=======================================
  Files         120      120           
  Lines        6976     6976           
  Branches     1178     1178           
=======================================
  Hits         5859     5859           
  Misses       1005     1005           
  Partials      112      112           

Flag	Coverage Δ
suite.unit	83.98% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
packages/aws-cdk	∅ <ø> (∅)
packages/aws-cdk-lib/core	83.98% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[badmintoncryer]

Thank you for your contribution!! I added two minor comments.

[badmintoncryer]

You probably don't need to explicitly disable this function flag. It will be set true implicitly.

Suggested change

	postCliContext: {
	[SET_UNIQUE_REPLICATION_ROLE_NAME]: false,
	},

This fix should not cause any differences in the snapshot generation in this integration test, but if it does, I would appreciate it if you could run the snapshot update again.

[hassaku63]

Thank you for your feedback. You're right, it doesn't seem necessary to consider this in the current test scenario. I will remove it.

[badmintoncryer]

It's probably correct not to specify replicationRules, right?

Suggested change

replicationRules: [],

[hassaku63]

You are absolutely right. This replicationRule did not reflect the original intent of testing the unspecified state. I have removed it in the latest commit.

[badmintoncryer]

Thanks!!

[shikha372]

Thank you @hassaku63 for this contribution, I agree with abstracting the permissions under a new method , which can be added in a follow up PR.

Note: added do-not-merge just to confirm internally that this doesn't require any security review.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

This pull request has been removed from the queue for the following reason: pull request dequeued.

Pull request #33978 has been dequeued. The pull request rule doesn't match anymore. The following conditions don't match anymore:

• -label~=(blocked|do-not-merge|no-squash|two-approvers|priority-pr)
• status-success=validate-pr
• status-success~=AWS CodeBuild us-east-1
• any of: [🔀 queue conditions]
  • all of: [📌 queue conditions of queue default-squash]
    • any of: [🛡 GitHub branch protection]
      • check-neutral = validate-pr
      • check-skipped = validate-pr
      • check-success = validate-pr
    • any of: [🛡 GitHub branch protection]
      • check-neutral = AWS CodeBuild us-east-1 (AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv)
      • check-skipped = AWS CodeBuild us-east-1 (AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv)
      • check-success = AWS CodeBuild us-east-1 (AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv).

You should look at the reason for the failure and decide if the pull request needs to be fixed or if you want to requeue it.
If you do update this pull request, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio requeue comment.

[aws-cdk-automation]

AWS CodeBuild CI Report

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

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