awss3deployment

package
v2.93.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 23, 2023 License: Apache-2.0 Imports: 13 Imported by: 11

README

AWS S3 Deployment Construct Library

This library allows populating an S3 bucket with the contents of .zip files from other S3 buckets or from local disk.

The following example defines a publicly accessible S3 bucket with web hosting enabled and populates it from a local directory on disk.

websiteBucket := s3.NewBucket(this, jsii.String("WebsiteBucket"), &BucketProps{
	WebsiteIndexDocument: jsii.String("index.html"),
	PublicReadAccess: jsii.Boolean(true),
})

s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website-dist")),
	},
	DestinationBucket: websiteBucket,
	DestinationKeyPrefix: jsii.String("web/static"),
})

This is what happens under the hood:

  1. When this stack is deployed (either via cdk deploy or via CI/CD), the contents of the local website-dist directory will be archived and uploaded to an intermediary assets bucket. If there is more than one source, they will be individually uploaded.
  2. The BucketDeployment construct synthesizes a custom CloudFormation resource of type Custom::CDKBucketDeployment into the template. The source bucket/key is set to point to the assets bucket.
  3. The custom resource downloads the .zip archive, extracts it and issues aws s3 sync --delete against the destination bucket (in this case websiteBucket). If there is more than one source, the sources will be downloaded and merged pre-deployment at this step.

If you are referencing the filled bucket in another construct that depends on the files already be there, be sure to use deployment.deployedBucket. This will ensure the bucket deployment has finished before the resource that uses the bucket is created:

var websiteBucket bucket


deployment := s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: websiteBucket,
})

NewConstructThatReadsFromTheBucket(this, jsii.String("Consumer"), map[string]iBucket{
	// Use 'deployment.deployedBucket' instead of 'websiteBucket' here
	"bucket": deployment.deployedBucket,
})

It is also possible to add additional sources using the addSource method.

var websiteBucket iBucket


deployment := s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website-dist")),
	},
	DestinationBucket: websiteBucket,
	DestinationKeyPrefix: jsii.String("web/static"),
})

deployment.AddSource(s3deploy.Source_Asset(jsii.String("./another-asset")))

Supported sources

The following source types are supported for bucket deployments:

  • Local .zip file: s3deploy.Source.asset('/path/to/local/file.zip')
  • Local directory: s3deploy.Source.asset('/path/to/local/directory')
  • Another bucket: s3deploy.Source.bucket(bucket, zipObjectKey)
  • String data: s3deploy.Source.data('object-key.txt', 'hello, world!') (supports deploy-time values)
  • JSON data: s3deploy.Source.jsonData('object-key.json', { json: 'object' }) (supports deploy-time values)
  • YAML data: s3deploy.Source.yamlData('object-key.yaml', { yaml: 'object' }) (supports deploy-time values)

To create a source from a single file, you can pass AssetOptions to exclude all but a single file:

  • Single file: s3deploy.Source.asset('/path/to/local/directory', { exclude: ['**', '!onlyThisFile.txt'] })

IMPORTANT The aws-s3-deployment module is only intended to be used with zip files from trusted sources. Directories bundled by the CDK CLI (by using Source.asset() on a directory) are safe. If you are using Source.asset() or Source.bucket() to reference an existing zip file, make sure you trust the file you are referencing. Zips from untrusted sources might be able to execute arbitrary code in the Lambda Function used by this module, and use its permissions to read or write unexpected files in the S3 bucket.

Retain on Delete

By default, the contents of the destination bucket will not be deleted when the BucketDeployment resource is removed from the stack or when the destination is changed. You can use the option retainOnDelete: false to disable this behavior, in which case the contents will be deleted.

Configuring this has a few implications you should be aware of:

  • Logical ID Changes

    Changing the logical ID of the BucketDeployment construct, without changing the destination (for example due to refactoring, or intentional ID change) will result in the deletion of the objects. This is because CloudFormation will first create the new resource, which will have no affect, followed by a deletion of the old resource, which will cause a deletion of the objects, since the destination hasn't changed, and retainOnDelete is false.

  • Destination Changes

    When the destination bucket or prefix is changed, all files in the previous destination will first be deleted and then uploaded to the new destination location. This could have availability implications on your users.

General Recommendations
Shared Bucket

If the destination bucket is not dedicated to the specific BucketDeployment construct (i.e shared by other entities), we recommend to always configure the destinationKeyPrefix property. This will prevent the deployment from accidentally deleting data that wasn't uploaded by it.

Dedicated Bucket

If the destination bucket is dedicated, it might be reasonable to skip the prefix configuration, in which case, we recommend to remove retainOnDelete: false, and instead, configure the autoDeleteObjects property on the destination bucket. This will avoid the logical ID problem mentioned above.

Prune

By default, files in the destination bucket that don't exist in the source will be deleted when the BucketDeployment resource is created or updated. You can use the option prune: false to disable this behavior, in which case the files will not be deleted.

var destinationBucket bucket

s3deploy.NewBucketDeployment(this, jsii.String("DeployMeWithoutDeletingFilesOnDestination"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: DestinationBucket,
	Prune: jsii.Boolean(false),
})

