(s3tables-alpha): support ReplicationConfiguration for TableBucket

[badmintoncryer]

Describe the feature

Add support for S3 Tables Bucket replication by exposing the L1
AWS::S3Tables::TableBucket ReplicationConfiguration property through the
L2 TableBucket construct in @aws-cdk/aws-s3tables-alpha.

Related docs:

• https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-replication.html
• https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3tables-tablebucket-replicationconfiguration.html

Use Case

We want to replicate S3 Tables across Regions / accounts for DR and
cross-account analytics. The L1 already accepts ReplicationConfiguration,
but the L2 TableBucket has no first-class API, so users have to drop down
to the CfnTableBucket escape hatch today.

Proposed Solution

Add two flat props to TableBucketProps (mirroring the pattern used by
aws-s3's replicationRole / replicationRules):

export interface TableBucketProps {
  // ... existing props

  /**
   * Destination table buckets to replicate to.
   *
   * @default - No replication
   */
  readonly replicationDestinations?: ITableBucket[];

  /**
   * The role to be used by the replication.
   *
   * When setting this property, you must also set `replicationDestinations`.
   *
   * @default - a new role will be created.
   */
  readonly replicationRole?: iam.IRole;
}

// Usage
const dest = TableBucket.fromTableBucketArn(this, 'Dest', 'arn:...');
new TableBucket(this, 'Source', {
  tableBucketName: 'src',
  replicationDestinations: [dest],
});

When replicationRole is omitted the construct creates a role with
least-privilege replication permissions and an s3tables.amazonaws.com trust
policy with aws:SourceAccount / aws:SourceArn confused-deputy conditions.

Notes:

• The CFN ReplicationConfiguration wraps destinations in a rules: []
  array, but a rule currently has no fields other than destinations, so
  flattening to a single replicationDestinations: ITableBucket[] avoids a
  speculative abstraction. If AWS later adds per-rule settings (filter,
  priority, etc.), we can evolve the API — breaking changes are acceptable
  in the alpha package.
• Escape hatch remains available via node.defaultChild on the underlying
  CfnTableBucket.

Other Information

• L1 types (CfnTableBucket.ReplicationConfigurationProperty etc.) already
  exist in aws-cdk-lib/aws-s3tables, so no L1 work is needed.
• Additive props, no breaking change.

Acknowledgements

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

AWS CDK Library version (aws-cdk-lib)

2.250.0

AWS CDK CLI version

2.1030.0

Environment details (OS name and version, etc.)

macOS 14.6 (Darwin 23.6.0)

[pahud]

Hi @badmintoncryer,

┌──────────────────────────────┐     ┌──────────────────────────────┐
│ TableBucketProps adds         │ ──> │ Constructor creates IAM role  │
│ replicationDestinations &    │     │ with s3tables trust policy   │
│ replicationRole              │     │ + confused-deputy conditions  │
└──────────────────────────────┘     └──────────────────────────────┘
                                                   │
                                                   v
                                     ┌──────────────────────────────┐
                                     │ Maps to CfnTableBucket       │
                                     │ ReplicationConfiguration     │
                                     │ { role, rules: [{ dests }] } │
                                     └──────────────────────────────┘

Thanks for the well-structured feature request. In my opinion, the proposed API design with replicationDestinations and replicationRole is a clean approach that aligns well with the existing patterns in the CDK (e.g., aws-s3 replication).

I confirmed that the L2 TableBucket currently does not pass replicationConfiguration to the underlying CfnTableBucket:

https://github.com/aws/aws-cdk/blob/818574f2026c4a31f51e7bc03c0079fb9fd76478/packages/@aws-cdk/aws-s3tables-alpha/lib/table-bucket.ts

The CloudFormation resource already supports ReplicationConfiguration with Role and Rules[].Destinations[].DestinationTableBucketARN, so the L1 types should be available.

Since you indicated you may be able to implement this, a PR would be very welcome! 🙌