BucketDeployment
BucketDeployment populates an S3 bucket with the contents of .zip files from other S3 buckets or from local disk.
Example
declare const destinationBucket: s3.Bucket;
const deployment = new s3deploy.BucketDeployment(this, 'DeployFiles', {
sources: [s3deploy.Source.asset(path.join(__dirname, 'source-files'))],
destinationBucket,
});
deployment.handlerRole.addToPolicy(
new iam.PolicyStatement({
actions: ['kms:Decrypt', 'kms:DescribeKey'],
effect: iam.Effect.ALLOW,
resources: ['<encryption key ARN>'],
}),
);
# destination_bucket: s3.Bucket
deployment = s3deploy.BucketDeployment(self, "DeployFiles",
sources=[s3deploy.Source.asset(path.join(__dirname, "source-files"))],
destination_bucket=destination_bucket
)
deployment.handler_role.add_to_policy(
iam.PolicyStatement(
actions=["kms:Decrypt", "kms:DescribeKey"],
effect=iam.Effect.ALLOW,
resources=["<encryption key ARN>"]
))
Bucket destinationBucket;
BucketDeployment deployment = BucketDeployment.Builder.create(this, "DeployFiles")
.sources(List.of(Source.asset(join(__dirname, "source-files"))))
.destinationBucket(destinationBucket)
.build();
deployment.handlerRole.addToPolicy(
PolicyStatement.Builder.create()
.actions(List.of("kms:Decrypt", "kms:DescribeKey"))
.effect(Effect.ALLOW)
.resources(List.of("<encryption key ARN>"))
.build());
// Install: dotnet add package Amazon.CDK.Lib
Bucket destinationBucket;
var deployment = new BucketDeployment(this, "DeployFiles", new BucketDeploymentProps {
Sources = new [] { Source.Asset(Join(__dirname, "source-files")) },
DestinationBucket = destinationBucket
});
deployment.HandlerRole.AddToPolicy(
new PolicyStatement(new PolicyStatementProps {
Actions = new [] { "kms:Decrypt", "kms:DescribeKey" },
Effect = Effect.ALLOW,
Resources = new [] { "<encryption key ARN>" }
}));
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
var destinationBucket Bucket
deployment := s3deploy.NewBucketDeployment(this, jsii.String("DeployFiles"), &BucketDeploymentProps{
Sources: []ISource{
s3deploy.Source_Asset(path.join(__dirname, jsii.String("source-files"))),
},
DestinationBucket: DestinationBucket,
})
deployment.HandlerRole.AddToPolicy(
iam.NewPolicyStatement(&PolicyStatementProps{
Actions: []*string{
jsii.String("kms:Decrypt"),
jsii.String("kms:DescribeKey"),
},
Effect: iam.Effect_ALLOW,
Resources: []*string{
jsii.String("<encryption key ARN>"),
},
}))
Initializer
new BucketDeployment(scope: Construct, id: string, props: BucketDeploymentProps)
BucketDeployment(scope: Construct, id: str, props: BucketDeploymentProps)
new BucketDeployment(Construct scope, String id, BucketDeploymentProps props)
new BucketDeployment(Construct scope, string id, BucketDeploymentProps props)
NewBucketDeployment(Scope Construct, Id *string, Props BucketDeploymentProps)
Construct Props
accessControloptionalBucketAccessControlaccess_controloptionalBucketAccessControlaccessControloptionalBucketAccessControlAccessControloptionalBucketAccessControlAccessControloptionalBucketAccessControl#Default: Not set.
cacheControloptionalCacheControl[]cache_controloptionaltyping.List[CacheControl]cacheControloptionalList<CacheControl>CacheControloptionalCacheControl[]CacheControloptional*[]CacheControl#Default: Not set.
contentDispositionoptionalstringcontent_dispositionoptionalstrcontentDispositionoptionalStringContentDispositionoptionalstringContentDispositionoptional*string#Default: Not set.
contentEncodingoptionalstringcontent_encodingoptionalstrcontentEncodingoptionalStringContentEncodingoptionalstringContentEncodingoptional*string#Default: Not set.
contentLanguageoptionalstringcontent_languageoptionalstrcontentLanguageoptionalStringContentLanguageoptionalstringContentLanguageoptional*string#Default: Not set.
contentTypeoptionalstringcontent_typeoptionalstrcontentTypeoptionalStringContentTypeoptionalstringContentTypeoptional*string#Default: Not set.
destinationBucketIBucketdestination_bucketIBucketdestinationBucketIBucketDestinationBucketIBucketDestinationBucketIBucketrequired#destinationKeyPrefixoptionalstringdestination_key_prefixoptionalstrdestinationKeyPrefixoptionalStringDestinationKeyPrefixoptionalstringDestinationKeyPrefixoptional*string#Default: "/" (unzip to root of the destination bucket)
If it's set with prune: true, it will only prune files with the prefix.
We recommend to always configure the destinationKeyPrefix property. This will prevent the deployment from accidentally deleting data that wasn't uploaded by it.
distributionoptionalIDistributionRefdistributionoptionalIDistributionRefdistributionoptionalIDistributionRefDistributionoptionalIDistributionRefDistributionoptionalIDistributionRef#Default: No invalidation occurs
Files in the distribution's edge caches will be invalidated after files are uploaded to the destination bucket.
distributionPathsoptionalstring[]distribution_pathsoptionaltyping.List[str]distributionPathsoptionalList<String>DistributionPathsoptionalstring[]DistributionPathsoptional*[]*string#Default: All files under the destination bucket key prefix will be invalidated.
ephemeralStorageSizeoptionalSizeephemeral_storage_sizeoptionalSizeephemeralStorageSizeoptionalSizeEphemeralStorageSizeoptionalSizeEphemeralStorageSizeoptionalSize#Default: 512 MiB
excludeoptionalstring[]excludeoptionaltyping.List[str]excludeoptionalList<String>Excludeoptionalstring[]Excludeoptional*[]*string#Default: No exclude filters are used
notes
This can be used to exclude a file from being pruned in the destination bucket.
If you want to just exclude files from the deployment package (which excludes these files evaluated when invalidating the asset), you should leverage the exclude property of AssetOptions when defining your source.
expiresoptionalExpirationexpiresoptionalExpirationexpiresoptionalExpirationExpiresoptionalExpirationExpiresoptionalExpiration#Default: The objects in the distribution will not expire.
extractoptionalbooleanextractoptionalboolextractoptionalBooleanExtractoptionalboolExtractoptional*bool= true#If false, the file will remain zipped in the destination bucket.
includeoptionalstring[]includeoptionaltyping.List[str]includeoptionalList<String>Includeoptionalstring[]Includeoptional*[]*string#Default: No include filters are used and all files are included with the sync command
Since all files from the deployment package are included by default, this property is usually leveraged alongside an exclude filter.
logGroupoptionalILogGroupReflog_groupoptionalILogGroupReflogGroupoptionalILogGroupRefLogGroupoptionalILogGroupRefLogGroupoptionalILogGroupRef#Default: a default log group created by AWS Lambda
Providing a user-controlled log group was rolled out to commercial regions on 2023-11-16. If you are deploying to another type of region, please check regional availability first.
logRetentionoptionalRetentionDayslog_retentionoptionalRetentionDayslogRetentionoptionalRetentionDaysLogRetentionoptionalRetentionDaysLogRetentionoptionalRetentionDays= logs.RetentionDays.INFINITE#This is a legacy API and we strongly recommend you migrate to logGroup if you can. logGroup allows you to create a fully customizable log group and instruct the Lambda function to send logs to it.
memoryLimitoptionalnumbermemory_limitoptionalint | floatmemoryLimitoptionalNumberMemoryLimitoptionaldoubleMemoryLimitoptional*float64= 1024#If you are deploying large files, you will need to increase this number accordingly.
metadataoptional{ [key: string]: string }metadataoptionaltyping.Mapping[str, str]metadataoptionalMap<String, String>MetadataoptionalIDictionary<string, string>Metadataoptional*map[string]*string#Default: No user metadata is set
outputObjectKeysoptionalbooleanoutput_object_keysoptionalbooloutputObjectKeysoptionalBooleanOutputObjectKeysoptionalboolOutputObjectKeysoptional*bool= true#This is useful when you are facing the error Response object is too long
If this is set to false, files in the destination bucket that do not exist in the asset, will NOT be deleted during deployment (create/update).
retainOnDeleteoptionalbooleanretain_on_deleteoptionalboolretainOnDeleteoptionalBooleanRetainOnDeleteoptionalboolRetainOnDeleteoptional*bool#Default: true - when resource is deleted/updated, files are retained
NOTICE: Configuring this to "false" might have operational implications. Please visit to the package documentation referred below to make sure you fully understand those implications.
Default: A role is automatically created
securityGroupsoptionalISecurityGroup[]security_groupsoptionaltyping.List[ISecurityGroup]securityGroupsoptionalList<ISecurityGroup>SecurityGroupsoptionalISecurityGroup[]SecurityGroupsoptional*[]ISecurityGroup#Default: undefined - If the function is placed within a VPC and a security group is not specified a dedicated security group will be created for this function.
Only used if 'vpc' is supplied.
serverSideEncryptionoptionalServerSideEncryptionserver_side_encryptionoptionalServerSideEncryptionserverSideEncryptionoptionalServerSideEncryptionServerSideEncryptionoptionalServerSideEncryptionServerSideEncryptionoptionalServerSideEncryption#Default: Server side encryption is not used.
serverSideEncryptionAwsKmsKeyIdoptionalstringserver_side_encryption_aws_kms_key_idoptionalstrserverSideEncryptionAwsKmsKeyIdoptionalStringServerSideEncryptionAwsKmsKeyIdoptionalstringServerSideEncryptionAwsKmsKeyIdoptional*string#Default: Not set.
serverSideEncryptionCustomerAlgorithmoptionalstringserver_side_encryption_customer_algorithmoptionalstrserverSideEncryptionCustomerAlgorithmoptionalStringServerSideEncryptionCustomerAlgorithmoptionalstringServerSideEncryptionCustomerAlgorithmoptional*string#Default: Not set.
Warning: This is not a useful parameter until this bug is fixed: https://github.com/aws/aws-cdk/issues/6080
signContentoptionalbooleansign_contentoptionalboolsignContentoptionalBooleanSignContentoptionalboolSignContentoptional*bool#Default: x-amz-content-sha256 will not be computed
sourcesISource[]sourcestyping.List[ISource]sourcesList<ISource>SourcesISource[]Sources*[]ISourcerequired#storageClassoptionalStorageClassstorage_classoptionalStorageClassstorageClassoptionalStorageClassStorageClassoptionalStorageClassStorageClassoptionalStorageClass#Default: Default storage-class for the bucket is used.
Default: No EFS. Lambda has access only to 512MB of disk space.
Enable this if your assets are large and you encounter disk space errors. Enabling this option will require a VPC to be specified.
This is required if useEfs is set.
vpcSubnetsoptionalSubnetSelectionvpc_subnetsoptionalSubnetSelectionvpcSubnetsoptionalSubnetSelectionVpcSubnetsoptionalSubnetSelectionVpcSubnetsoptionalSubnetSelection#Default: the Vpc default strategy if not specified
Only used if 'vpc' is supplied.
waitForDistributionInvalidationoptionalbooleanwait_for_distribution_invalidationoptionalboolwaitForDistributionInvalidationoptionalBooleanWaitForDistributionInvalidationoptionalboolWaitForDistributionInvalidationoptional*bool= true#This may speed up deployment and avoid intermittent Cloudfront issues. However, this is risky and not recommended as cache invalidation can silently fail.
websiteRedirectLocationoptionalstringwebsite_redirect_locationoptionalstrwebsiteRedirectLocationoptionalStringWebsiteRedirectLocationoptionalstringWebsiteRedirectLocationoptional*string#Default: No website redirection.
Properties
deployedBucketIBucketdeployed_bucketIBucketdeployedBucketIBucketDeployedBucketIBucketDeployedBucketIBucket#notes
If you want to reference the destination bucket in another construct and make sure the bucket deployment has happened before the next operation is started, pass the other construct a reference to deployment.deployedBucket.
Note that this only returns an immutable reference to the destination bucket. If sequenced access to the original destination bucket is required, you may add a dependency on the bucket deployment instead: otherResource.node.addDependency(deployment)
objectKeysstring[]object_keystyping.List[str]objectKeysList<String>ObjectKeysstring[]ObjectKeys*[]*string#notes
This returns a list of tokenized object keys for source files that are deployed to the bucket.
This can be useful when using BucketDeployment with extract set to false and you need to reference the object key that resides in the bucket for that zip source file somewhere else in your CDK application, such as in a CFN output.
For example, use Fn.select(0, myBucketDeployment.objectKeys) to reference the object key of the first source file in your bucket deployment.
objectVersionIdsstring[]object_version_idstyping.List[str]objectVersionIdsList<String>ObjectVersionIdsstring[]ObjectVersionIds*[]*string#notes
Returns a list of tokenized version IDs, positionally matching objectKeys: the version ID at a given index corresponds to the object key at the same index.
This is useful when a consumer must reference a specific, immutable version of a deployed object — for example a Lambda function that references its code in S3 by version rather than copying it.
Requires versioning to be enabled on the destination bucket; otherwise the returned version IDs will be empty strings. Only supported with extract set to false, where each source zip maps 1:1 to a destination object. Reading this accessor with extract set to true (the default) throws. It also requires outputObjectKeys to remain enabled (the default), since the returned list is defined to be positionally aligned with objectKeys; reading it with outputObjectKeys set to false throws.
PROPERTY_INJECTION_IDstringproperty_injection_idstrPROPERTY_INJECTION_IDStringPROPERTY_INJECTION_IDstringPROPERTY_INJECTION_ID*stringstatic#Methods
addSource(source: ISource): voiddef add_source(self, source: ISource) -> Nonepublic void addSource(ISource source)public void AddSource(ISource source)func AddSource(Source ISource)#example
declare const websiteBucket: s3.IBucket;
const deployment = new s3deploy.BucketDeployment(this, 'Deployment', {
sources: [s3deploy.Source.asset('./website-dist')],
destinationBucket: websiteBucket,
});
deployment.addSource(s3deploy.Source.asset('./another-asset'));
isConstruct(x: any): boolean@staticmethod def is_construct(x: Any) -> boolpublic static Boolean isConstruct(Object x)public static bool IsConstruct(object x)func IsConstruct(X interface{}) *boolstatic#notes · 1 parameter · returns
Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.
Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.
Parameters
xxxxX— Any object.
Returns: true if x is an object created from a class which extends Construct.
toString(): stringdef to_string(self, ) -> strpublic String toString()public string ToString()func ToString() *string#with(...mixins: IMixin[]): IConstructdef with(self, mixins: IMixin) -> IConstructpublic IConstruct with(IMixin mixins)public IConstruct With(IMixin mixins)func With(Mixins IMixin) IConstruct#Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.
1 parameter · returns
Parameters
mixinsmixinsmixinsmixinsMixins— The mixins to apply.
Returns: This construct for chaining