This option also enables you to multiple bucket deployments for the same destination bucket & prefix, each with its own characteristics. For example, you can set different cache-control headers based on file extensions:

var destinationBucket bucket

s3deploy.NewBucketDeployment(this, jsii.String("BucketDeployment"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website"), &AssetOptions{
			Exclude: []*string{
				jsii.String("index.html"),
			},
		}),
	},
	DestinationBucket: DestinationBucket,
	CacheControl: []cacheControl{
		s3deploy.*cacheControl_MaxAge(awscdk.Duration_Days(jsii.Number(365))),
		s3deploy.*cacheControl_Immutable(),
	},
	Prune: jsii.Boolean(false),
})

s3deploy.NewBucketDeployment(this, jsii.String("HTMLBucketDeployment"), &BucketDeploymentProps{
	Sources: []*iSource{
		s3deploy.Source_*Asset(jsii.String("./website"), &AssetOptions{
			Exclude: []*string{
				jsii.String("*"),
				jsii.String("!index.html"),
			},
		}),
	},
	DestinationBucket: DestinationBucket,
	CacheControl: []*cacheControl{
		s3deploy.*cacheControl_*MaxAge(awscdk.Duration_Seconds(jsii.Number(0))),
	},
	Prune: jsii.Boolean(false),
})

Exclude and Include Filters

There are two points at which filters are evaluated in a deployment: asset bundling and the actual deployment. If you simply want to exclude files in the asset bundling process, you should leverage the exclude property of AssetOptions when defining your source:

var destinationBucket bucket

s3deploy.NewBucketDeployment(this, jsii.String("HTMLBucketDeployment"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website"), &AssetOptions{
			Exclude: []*string{
				jsii.String("*"),
				jsii.String("!index.html"),
			},
		}),
	},
	DestinationBucket: DestinationBucket,
})

If you want to specify filters to be used in the deployment process, you can use the exclude and include filters on BucketDeployment. If excluded, these files will not be deployed to the destination bucket. In addition, if the file already exists in the destination bucket, it will not be deleted if you are using the prune option:

var destinationBucket bucket

s3deploy.NewBucketDeployment(this, jsii.String("DeployButExcludeSpecificFiles"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: DestinationBucket,
	Exclude: []*string{
		jsii.String("*.txt"),
	},
})

These filters follow the same format that is used for the AWS CLI. See the CLI documentation for information on Using Include and Exclude Filters.

Objects metadata

You can specify metadata to be set on all the objects in your deployment. There are 2 types of metadata in S3: system-defined metadata and user-defined metadata. System-defined metadata have a special purpose, for example cache-control defines how long to keep an object cached. User-defined metadata are not used by S3 and keys always begin with x-amz-meta- (this prefix is added automatically).

System defined metadata keys include the following:

  • cache-control (--cache-control in aws s3 sync)
  • content-disposition (--content-disposition in aws s3 sync)
  • content-encoding (--content-encoding in aws s3 sync)
  • content-language (--content-language in aws s3 sync)
  • content-type (--content-type in aws s3 sync)
  • expires (--expires in aws s3 sync)
  • x-amz-storage-class (--storage-class in aws s3 sync)
  • x-amz-website-redirect-location (--website-redirect in aws s3 sync)
  • x-amz-server-side-encryption (--sse in aws s3 sync)
  • x-amz-server-side-encryption-aws-kms-key-id (--sse-kms-key-id in aws s3 sync)
  • x-amz-server-side-encryption-customer-algorithm (--sse-c-copy-source in aws s3 sync)
  • x-amz-acl (--acl in aws s3 sync)

You can find more information about system defined metadata keys in S3 PutObject documentation and aws s3 sync documentation.

websiteBucket := s3.NewBucket(this, jsii.String("WebsiteBucket"), &BucketProps{
	WebsiteIndexDocument: jsii.String("index.html"),
	PublicReadAccess: jsii.Boolean(true),
})

s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website-dist")),
	},
	DestinationBucket: websiteBucket,
	DestinationKeyPrefix: jsii.String("web/static"),
	 // optional prefix in destination bucket
	Metadata: map[string]*string{
		"A": jsii.String("1"),
		"b": jsii.String("2"),
	},
	 // user-defined metadata

	// system-defined metadata
	ContentType: jsii.String("text/html"),
	ContentLanguage: jsii.String("en"),
	StorageClass: s3deploy.StorageClass_INTELLIGENT_TIERING,
	ServerSideEncryption: s3deploy.ServerSideEncryption_AES_256,
	CacheControl: []cacheControl{
		s3deploy.*cacheControl_SetPublic(),
		s3deploy.*cacheControl_MaxAge(awscdk.Duration_Hours(jsii.Number(1))),
	},
	AccessControl: s3.BucketAccessControl_BUCKET_OWNER_FULL_CONTROL,
})

CloudFront Invalidation

You can provide a CloudFront distribution and optional paths to invalidate after the bucket deployment finishes.

import cloudfront "github.com/aws/aws-cdk-go/awscdk"
import origins "github.com/aws/aws-cdk-go/awscdk"


