feat(s3-deployment): add architecture property to BucketDeployment

Add an `architecture` property to `BucketDeploymentProps` so users can
configure the Lambda function architecture (e.g. ARM_64/Graviton) for
cost savings and sustainability improvements.

- Pass architecture through to BucketDeploymentSingletonFunction
- Include architecture in singleton UUID to isolate different configs
- Declare compatibleArchitectures on AwsCliLayer for both x86_64/arm64
- Add unit tests for architecture passthrough, singleton isolation,
  default behavior, and combined memoryLimit scenarios
- Update README with Lambda Architecture section

Closes #29996

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: badmintoncryer

packages/aws-cdk-lib/aws-s3-deployment/README.md

@@ -373,6 +373,25 @@ resource handler.
 > NOTE: a new AWS Lambda handler will be created in your stack for each combination
 > of memory and storage size.
 
+## Lambda Architecture
+
+By default, the deployment handler Lambda function uses the `X86_64` architecture.
+You can use the `architecture` property to deploy using the `ARM_64` (Graviton)
+architecture for cost savings and sustainability improvements.
+
+```ts
+declare const destinationBucket: s3.Bucket;
+
+new s3deploy.BucketDeployment(this, 'DeployWithGraviton', {
+  sources: [s3deploy.Source.asset('./website')],
+  destinationBucket,
+  architecture: lambda.Architecture.ARM_64,
+});
+```
+
+> NOTE: a new AWS Lambda handler will be created in your stack for each unique
+> combination of memory, storage size, VPC, security groups, and architecture.
+
 ## JSON-Aware Source Processing
 
 When using `Source.jsonData` with CDK Tokens (references to construct properties), you may need to enable the escaping option. This is particularly important when the referenced properties might contain special characters that require proper JSON escaping (like double quotes, line breaks, etc.).

packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts

