feat(s3): support S3 Metadata configuration on buckets

[yasomaru]

Issue # (if applicable)

Closes #38468.

Reason for this change

S3 Metadata captures the metadata of the objects in a bucket as queryable Apache Iceberg tables: a journal table of every change made to the objects, an inventory table of their current state, and an annotation table holding the custom business context that S3 Annotations attach to objects.

AWS::S3::Bucket has supported MetadataConfiguration for a while, but nothing in the L2 reaches it, so users have to drop to the escape hatch and hand-write the raw CloudFormation shape:

const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;
cfnBucket.metadataConfiguration = {
  journalTableConfiguration: {
    recordExpiration: { expiration: 'ENABLED', days: 10 },
    encryptionConfiguration: { sseAlgorithm: 'aws:kms', kmsKeyArn: key.keyArn },
  },
};

That loses everything the L2 normally provides: no typed values for Expiration / ConfigurationState / SseAlgorithm, no Duration for the retention period, raw ARN strings instead of kms.IKey and iam.IRoleRef, and no synth-time validation.

Description of changes

Per the feature placement decision, this feature is about the bucket, extends its own L1 properties, and carries logic beyond a prop passthrough, so it is implemented as a mixin first and exposed through an L2 prop for convenience:

• s3.mixins.BucketMetadataConfiguration holds all the logic — validation and rendering to CfnBucket.metadataConfiguration. It is applicable to L1 and L2 buckets alike.
• BucketProps.metadataConfiguration applies that mixin via this.with(...).

Design decisions:

• Encryption is an enum-like class (MetadataTableEncryption.s3Managed() / .kms(key)) rather than separate sseAlgorithm + kmsKeyArn props. The L1 pair is only valid in two combinations, and folding them into factory methods makes the invalid ones unrepresentable while accepting a kms.IKey instead of an ARN string.
• Duration for record expiration instead of a raw day count, guarded with Token.isUnresolved() so a tokenized duration (e.g. from a CfnParameter) is not rejected by the range check.
• iam.IRoleRef for the annotation table role, since only the ARN is needed.
• A journal table is always rendered. S3 always creates one for a V2 configuration, so journalTable configures it rather than enabling it, and metadataConfiguration: {} is a valid minimal configuration.
• role is validated as required when the annotation table is enabled. CloudFormation documents AnnotationTableConfiguration.Role as optional, but S3 rejects the stack with Invalid request provided: Role is required when AnnotationTableConfiguration ConfigurationState is ENABLED. This was found by deploying the integration test. Because the input was accepted at synth but always failed at deploy, this is a fail-fast synth-time validation and does not need a feature flag.

Alternatives considered and rejected:

• Adding the property directly to BucketProps only, matching how the older versioned and inventories props render straight to the L1 in the Bucket constructor. Rejected because new features must be building blocks first, and a mixin also serves L1 users.
• Modelling V1 MetadataTableConfiguration in the same PR. Rejected to keep one concern per PR: V1 stores its tables in a customer-managed table bucket, and ITableBucket currently only exists in the alpha aws-s3tables-alpha module, which aws-cdk-lib cannot depend on. Using the generated ITableBucketRef instead is a separate design decision. This PR therefore addresses the V2 configuration from (aws-s3): support S3 Metadata (metadataConfiguration / metadataTableConfiguration) on the Bucket L2 #38468; V1 remains open.

No breaking changes: every new property is optional and additive.

Describe any new or updated permissions being added

None. This change does not create or modify any IAM policy.

Two permission-related notes for users, both documented in the README rather than wired automatically:

• When the metadata tables are encrypted with a customer managed key, that key's policy must allow kms:Decrypt and kms:GenerateDataKey for the metadata.s3.amazonaws.com and maintenance.s3tables.amazonaws.com service principals. The construct does not modify the key policy, because the key is frequently shared and imported.
• Enabling the annotation table requires the caller to supply a role assumable by metadata.s3.amazonaws.com.

Description of how you validated changes

Unit tests — 15 new tests. In bucket.test.ts: absent by default, the minimal {} configuration, record expiration, inventory and annotation tables, both encryption modes, and every validation failure (missing/superfluous retention, out-of-range retention via test.each, annotation table without a role) plus a tokenized Duration passing the range check. In mixins.test.ts: the mixin applied directly to a CfnBucket, its validation, and supports() returning false for a non-S3 construct. The whole aws-s3 suite passes (363 tests).

Integration test — integ.bucket-metadata-configuration.ts covers a bucket with only a journal table and a bucket with all three tables, KMS encryption and a 7 day retention. It was deployed to us-east-1 and the assertions verified the configuration by calling GetBucketMetadataConfiguration against the live buckets.

Deploying is what surfaced the required-role behaviour described above; the first deploy failed on it. Two notes on the test itself:

• The assertion needs an explicit s3:GetBucketMetadataTableConfiguration grant, because that is the IAM action name for both the V1 and V2 API operations and it does not match the V2 API name the assertion derives its grant from.
• AnnotationTableConfigurationResult is deliberately not asserted: the assertion provider's SDK did not return that key. The annotation table is still exercised, since S3 rejects the stack outright if its configuration is invalid.

Other — yarn build for aws-cdk-lib passes, including awslint and eslint. The README examples compile under Rosetta.

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)

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

[lpizzinidev]

Some comments, ty!

[lpizzinidev]

Are we missing the Destination attribute?

[yasomaru]

Good catch, added. MetadataConfiguration.destination now maps to a MetadataDestination struct with tableBucketType (a new MetadataTableBucketType enum for aws | customer), tableBucket and tableNamespace. tableBucket takes an s3tables.ITableBucketRef rather than an ARN string; I checked that aws-s3tables does not reference aws-s3, so this does not introduce a cycle.

[lpizzinidev]

Can we express this as a boolean attribute? Example.
Same for MetadataRecordExpiration below.

[yasomaru]

Done. MetadataConfigurationState and MetadataRecordExpiration are both gone. The table configurations now take enabled?: boolean (defaulting to true, so inventoryTable: {} enables it), and the journal table takes recordExpiration?: boolean. Reads much better, thanks.

[lpizzinidev]

Minimum seems to be 7, see docs.

[yasomaru]

You are right, and thank you for catching it. The docs say records "must be retained for a minimum of 7 days", so the lower bound is now 7 rather than 1. This was a real defect: Duration.days(1) would have passed synth and failed at deploy, which is exactly what this validation exists to prevent. My integration test happened to use 7 days, so the deployment did not catch it either. I extended the boundary test to [0, 1, 6, 2147483648] and added a case asserting that exactly 7 days is accepted.

[lpizzinidev]

All the CFN definitions seem to allow passing a customer table (via ARN and name). Why don't we support the feature here? Docs

[yasomaru]

Added tableArn and tableName to all three table configurations. I had assumed these were service-populated outputs rather than inputs and left them out on that basis, which was wrong: the CFN reference lists them as settable optional properties. Thanks for pushing back on it.

[lpizzinidev]

Can we test one with aes256?

[yasomaru]

Done. The inventory table on FullBucket now uses MetadataTableEncryption.s3Managed() while the journal and annotation tables stay on SSE-KMS, so one deployment exercises both encryption modes. Redeployed to us-east-1 and the assertions pass.