bucket := s3.NewBucket(this, jsii.String("Destination"))

// Handles buckets whether or not they are configured for website hosting.
distribution := cloudfront.NewDistribution(this, jsii.String("Distribution"), &DistributionProps{
	DefaultBehavior: &BehaviorOptions{
		Origin: origins.NewS3Origin(bucket),
	},
})

s3deploy.NewBucketDeployment(this, jsii.String("DeployWithInvalidation"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website-dist")),
	},
	DestinationBucket: bucket,
	Distribution: Distribution,
	DistributionPaths: []*string{
		jsii.String("/images/*.png"),
	},
})

Signed Content Payloads

By default, deployment uses streaming uploads which set the x-amz-content-sha256 request header to UNSIGNED-PAYLOAD (matching default behavior of the AWS CLI tool). In cases where bucket policy restrictions require signed content payloads, you can enable generation of a signed x-amz-content-sha256 request header with signContent: true.

var bucket iBucket


s3deploy.NewBucketDeployment(this, jsii.String("DeployWithSignedPayloads"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website-dist")),
	},
	DestinationBucket: bucket,
	SignContent: jsii.Boolean(true),
})

Size Limits

The default memory limit for the deployment resource is 128MiB. If you need to copy larger files, you can use the memoryLimit configuration to increase the size of the AWS Lambda resource handler.

The default ephemeral storage size for the deployment resource is 512MiB. If you need to upload larger files, you may hit this limit. You can use the ephemeralStorageSize configuration to increase the storage size of the AWS Lambda resource handler.

NOTE: a new AWS Lambda handler will be created in your stack for each combination of memory and storage size.

EFS Support

If your workflow needs more disk space than default (512 MB) disk space, you may attach an EFS storage to underlying lambda function. To Enable EFS support set efs and vpc props for BucketDeployment.

Check sample usage below. Please note that creating VPC inline may cause stack deletion failures. It is shown as below for simplicity. To avoid such condition, keep your network infra (VPC) in a separate stack and pass as props.

var destinationBucket bucket
var vpc vpc


s3deploy.NewBucketDeployment(this, jsii.String("DeployMeWithEfsStorage"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: DestinationBucket,
	DestinationKeyPrefix: jsii.String("efs/"),
	UseEfs: jsii.Boolean(true),
	Vpc: Vpc,
	RetainOnDelete: jsii.Boolean(false),
})

Data with deploy-time values

The content passed to Source.data(), Source.jsonData(), or Source.yamlData() can include references that will get resolved only during deployment.

For example:

import sns "github.com/aws/aws-cdk-go/awscdk"

var destinationBucket bucket
var topic topic


appConfig := map[string]interface{}{
	"topic_arn": topic.topicArn,
	"base_url": jsii.String("https://my-endpoint"),
}

s3deploy.NewBucketDeployment(this, jsii.String("BucketDeployment"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_JsonData(jsii.String("config.json"), appConfig),
	},
	DestinationBucket: DestinationBucket,
})

The value in topic.topicArn is a deploy-time value. It only gets resolved during deployment by placing a marker in the generated source file and substituting it when its deployed to the destination with the actual value.

Substitutions from Templated Files

The DeployTimeSubstitutedFile construct allows you to specify substitutions to make from placeholders in a local file which will be resolved during deployment. This is especially useful in situations like creating an API from a spec file, where users might want to reference other CDK resources they have created.

The syntax for template variables is {{ variableName }} in your local file. Then, you would specify the substitutions in CDK like this:

import lambda "github.com/aws/aws-cdk-go/awscdk"

var myLambdaFunction function
var destinationBucket bucket


s3deploy.NewDeployTimeSubstitutedFile(this, jsii.String("MyFile"), &DeployTimeSubstitutedFileProps{
	Source: jsii.String("my-file.yaml"),
	DestinationBucket: destinationBucket,
	Substitutions: map[string]*string{
		"variableName": myLambdaFunction.functionName,
	},
})

Nested variables, like {{ {{ foo }} }} or {{ foo {{ bar }} }}, are not supported by this construct. In the first case of a single variable being is double nested {{ {{ foo }} }}, only the {{ foo }} would be replaced by the substitution, and the extra brackets would remain in the file. In the second case of two nexted variables {{ foo {{ bar }} }}, only the {{ bar }} would be replaced in the file.

Keep Files Zipped

By default, files are zipped, then extracted into the destination bucket.

You can use the option extract: false to disable this behavior, in which case, files will remain in a zip file when deployed to S3. To reference the object keys, or filenames, which will be deployed to the bucket, you can use the objectKeys getter on the bucket deployment.

import "github.com/aws/aws-cdk-go/awscdk"

var destinationBucket bucket


myBucketDeployment := s3deploy.NewBucketDeployment(this, jsii.String("DeployMeWithoutExtractingFilesOnDestination"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: DestinationBucket,
	Extract: jsii.Boolean(false),
})

cdk.NewCfnOutput(this, jsii.String("ObjectKey"), &CfnOutputProps{
	Value: cdk.Fn_Select(jsii.Number(0), myBucketDeployment.objectKeys),
})

