(aws-s3-deployment): support for corss-region BucketDeployment similar to S3 Sync

[arbzkhan]

Describe the feature

Currently, while using the 'BucketDeployment' CDK construct[1], which copies files from a source S3 bucket to a destination S3 bucket, works perfectly within the same region. However, when customers need to copy files to a cross-region S3 bucket, they encounter the below error, which is expected because there is no opt-in region property for this construct.

---

"An error occurred (IllegalLocationConstraintException) when calling the ListObjectsV2 operation: The "region-name" location constraint is incompatible for the region specific endpoint this request was sent to."

---

[1] https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeployment.html#destinationbucket

Use Case

To achieve this use-case either customers need to create a stack in specific region itself or need to use "aws s3 sync" CLI command[2].

[2] https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html

Proposed Solution

Add a new optional property 'region' to the BucketDeployment construct to allow users to specify the destination region for cross-region deployments

Other Information

No response

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.161.0

AWS CDK CLI version

2.1019.1

Environment details (OS name and version, etc.)

OSX

[pahud]

Hi @arbzkhan,

Thank you for this feature request! You've identified a limitation in the current BucketDeployment construct.

Current Limitation:
The BucketDeployment construct currently assumes that both source and destination buckets are in the same region as the CDK stack. The underlying Lambda function uses the AWS CLI without region-specific configuration, which causes the IllegalLocationConstraintException when attempting cross-region operations.

Root Cause:
The issue stems from the Lambda handler not being configured to handle cross-region S3 operations. The AWS CLI commands executed by the handler default to the Lambda function's region, which may not match the destination bucket's region.

Proposed Solution:
We should add an optional destinationBucketRegion property to BucketDeploymentProps that allows users to specify the target region for cross-region deployments. This would require:

1. Adding the new property to the construct interface
2. Updating the Lambda handler to use region-specific AWS CLI commands
3. Ensuring proper IAM permissions for cross-region operations

Workaround:
Until this feature is implemented, you can:

1. Deploy your CDK stack in the same region as the destination bucket
2. Use the aws s3 sync CLI command directly as you mentioned
3. Create a custom Lambda function with proper cross-region configuration

This is a valuable enhancement that would benefit many users dealing with multi-region architectures. Would you be interested in contributing a pull request for this feature? The implementation would involve modifying the construct interface and the underlying Lambda handler to support region specification.

The changes would be primarily in:

• packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts
• The custom resource handler for S3 deployment

Let me know if you'd like guidance on implementing this feature!

---

Root Cause Analysis

The root cause lies in the BucketDeployment construct's Lambda function implementation. Looking at the source code:

// From bucket-deployment.ts
const handler = new BucketDeploymentSingletonFunction(this, 'CustomResourceHandler', {
  uuid: this.renderSingletonUuid(props.memoryLimit, props.ephemeralStorageSize, props.vpc),
  layers: [new AwsCliLayer(this, 'AwsCliLayer')],
  environment: {
    ...props.useEfs ? { MOUNT_PATH: mountPath } : undefined,
    AWS_CA_BUNDLE: '/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem',
  },
  // ... other properties
});

The Lambda function uses the AWS CLI layer but doesn't have any mechanism to:

1. Specify the destination region for S3 operations
2. Configure AWS CLI region settings dynamically based on the destination bucket's region
3. Handle cross-region S3 API calls properly

The BucketDeploymentProps interface lacks a region property, and the Lambda handler assumes all operations happen within the same region as the stack deployment.

Possible Fixes/Solutions

The implementation would require several changes:

// 1. Add region property to BucketDeploymentProps interface
export interface BucketDeploymentProps {
  // ... existing properties

  /**
   * The AWS region where the destination bucket is located.
   * This is required for cross-region deployments.
   *
   * @default - Same region as the stack
   */
  readonly destinationBucketRegion?: string;
}

// 2. Pass region information to the Lambda handler
this.cr = new cdk.CustomResource(this, crUniqueId, {
  serviceToken: handler.functionArn,
  resourceType: 'Custom::CDKBucketDeployment',
  properties: {
    // ... existing properties
    DestinationBucketRegion: props.destinationBucketRegion,
  },
});

// 3. Update Lambda handler to use region-specific AWS CLI commands
// The actual Lambda handler would need to:
// - Configure AWS CLI with --region parameter
// - Use region-specific S3 endpoints
// - Handle cross-region IAM permissions

Alternative approaches:

1. Auto-detect region from the destination bucket ARN/properties
2. Support multiple regions in a single deployment
3. Use AWS SDK instead of AWS CLI for better region control