diff --git a/packages/@aws-cdk/aws-s3-deployment/README.md b/packages/@aws-cdk/aws-s3-deployment/README.md index b0bb1e2d9ebd5..64c3872c59f74 100644 --- a/packages/@aws-cdk/aws-s3-deployment/README.md +++ b/packages/@aws-cdk/aws-s3-deployment/README.md @@ -3,13 +3,7 @@ --- -![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge) - -> The APIs of higher level constructs in this module are experimental and under active development. -> They are subject to non-backward compatible changes or removal in any future version. These are -> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be -> announced in the release notes. This means that while you may use them, you may need to update -> your source code when upgrading to a newer version of this package. +![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge) --- @@ -70,6 +64,37 @@ By default, the contents of the destination bucket will **not** be deleted when 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 availablity 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`](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-s3-readme.html#bucket-deletion) +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 diff --git a/packages/@aws-cdk/aws-s3-deployment/lib/bucket-deployment.ts b/packages/@aws-cdk/aws-s3-deployment/lib/bucket-deployment.ts index 4ca33864952f3..ca91f036dc5ed 100644 --- a/packages/@aws-cdk/aws-s3-deployment/lib/bucket-deployment.ts +++ b/packages/@aws-cdk/aws-s3-deployment/lib/bucket-deployment.ts @@ -13,6 +13,9 @@ import { ISource, SourceConfig } from './source'; // eslint-disable-next-line no-duplicate-imports, import/order import { Construct as CoreConstruct } from '@aws-cdk/core'; +/** + * Properties for `BucketDeployment`. + */ export interface BucketDeploymentProps { /** * The sources from which to deploy the contents of this bucket. @@ -45,11 +48,10 @@ export interface BucketDeploymentProps { * If this is set to "false", the destination files will be deleted when the * resource is deleted or the destination is updated. * - * NOTICE: if this is set to "false" and destination bucket/prefix is updated, - * all files in the previous destination will first be deleted and then - * uploaded to the new destination location. This could have availablity - * implications on your users. + * 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/master/packages/%40aws-cdk/aws-s3-deployment#retain-on-delete * @default true - when resource is deleted/updated, files are retained */ readonly retainOnDelete?: boolean; @@ -179,6 +181,10 @@ export interface BucketDeploymentProps { readonly vpcSubnets?: ec2.SubnetSelection; } +/** + * `BucketDeployment` populates an S3 bucket with the contents of .zip files from + * other S3 buckets or from local disk + */ export class BucketDeployment extends CoreConstruct { constructor(scope: Construct, id: string, props: BucketDeploymentProps) { super(scope, id); @@ -285,17 +291,58 @@ function mapSystemMetadata(metadata: BucketDeploymentProps) { * @see https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata */ export class CacheControl { + + /** + * Sets 'must-revalidate'. + */ public static mustRevalidate() { return new CacheControl('must-revalidate'); } + + /** + * Sets 'no-cache'. + */ public static noCache() { return new CacheControl('no-cache'); } + + /** + * Sets 'no-transform'. + */ public static noTransform() { return new CacheControl('no-transform'); } + + /** + * Sets 'public'. + */ public static setPublic() { return new CacheControl('public'); } + + /** + * Sets 'private'. + */ public static setPrivate() { return new CacheControl('private'); } + + /** + * Sets 'proxy-revalidate'. + */ public static proxyRevalidate() { return new CacheControl('proxy-revalidate'); } + + /** + * Sets 'max-age='. + */ public static maxAge(t: cdk.Duration) { return new CacheControl(`max-age=${t.toSeconds()}`); } + + /** + * Sets 's-maxage='. + */ public static sMaxAge(t: cdk.Duration) { return new CacheControl(`s-maxage=${t.toSeconds()}`); } + + /** + * Constructs a custom cache control key from the literal value. + */ public static fromString(s: string) { return new CacheControl(s); } - private constructor(public readonly value: any) {} + private constructor( + /** + * The raw cache control setting. + */ + public readonly value: any, + ) {} } /** @@ -304,7 +351,15 @@ export class CacheControl { * @see https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata */ export enum ServerSideEncryption { + + /** + * 'AES256' + */ AES_256 = 'AES256', + + /** + * 'aws:kms' + */ AWS_KMS = 'aws:kms' } @@ -313,12 +368,40 @@ export enum ServerSideEncryption { * @see https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata */ export enum StorageClass { + + /** + * 'STANDARD' + */ STANDARD = 'STANDARD', + + /** + * 'REDUCED_REDUNDANCY' + */ REDUCED_REDUNDANCY = 'REDUCED_REDUNDANCY', + + /** + * 'STANDARD_IA' + */ STANDARD_IA = 'STANDARD_IA', + + /** + * 'ONEZONE_IA' + */ ONEZONE_IA = 'ONEZONE_IA', + + /** + * 'INTELLIGENT_TIERING' + */ INTELLIGENT_TIERING = 'INTELLIGENT_TIERING', + + /** + * 'GLACIER' + */ GLACIER = 'GLACIER', + + /** + * 'DEEP_ARCHIVE' + */ DEEP_ARCHIVE = 'DEEP_ARCHIVE' } @@ -347,11 +430,22 @@ export class Expires { */ public static after(t: cdk.Duration) { return Expires.atDate(new Date(Date.now() + t.toMilliseconds())); } + /** + * Create an expiration date from a raw date string. + */ public static fromString(s: string) { return new Expires(s); } - private constructor(public readonly value: any) {} + private constructor( + /** + * The raw expiration date expression. + */ + public readonly value: any, + ) {} } +/** + * Custom user defined metadata. + */ export interface UserDefinedObjectMetadata { /** * Arbitrary metadata key-values diff --git a/packages/@aws-cdk/aws-s3-deployment/lib/source.ts b/packages/@aws-cdk/aws-s3-deployment/lib/source.ts index 558c32556c25c..4eaea3fdc0060 100644 --- a/packages/@aws-cdk/aws-s3-deployment/lib/source.ts +++ b/packages/@aws-cdk/aws-s3-deployment/lib/source.ts @@ -6,6 +6,9 @@ import * as s3_assets from '@aws-cdk/aws-s3-assets'; // eslint-disable-next-line no-duplicate-imports, import/order import { Construct } from '@aws-cdk/core'; +/** + * Source information. + */ export interface SourceConfig { /** * The source bucket to deploy from. diff --git a/packages/@aws-cdk/aws-s3-deployment/package.json b/packages/@aws-cdk/aws-s3-deployment/package.json index 71dabe9caf6e0..2709a5baac677 100644 --- a/packages/@aws-cdk/aws-s3-deployment/package.json +++ b/packages/@aws-cdk/aws-s3-deployment/package.json @@ -111,37 +111,8 @@ "engines": { "node": ">= 10.13.0 <13 || >=13.7.0" }, - "stability": "experimental", - "maturity": "experimental", - "awslint": { - "exclude": [ - "docs-public-apis:@aws-cdk/aws-s3-deployment.Expires.fromString", - "docs-public-apis:@aws-cdk/aws-s3-deployment.BucketDeployment", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.fromString", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.maxAge", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.mustRevalidate", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.noCache", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.noTransform", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.proxyRevalidate", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.setPrivate", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.setPublic", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.sMaxAge", - "docs-public-apis:@aws-cdk/aws-s3-deployment.Expires.value", - "docs-public-apis:@aws-cdk/aws-s3-deployment.CacheControl.value", - "docs-public-apis:@aws-cdk/aws-s3-deployment.BucketDeploymentProps", - "docs-public-apis:@aws-cdk/aws-s3-deployment.SourceConfig", - "docs-public-apis:@aws-cdk/aws-s3-deployment.UserDefinedObjectMetadata", - "docs-public-apis:@aws-cdk/aws-s3-deployment.ServerSideEncryption.AES_256", - "docs-public-apis:@aws-cdk/aws-s3-deployment.ServerSideEncryption.AWS_KMS", - "docs-public-apis:@aws-cdk/aws-s3-deployment.StorageClass.STANDARD", - "docs-public-apis:@aws-cdk/aws-s3-deployment.StorageClass.REDUCED_REDUNDANCY", - "docs-public-apis:@aws-cdk/aws-s3-deployment.StorageClass.STANDARD_IA", - "docs-public-apis:@aws-cdk/aws-s3-deployment.StorageClass.ONEZONE_IA", - "docs-public-apis:@aws-cdk/aws-s3-deployment.StorageClass.INTELLIGENT_TIERING", - "docs-public-apis:@aws-cdk/aws-s3-deployment.StorageClass.GLACIER", - "docs-public-apis:@aws-cdk/aws-s3-deployment.StorageClass.DEEP_ARCHIVE" - ] - }, + "stability": "stable", + "maturity": "stable", "awscdkio": { "announce": false },