Notes

  • This library uses an AWS CloudFormation custom resource which is about 10MiB in size. The code of this resource is bundled with this library.

  • AWS Lambda execution time is limited to 15min. This limits the amount of data which can be deployed into the bucket by this timeout.

  • When the BucketDeployment is removed from the stack, the contents are retained in the destination bucket (#952).

  • If you are using s3deploy.Source.bucket() to take the file source from another bucket: the deployed files will only be updated if the key (file name) of the file in the source bucket changes. Mutating the file in place will not be good enough: the custom resource will simply not run if the properties don't change.

    • If you use assets (s3deploy.Source.asset()) you don't need to worry about this: the asset system will make sure that if the files have changed, the file name is unique and the deployment will run.

Development

The custom resource is implemented in Python 3.9 in order to be able to leverage the AWS CLI for "aws s3 sync". The code is under lib/lambda and unit tests are under test/lambda.

This package requires Python 3.9 during build time in order to create the custom resource Lambda bundle and test it. It also relies on a few bash scripts, so might be tricky to build on Windows.

Roadmap

  • Support "blue/green" deployments (#954)

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BucketDeployment_IsConstruct 

func BucketDeployment_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

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.

Returns: true if `x` is an object created from a class which extends `Construct`.

func DeployTimeSubstitutedFile_IsConstruct added in v2.85.0 

func DeployTimeSubstitutedFile_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

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.

Returns: true if `x` is an object created from a class which extends `Construct`.

func NewBucketDeployment_Override 

func NewBucketDeployment_Override(b BucketDeployment, scope constructs.Construct, id *string, props *BucketDeploymentProps)

func NewDeployTimeSubstitutedFile_Override added in v2.85.0 

func NewDeployTimeSubstitutedFile_Override(d DeployTimeSubstitutedFile, scope constructs.Construct, id *string, props *DeployTimeSubstitutedFileProps)

Types

type BucketDeployment 

type BucketDeployment interface {
	constructs.Construct
	// The bucket after the deployment.
	//
	// 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)`
	DeployedBucket() awss3.IBucket
	// The tree node.
	Node() constructs.Node
	// The object keys for the sources deployed to the S3 bucket.
	//
	// 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.
	ObjectKeys() *[]*string
	// Add an additional source to the bucket deployment.
	//
	// Example:
	//   var websiteBucket iBucket
	//
	//   deployment := s3deploy.NewBucketDeployment(this, jsii.String("Deployment"), &BucketDeploymentProps{
	//   	Sources: []iSource{
	//   		s3deploy.Source_Asset(jsii.String("./website-dist")),
	//   	},
	//   	DestinationBucket: websiteBucket,
	//   })
	//
	//   deployment.AddSource(s3deploy.Source_Asset(jsii.String("./another-asset")))
	//
	AddSource(source ISource)
	// Returns a string representation of this construct.
	ToString() *string
}

`BucketDeployment` populates an S3 bucket with the contents of .zip files from other S3 buckets or from local disk.

Example: 

var websiteBucket bucket

deployment := s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: websiteBucket,
})

NewConstructThatReadsFromTheBucket(this, jsii.String("Consumer"), map[string]iBucket{
	// Use 'deployment.deployedBucket' instead of 'websiteBucket' here
	"bucket": deployment.deployedBucket,
})

func NewBucketDeployment 

func NewBucketDeployment(scope constructs.Construct, id *string, props *BucketDeploymentProps) BucketDeployment

type BucketDeploymentProps 