@@ -305,6 +305,13 @@ export interface BucketDeploymentProps {
    * not specified a dedicated security group will be created for this function.
    */
   readonly securityGroups?: ec2.ISecurityGroup[];
+
+  /**
+   * The system architectures compatible with the lambda function for this deployment.
+   *
+   * @default - the default Lambda architecture (X86_64)
+   */
+  readonly architecture?: lambda.Architecture;
 }
 
 /**
@@ -380,7 +387,8 @@ export class BucketDeployment extends Construct {
 
     const mountPath = `/mnt${accessPointPath}`;
     const handler = new BucketDeploymentSingletonFunction(this, 'CustomResourceHandler', {
-      uuid: this.renderSingletonUuid(props.memoryLimit, props.ephemeralStorageSize, props.vpc, props.securityGroups),
+      uuid: this.renderSingletonUuid(props.memoryLimit, props.ephemeralStorageSize, props.vpc, props.securityGroups, props.architecture),
+      architecture: props.architecture,
       layers: [new AwsCliLayer(this, 'AwsCliLayer')],
       environment: {
         ...props.useEfs ? { MOUNT_PATH: mountPath } : undefined,
@@ -436,7 +444,7 @@ export class BucketDeployment extends Construct {
       },
     });
 
-    const crUniqueId = `CustomResource${this.renderUniqueId(props.memoryLimit, props.ephemeralStorageSize, props.vpc)}`;
+    const crUniqueId = `CustomResource${this.renderUniqueId(props.memoryLimit, props.ephemeralStorageSize, props.vpc, undefined, props.architecture)}`;
     this.cr = new cdk.CustomResource(this, crUniqueId, {
       serviceToken: handler.functionArn,
       resourceType: 'Custom::CDKBucketDeployment',
@@ -602,7 +610,13 @@ export class BucketDeployment extends Construct {
     }
   }
 
-  private renderUniqueId(memoryLimit?: number, ephemeralStorageSize?: cdk.Size, vpc?: ec2.IVpc, securityGroups?: ec2.ISecurityGroup[]) {
+  private renderUniqueId(
+    memoryLimit?: number,
+    ephemeralStorageSize?: cdk.Size,
+    vpc?: ec2.IVpc,
+    securityGroups?: ec2.ISecurityGroup[],
+    architecture?: lambda.Architecture,
+  ) {
     let uuid = '';
 
     // if the user specifes a custom memory limit, we define another singleton handler
@@ -646,13 +660,26 @@ export class BucketDeployment extends Construct {
       uuid += `-${sortedSecurityGroupIds}`;
     }
 
+    // if the user specifies an architecture, we define another singleton handler
+    // with this configuration. otherwise, it won't be possible to use multiple
+    // configurations since we have a singleton.
+    if (architecture) {
+      uuid += `-${architecture.name}`;
+    }
+
     return uuid;
   }
 
-  private renderSingletonUuid(memoryLimit?: number, ephemeralStorageSize?: cdk.Size, vpc?: ec2.IVpc, securityGroups?: ec2.ISecurityGroup[]) {
+  private renderSingletonUuid(
+    memoryLimit?: number,
+    ephemeralStorageSize?: cdk.Size,
+    vpc?: ec2.IVpc,
+    securityGroups?: ec2.ISecurityGroup[],
+    architecture?: lambda.Architecture,
+  ) {
     let uuid = '8693BB64-9689-44B6-9AAF-B0CC9EB8756C';
 
-    uuid += this.renderUniqueId(memoryLimit, ephemeralStorageSize, vpc, securityGroups);
+    uuid += this.renderUniqueId(memoryLimit, ephemeralStorageSize, vpc, securityGroups, architecture);
 
     return uuid;
   }

packages/aws-cdk-lib/aws-s3-deployment/test/bucket-deployment.test.ts

@@ -5,6 +5,7 @@ import { Match, Template } from '../../assertions';
 import * as cloudfront from '../../aws-cloudfront';
 import * as ec2 from '../../aws-ec2';
 import * as iam from '../../aws-iam';
+import * as lambda from '../../aws-lambda';
 import * as logs from '../../aws-logs';
 import * as s3 from '../../aws-s3';
 import * as sns from '../../aws-sns';
@@ -1802,3 +1803,96 @@ test('outputObjectKeys default value is true', () => {
     OutputObjectKeys: true,
   });
 });
+
+test('architecture can be used to specify the Lambda architecture', () => {
+  // GIVEN
+  const stack = new cdk.Stack();
+  const bucket = new s3.Bucket(stack, 'Dest');
+
+  // WHEN
+  new s3deploy.BucketDeployment(stack, 'Deploy', {
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+    destinationBucket: bucket,
+    architecture: lambda.Architecture.ARM_64,
+  });
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::Lambda::Function', {
+    Architectures: ['arm64'],
+  });
+});
+
+test('architecture creates separate singleton handlers for different architectures', () => {
+  // GIVEN
+  const stack = new cdk.Stack();
+  const bucket = new s3.Bucket(stack, 'Dest');
+
+  // WHEN
+  new s3deploy.BucketDeployment(stack, 'DeployX86-1', {
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+    destinationBucket: bucket,
+    architecture: lambda.Architecture.X86_64,
+  });
+
+  new s3deploy.BucketDeployment(stack, 'DeployX86-2', {
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+    destinationBucket: bucket,
+    architecture: lambda.Architecture.X86_64,
+  });
+
+  new s3deploy.BucketDeployment(stack, 'DeployARM', {
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+    destinationBucket: bucket,
+    architecture: lambda.Architecture.ARM_64,
+  });
+
+  // THEN - two handlers (one for x86_64, one for arm64)
+  Template.fromStack(stack).resourceCountIs('AWS::Lambda::Function', 2);
+  Template.fromStack(stack).hasResourceProperties('AWS::Lambda::Function', {
+    Architectures: ['x86_64'],
+  });
+  Template.fromStack(stack).hasResourceProperties('AWS::Lambda::Function', {
+    Architectures: ['arm64'],
+  });
+});
+
+test('default architecture does not set Architectures property', () => {
+  // GIVEN
+  const stack = new cdk.Stack();
+  const bucket = new s3.Bucket(stack, 'Dest');
+
+  // WHEN
+  new s3deploy.BucketDeployment(stack, 'Deploy', {
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+    destinationBucket: bucket,
+  });
+
+  // THEN - Architectures is not set (Lambda defaults to x86_64)
+  Template.fromStack(stack).hasResourceProperties('AWS::Lambda::Function', {
+    Architectures: Match.absent(),
+  });
+});
+
+test('architecture combined with memoryLimit creates separate singleton handlers', () => {
+  // GIVEN
+  const stack = new cdk.Stack();
+  const bucket = new s3.Bucket(stack, 'Dest');
+
+  // WHEN
+  new s3deploy.BucketDeployment(stack, 'DeployX86-256', {
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+    destinationBucket: bucket,
+    architecture: lambda.Architecture.X86_64,
+    memoryLimit: 256,
+  });
+
+  new s3deploy.BucketDeployment(stack, 'DeployARM-256', {
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+    destinationBucket: bucket,
+    architecture: lambda.Architecture.ARM_64,
+    memoryLimit: 256,
+  });
+
+  // THEN - same memory but different architecture = different singletons
+  Template.fromStack(stack).resourceCountIs('AWS::Lambda::Function', 2);
+});

packages/aws-cdk-lib/lambda-layer-awscli/lib/awscli-layer.ts

@@ -19,6 +19,7 @@ export class AwsCliLayer extends lambda.LayerVersion {
         assetHash: FileSystem.fingerprint(LAYER_SOURCE_DIR),
       }),
       description: '/opt/awscli/aws',
+      compatibleArchitectures: [lambda.Architecture.X86_64, lambda.Architecture.ARM_64],
     });
   }
 }

packages/aws-cdk-lib/lambda-layer-awscli/test/awscli-layer.test.ts

@@ -14,3 +14,16 @@ test('synthesized to a layer version', () => {
     Description: '/opt/awscli/aws',
   });
 });
+
+test('layer declares compatible architectures', () => {
+  // GIVEN
+  const stack = new Stack();
+
+  // WHEN
+  new AwsCliLayer(stack, 'MyLayer');
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::Lambda::LayerVersion', {
+    CompatibleArchitectures: ['x86_64', 'arm64'],
+  });
+});