type BucketDeploymentProps struct {
	// The S3 bucket to sync the contents of the zip file to.
	DestinationBucket awss3.IBucket `field:"required" json:"destinationBucket" yaml:"destinationBucket"`
	// The sources from which to deploy the contents of this bucket.
	Sources *[]ISource `field:"required" json:"sources" yaml:"sources"`
	// System-defined x-amz-acl metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl
	//
	// Default: - Not set.
	//
	AccessControl awss3.BucketAccessControl `field:"optional" json:"accessControl" yaml:"accessControl"`
	// System-defined cache-control metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Not set.
	//
	CacheControl *[]CacheControl `field:"optional" json:"cacheControl" yaml:"cacheControl"`
	// System-defined cache-disposition metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Not set.
	//
	ContentDisposition *string `field:"optional" json:"contentDisposition" yaml:"contentDisposition"`
	// System-defined content-encoding metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Not set.
	//
	ContentEncoding *string `field:"optional" json:"contentEncoding" yaml:"contentEncoding"`
	// System-defined content-language metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Not set.
	//
	ContentLanguage *string `field:"optional" json:"contentLanguage" yaml:"contentLanguage"`
	// System-defined content-type metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Not set.
	//
	ContentType *string `field:"optional" json:"contentType" yaml:"contentType"`
	// Key prefix in the destination bucket.
	//
	// Must be <=104 characters.
	// Default: "/" (unzip to root of the destination bucket).
	//
	DestinationKeyPrefix *string `field:"optional" json:"destinationKeyPrefix" yaml:"destinationKeyPrefix"`
	// The CloudFront distribution using the destination bucket as an origin.
	//
	// Files in the distribution's edge caches will be invalidated after
	// files are uploaded to the destination bucket.
	// Default: - No invalidation occurs.
	//
	Distribution awscloudfront.IDistribution `field:"optional" json:"distribution" yaml:"distribution"`
	// The file paths to invalidate in the CloudFront distribution.
	// Default: - All files under the destination bucket key prefix will be invalidated.
	//
	DistributionPaths *[]*string `field:"optional" json:"distributionPaths" yaml:"distributionPaths"`
	// The size of the AWS Lambda function’s /tmp directory in MiB.
	// Default: 512 MiB.
	//
	EphemeralStorageSize awscdk.Size `field:"optional" json:"ephemeralStorageSize" yaml:"ephemeralStorageSize"`
	// If this is set, matching files or objects will be excluded from the deployment's sync command.
	//
	// 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.
	// See: https://docs.aws.amazon.com/cli/latest/reference/s3/index.html#use-of-exclude-and-include-filters
	//
	// Default: - No exclude filters are used.
	//
	Exclude *[]*string `field:"optional" json:"exclude" yaml:"exclude"`
	// System-defined expires metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - The objects in the distribution will not expire.
	//
	Expires awscdk.Expiration `field:"optional" json:"expires" yaml:"expires"`
	// If this is set, the zip file will be synced to the destination S3 bucket and extracted.
	//
	// If false, the file will remain zipped in the destination bucket.
	// Default: true.
	//
	Extract *bool `field:"optional" json:"extract" yaml:"extract"`
	// If this is set, matching files or objects will be included with the deployment's sync command.
	//
	// Since all files from the deployment package are included by default, this property
	// is usually leveraged alongside an `exclude` filter.
	// See: https://docs.aws.amazon.com/cli/latest/reference/s3/index.html#use-of-exclude-and-include-filters
	//
	// Default: - No include filters are used and all files are included with the sync command.
	//
	Include *[]*string `field:"optional" json:"include" yaml:"include"`
	// The number of days that the lambda function's log events are kept in CloudWatch Logs.
	// Default: logs.RetentionDays.INFINITE
	//
	LogRetention awslogs.RetentionDays `field:"optional" json:"logRetention" yaml:"logRetention"`
	// The amount of memory (in MiB) to allocate to the AWS Lambda function which replicates the files from the CDK bucket to the destination bucket.
	//
	// If you are deploying large files, you will need to increase this number
	// accordingly.
	// Default: 128.
	//
	MemoryLimit *float64 `field:"optional" json:"memoryLimit" yaml:"memoryLimit"`
	// User-defined object metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#UserMetadata
	//
	// Default: - No user metadata is set.
	//
	Metadata *map[string]*string `field:"optional" json:"metadata" yaml:"metadata"`
	// 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).
	// See: https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html
	//
	// Default: true.
	//
	Prune *bool `field:"optional" json:"prune" yaml:"prune"`
	// If this is set to "false", the destination files will be deleted when the resource is deleted or the destination is updated.
	//
	// 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.
	// See: https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/aws-s3-deployment#retain-on-delete
	//
	// Default: true - when resource is deleted/updated, files are retained.
	//
	RetainOnDelete *bool `field:"optional" json:"retainOnDelete" yaml:"retainOnDelete"`
	// Execution role associated with this function.
	// Default: - A role is automatically created.
	//
	Role awsiam.IRole `field:"optional" json:"role" yaml:"role"`
	// System-defined x-amz-server-side-encryption metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Server side encryption is not used.
	//
	ServerSideEncryption ServerSideEncryption `field:"optional" json:"serverSideEncryption" yaml:"serverSideEncryption"`
	// System-defined x-amz-server-side-encryption-aws-kms-key-id metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Not set.
	//
	ServerSideEncryptionAwsKmsKeyId *string `field:"optional" json:"serverSideEncryptionAwsKmsKeyId" yaml:"serverSideEncryptionAwsKmsKeyId"`
	// System-defined x-amz-server-side-encryption-customer-algorithm metadata to be set on all objects in the deployment.
	//
	// Warning: This is not a useful parameter until this bug is fixed: https://github.com/aws/aws-cdk/issues/6080
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/ServerSideEncryptionCustomerKeys.html#sse-c-how-to-programmatically-intro
	//
	// Default: - Not set.
	//
	ServerSideEncryptionCustomerAlgorithm *string `field:"optional" json:"serverSideEncryptionCustomerAlgorithm" yaml:"serverSideEncryptionCustomerAlgorithm"`
	// If set to true, uploads will precompute the value of `x-amz-content-sha256` and include it in the signed S3 request headers.
	// Default: - `x-amz-content-sha256` will not be computed.
	//
	SignContent *bool `field:"optional" json:"signContent" yaml:"signContent"`
	// System-defined x-amz-storage-class metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - Default storage-class for the bucket is used.
	//
	StorageClass StorageClass `field:"optional" json:"storageClass" yaml:"storageClass"`
	// Mount an EFS file system.
	//
	// Enable this if your assets are large and you encounter disk space errors.
	// Enabling this option will require a VPC to be specified.
	// Default: - No EFS. Lambda has access only to 512MB of disk space.
	//
	UseEfs *bool `field:"optional" json:"useEfs" yaml:"useEfs"`
	// The VPC network to place the deployment lambda handler in.
	//
	// This is required if `useEfs` is set.
	// Default: None.
	//
	Vpc awsec2.IVpc `field:"optional" json:"vpc" yaml:"vpc"`
	// Where in the VPC to place the deployment lambda handler.
	//
	// Only used if 'vpc' is supplied.
	// Default: - the Vpc default strategy if not specified.
	//
	VpcSubnets *awsec2.SubnetSelection `field:"optional" json:"vpcSubnets" yaml:"vpcSubnets"`
	// System-defined x-amz-website-redirect-location metadata to be set on all objects in the deployment.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata
	//
	// Default: - No website redirection.
	//
	WebsiteRedirectLocation *string `field:"optional" json:"websiteRedirectLocation" yaml:"websiteRedirectLocation"`
}

Properties for `BucketDeployment`.

Example: 

var websiteBucket bucket

deployment := s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: websiteBucket,
})

NewConstructThatReadsFromTheBucket(this, jsii.String("Consumer"), map[string]iBucket{
	// Use 'deployment.deployedBucket' instead of 'websiteBucket' here
	"bucket": deployment.deployedBucket,
})

type CacheControl 

type CacheControl interface {
	// The raw cache control setting.
	Value() interface{}
}

Used for HTTP cache-control header, which influences downstream caches.

Example: 

var destinationBucket bucket

s3deploy.NewBucketDeployment(this, jsii.String("BucketDeployment"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website"), &AssetOptions{
			Exclude: []*string{
				jsii.String("index.html"),
			},
		}),
	},
	DestinationBucket: DestinationBucket,
	CacheControl: []cacheControl{
		s3deploy.*cacheControl_MaxAge(awscdk.Duration_Days(jsii.Number(365))),
		s3deploy.*cacheControl_Immutable(),
	},
	Prune: jsii.Boolean(false),
})

s3deploy.NewBucketDeployment(this, jsii.String("HTMLBucketDeployment"), &BucketDeploymentProps{
	Sources: []*iSource{
		s3deploy.Source_*Asset(jsii.String("./website"), &AssetOptions{
			Exclude: []*string{
				jsii.String("*"),
				jsii.String("!index.html"),
			},
		}),
	},
	DestinationBucket: DestinationBucket,
	CacheControl: []*cacheControl{
		s3deploy.*cacheControl_*MaxAge(awscdk.Duration_Seconds(jsii.Number(0))),
	},
	Prune: jsii.Boolean(false),
})

See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata

func CacheControl_FromString 

func CacheControl_FromString(s *string) CacheControl

Constructs a custom cache control key from the literal value.

func CacheControl_Immutable added in v2.81.0 

func CacheControl_Immutable() CacheControl

Sets 'immutable'.

func CacheControl_MaxAge 

func CacheControl_MaxAge(t awscdk.Duration) CacheControl

Sets 'max-age=<duration-in-seconds>'.

func CacheControl_MustRevalidate 

func CacheControl_MustRevalidate() CacheControl

Sets 'must-revalidate'.

func CacheControl_MustUnderstand added in v2.81.0 

func CacheControl_MustUnderstand() CacheControl

Sets 'must-understand'.

func CacheControl_NoCache 

func CacheControl_NoCache() CacheControl

Sets 'no-cache'.

func CacheControl_NoStore added in v2.81.0 

func CacheControl_NoStore() CacheControl

Sets 'no-store'.

func CacheControl_NoTransform 

func CacheControl_NoTransform() CacheControl

Sets 'no-transform'.

func CacheControl_ProxyRevalidate 

func CacheControl_ProxyRevalidate() CacheControl

Sets 'proxy-revalidate'.

func CacheControl_SMaxAge 

func CacheControl_SMaxAge(t awscdk.Duration) CacheControl

Sets 's-maxage=<duration-in-seconds>'.

func CacheControl_SetPrivate 

func CacheControl_SetPrivate() CacheControl

Sets 'private'.

func CacheControl_SetPublic 

func CacheControl_SetPublic() CacheControl

Sets 'public'.

func CacheControl_StaleIfError added in v2.81.0 

func CacheControl_StaleIfError(t awscdk.Duration) CacheControl

Sets 'stale-if-error=<duration-in-seconds>'.

func CacheControl_StaleWhileRevalidate added in v2.81.0 

func CacheControl_StaleWhileRevalidate(t awscdk.Duration) CacheControl

Sets 'stale-while-revalidate=<duration-in-seconds>'.

type DeployTimeSubstitutedFile added in v2.85.0 

type DeployTimeSubstitutedFile interface {
	BucketDeployment
	Bucket() awss3.IBucket
	// The bucket after the deployment.
	//
	// 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)`
	DeployedBucket() awss3.IBucket
	// The tree node.
	Node() constructs.Node
	ObjectKey() *string
	// The object keys for the sources deployed to the S3 bucket.
	//
	// 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.
	ObjectKeys() *[]*string
	// Add an additional source to the bucket deployment.
	//
	// 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'));
	//
	AddSource(source ISource)
	// Returns a string representation of this construct.
	ToString() *string
}

`DeployTimeSubstitutedFile` is an extension of `BucketDeployment` that allows users to upload individual files and specify to make substitutions in the file.

Example: 

import lambda "github.com/aws/aws-cdk-go/awscdk"

var myLambdaFunction function
var destinationBucket bucket

s3deploy.NewDeployTimeSubstitutedFile(this, jsii.String("MyFile"), &DeployTimeSubstitutedFileProps{
	Source: jsii.String("my-file.yaml"),
	DestinationBucket: destinationBucket,
	Substitutions: map[string]*string{
		"variableName": myLambdaFunction.functionName,
	},
})

func NewDeployTimeSubstitutedFile added in v2.85.0 

func NewDeployTimeSubstitutedFile(scope constructs.Construct, id *string, props *DeployTimeSubstitutedFileProps) DeployTimeSubstitutedFile

type DeployTimeSubstitutedFileProps added in v2.85.0 

type DeployTimeSubstitutedFileProps struct {
	// The S3 bucket to sync the contents of the zip file to.
	DestinationBucket awss3.IBucket `field:"required" json:"destinationBucket" yaml:"destinationBucket"`
	// Path to the user's local file.
	Source *string `field:"required" json:"source" yaml:"source"`
	// User-defined substitutions to make in the file.
	//
	// Placeholders in the user's local file must be specified with double curly
	// brackets and spaces. For example, if you use the key 'xxxx' in the file,
	// it must be written as: {{ xxxx }} to be recognized by the construct as a
	// substitution.
	Substitutions *map[string]*string `field:"required" json:"substitutions" yaml:"substitutions"`
}

Example: 

import lambda "github.com/aws/aws-cdk-go/awscdk"

var myLambdaFunction function
var destinationBucket bucket

s3deploy.NewDeployTimeSubstitutedFile(this, jsii.String("MyFile"), &DeployTimeSubstitutedFileProps{
	Source: jsii.String("my-file.yaml"),
	DestinationBucket: destinationBucket,
	Substitutions: map[string]*string{
		"variableName": myLambdaFunction.functionName,
	},
})

type DeploymentSourceContext 

type DeploymentSourceContext struct {
	// The role for the handler.
	HandlerRole awsiam.IRole `field:"required" json:"handlerRole" yaml:"handlerRole"`
}

Bind context for ISources.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

var role role

deploymentSourceContext := &DeploymentSourceContext{
	HandlerRole: role,
}

type ISource 

type ISource interface {
	// Binds the source to a bucket deployment.
	Bind(scope constructs.Construct, context *DeploymentSourceContext) *SourceConfig
}

Represents a source for bucket deployments.

func Source_Asset 

func Source_Asset(path *string, options *awss3assets.AssetOptions) ISource

Uses a local asset as the deployment source.

If the local asset is a .zip archive, make sure you trust the producer of the archive.

func Source_Bucket 

func Source_Bucket(bucket awss3.IBucket, zipObjectKey *string) ISource

Uses a .zip file stored in an S3 bucket as the source for the destination bucket contents.

Make sure you trust the producer of the archive.

func Source_Data added in v2.11.0 

func Source_Data(objectKey *string, data *string) ISource

Deploys an object with the specified string contents into the bucket.

The content can include deploy-time values (such as `snsTopic.topicArn`) that will get resolved only during deployment.

To store a JSON object use `Source.jsonData()`. To store YAML content use `Source.yamlData()`.

func Source_JsonData added in v2.11.0 

func Source_JsonData(objectKey *string, obj interface{}) ISource

Deploys an object with the specified JSON object into the bucket.

The object can include deploy-time values (such as `snsTopic.topicArn`) that will get resolved only during deployment.

func Source_YamlData added in v2.72.0 

func Source_YamlData(objectKey *string, obj interface{}) ISource

Deploys an object with the specified JSON object formatted as YAML into the bucket.

The object can include deploy-time values (such as `snsTopic.topicArn`) that will get resolved only during deployment.

type ServerSideEncryption 

type ServerSideEncryption string

Indicates whether server-side encryption is enabled for the object, and whether that encryption is from the AWS Key Management Service (AWS KMS) or from Amazon S3 managed encryption (SSE-S3).

Example: 

websiteBucket := s3.NewBucket(this, jsii.String("WebsiteBucket"), &BucketProps{
	WebsiteIndexDocument: jsii.String("index.html"),
	PublicReadAccess: jsii.Boolean(true),
})

s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website-dist")),
	},
	DestinationBucket: websiteBucket,
	DestinationKeyPrefix: jsii.String("web/static"),
	 // optional prefix in destination bucket
	Metadata: map[string]*string{
		"A": jsii.String("1"),
		"b": jsii.String("2"),
	},
	 // user-defined metadata

	// system-defined metadata
	ContentType: jsii.String("text/html"),
	ContentLanguage: jsii.String("en"),
	StorageClass: s3deploy.StorageClass_INTELLIGENT_TIERING,
	ServerSideEncryption: s3deploy.ServerSideEncryption_AES_256,
	CacheControl: []cacheControl{
		s3deploy.*cacheControl_SetPublic(),
		s3deploy.*cacheControl_MaxAge(awscdk.Duration_Hours(jsii.Number(1))),
	},
	AccessControl: s3.BucketAccessControl_BUCKET_OWNER_FULL_CONTROL,
})

See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata 

const (
	// 'AES256'.
	ServerSideEncryption_AES_256 ServerSideEncryption = "AES_256"
	// 'aws:kms'.
	ServerSideEncryption_AWS_KMS ServerSideEncryption = "AWS_KMS"
)

type Source 

type Source interface {
}

Specifies bucket deployment source.

Usage: 

Source.bucket(bucket, key)
Source.asset('/local/path/to/directory')
Source.asset('/local/path/to/a/file.zip')
Source.data('hello/world/file.txt', 'Hello, world!')
Source.dataJson('config.json', { baz: topic.topicArn })
Source.dataYaml('config.yaml', { baz: topic.topicArn })

Example: 

var websiteBucket bucket

deployment := s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(path.join(__dirname, jsii.String("my-website"))),
	},
	DestinationBucket: websiteBucket,
})

NewConstructThatReadsFromTheBucket(this, jsii.String("Consumer"), map[string]iBucket{
	// Use 'deployment.deployedBucket' instead of 'websiteBucket' here
	"bucket": deployment.deployedBucket,
})

type SourceConfig 

type SourceConfig struct {
	// The source bucket to deploy from.
	Bucket awss3.IBucket `field:"required" json:"bucket" yaml:"bucket"`
	// An S3 object key in the source bucket that points to a zip file.
	ZipObjectKey *string `field:"required" json:"zipObjectKey" yaml:"zipObjectKey"`
	// A set of markers to substitute in the source content.
	// Default: - no markers.
	//
	Markers *map[string]interface{} `field:"optional" json:"markers" yaml:"markers"`
}

Source information.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

var bucket bucket
var markers interface{}

sourceConfig := &SourceConfig{
	Bucket: bucket,
	ZipObjectKey: jsii.String("zipObjectKey"),

	// the properties below are optional
	Markers: map[string]interface{}{
		"markersKey": markers,
	},
}

type StorageClass 

type StorageClass string

Storage class used for storing the object.

Example: 

websiteBucket := s3.NewBucket(this, jsii.String("WebsiteBucket"), &BucketProps{
	WebsiteIndexDocument: jsii.String("index.html"),
	PublicReadAccess: jsii.Boolean(true),
})

s3deploy.NewBucketDeployment(this, jsii.String("DeployWebsite"), &BucketDeploymentProps{
	Sources: []iSource{
		s3deploy.Source_Asset(jsii.String("./website-dist")),
	},
	DestinationBucket: websiteBucket,
	DestinationKeyPrefix: jsii.String("web/static"),
	 // optional prefix in destination bucket
	Metadata: map[string]*string{
		"A": jsii.String("1"),
		"b": jsii.String("2"),
	},
	 // user-defined metadata

	// system-defined metadata
	ContentType: jsii.String("text/html"),
	ContentLanguage: jsii.String("en"),
	StorageClass: s3deploy.StorageClass_INTELLIGENT_TIERING,
	ServerSideEncryption: s3deploy.ServerSideEncryption_AES_256,
	CacheControl: []cacheControl{
		s3deploy.*cacheControl_SetPublic(),
		s3deploy.*cacheControl_MaxAge(awscdk.Duration_Hours(jsii.Number(1))),
	},
	AccessControl: s3.BucketAccessControl_BUCKET_OWNER_FULL_CONTROL,
})

See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata 

const (
	// 'STANDARD'.
	StorageClass_STANDARD StorageClass = "STANDARD"
	// 'REDUCED_REDUNDANCY'.
	StorageClass_REDUCED_REDUNDANCY StorageClass = "REDUCED_REDUNDANCY"
	// 'STANDARD_IA'.
	StorageClass_STANDARD_IA StorageClass = "STANDARD_IA"
	// 'ONEZONE_IA'.
	StorageClass_ONEZONE_IA StorageClass = "ONEZONE_IA"
	// 'INTELLIGENT_TIERING'.
	StorageClass_INTELLIGENT_TIERING StorageClass = "INTELLIGENT_TIERING"
	// 'GLACIER'.
	StorageClass_GLACIER StorageClass = "GLACIER"
	// 'DEEP_ARCHIVE'.
	StorageClass_DEEP_ARCHIVE StorageClass = "DEEP_ARCHIVE"
)

type UserDefinedObjectMetadata deprecated 

type UserDefinedObjectMetadata struct {
}

Custom user defined metadata.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"

userDefinedObjectMetadata := &UserDefinedObjectMetadata{
}

Deprecated: Use raw property bags instead (object literals, `Map<String,Object>`, etc... )

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.