feat(s3-deployment): add deployedBucket attribute for sequencing (#15384)

This allows referencing the bucket in a way that ensures the
deployment has happened before dependent resources are created.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

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

@@ -42,6 +42,25 @@ This is what happens under the hood:
    `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:
+
+```ts
+declare const websiteBucket: s3.Bucket;
+
+const deployment = new s3deploy.BucketDeployment(this, 'DeployWebsite', {
+  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+  destinationBucket: websiteBucket,
+});
+
+new ConstructThatReadsFromTheBucket(this, 'Consumer', {
+  // Use 'deployment.deployedBucket' instead of 'websiteBucket' here
+  bucket: deployment.deployedBucket,
+});
+```
+
 ## Supported sources
 
 The following source types are supported for bucket deployments:
@@ -302,7 +321,7 @@ substituting it when its deployed to the destination with the actual value.
 
 ## Notes
 
-- This library uses an AWS CloudFormation custom resource which about 10MiB in
+- 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.

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

@@ -12,6 +12,10 @@ import { kebab as toKebabCase } from 'case';
 import { Construct } from 'constructs';
 import { ISource, SourceConfig } from './source';
 
+// keep this import separate from other imports to reduce chance for merge conflicts with v2-main
+// eslint-disable-next-line no-duplicate-imports, import/order
+import { Token } from '@aws-cdk/core';
+
 // keep this import separate from other imports to reduce chance for merge conflicts with v2-main
 // eslint-disable-next-line no-duplicate-imports, import/order
 import { Construct as CoreConstruct } from '@aws-cdk/core';
@@ -239,6 +243,10 @@ export interface BucketDeploymentProps {
  * other S3 buckets or from local disk
  */
 export class BucketDeployment extends CoreConstruct {
+  private readonly cr: cdk.CustomResource;
+  private _deployedBucket?: s3.IBucket;
+  private requestDestinationArn: boolean = false;
+
   constructor(scope: Construct, id: string, props: BucketDeploymentProps) {
     super(scope, id);
 
@@ -328,7 +336,7 @@ export class BucketDeployment extends CoreConstruct {
     const hasMarkers = sources.some(source => source.markers);
 
     const crUniqueId = `CustomResource${this.renderUniqueId(props.memoryLimit, props.vpc)}`;
-    const cr = new cdk.CustomResource(this, crUniqueId, {
+    this.cr = new cdk.CustomResource(this, crUniqueId, {
       serviceToken: handler.functionArn,
       resourceType: 'Custom::CDKBucketDeployment',
       properties: {
@@ -345,13 +353,15 @@ export class BucketDeployment extends CoreConstruct {
         SystemMetadata: mapSystemMetadata(props),
         DistributionId: props.distribution?.distributionId,
         DistributionPaths: props.distributionPaths,
+        // Passing through the ARN sequences dependencees on the deployment
+        DestinationBucketArn: cdk.Lazy.string({ produce: () => this.requestDestinationArn ? props.destinationBucket.bucketArn : undefined }),
       },
     });
 
     let prefix: string = props.destinationKeyPrefix ?
       `:${props.destinationKeyPrefix}` :
       '';
-    prefix += `:${cr.node.addr.substr(-8)}`;
+    prefix += `:${this.cr.node.addr.substr(-8)}`;
     const tagKey = CUSTOM_RESOURCE_OWNER_TAG + prefix;
 
     // destinationKeyPrefix can be 104 characters before we hit
@@ -405,6 +415,21 @@ export class BucketDeployment extends CoreConstruct {
 
   }
 
+  /**
+   * 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`.
+   *
+   * Doing this replaces calling `otherResource.node.addDependency(deployment)`.
+   */
+  public get deployedBucket(): s3.IBucket {
+    this.requestDestinationArn = true;
+    this._deployedBucket = this._deployedBucket ?? s3.Bucket.fromBucketArn(this, 'DestinationBucket', Token.asString(this.cr.getAtt('DestinationBucketArn')));
+    return this._deployedBucket;
+  }
+
   private renderUniqueId(memoryLimit?: number, vpc?: ec2.IVpc) {
     let uuid = '';
 

packages/@aws-cdk/aws-s3-deployment/lib/lambda/index.py

@@ -118,7 +118,10 @@ def cfn_error(message=None):
         if distribution_id:
             cloudfront_invalidate(distribution_id, distribution_paths)
 
-        cfn_send(event, context, CFN_SUCCESS, physicalResourceId=physical_id)
+        cfn_send(event, context, CFN_SUCCESS, physicalResourceId=physical_id, responseData={
+            # Passing through the ARN sequences dependencees on the deployment
+            'DestinationBucketArn': props.get('DestinationBucketArn')
+        })
     except KeyError as e:
         cfn_error("invalid request. Missing key %s" % str(e))
     except Exception as e:

packages/@aws-cdk/aws-s3-deployment/rosetta/default.ts-fixture

@@ -13,3 +13,8 @@ class Fixture extends Stack {
     /// here
   }
 }
+
+class ConstructThatReadsFromTheBucket {
+  constructor(...args: any[]) {
+  }
+}

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

@@ -945,6 +945,68 @@ test('deployment allows vpc and subnets to be implicitly supplied to lambda', ()
   });
 });
 
+test('s3 deployment bucket is identical to destination bucket', () => {
+  // GIVEN
+  const stack = new cdk.Stack();
+  const bucket = new s3.Bucket(stack, 'Dest');
+
+  // WHEN
+  const bd = new s3deploy.BucketDeployment(stack, 'Deployment', {
+    destinationBucket: bucket,
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+  });
+
+  // Call this function
+  void(bd.deployedBucket);
+
+  // THEN
+  const template = Template.fromStack(stack);
+  template.hasResourceProperties('Custom::CDKBucketDeployment', {
+    // Since this utilizes GetAtt, we know CFN will deploy the bucket first
+    // before deploying other resources that rely call the destination bucket.
+    DestinationBucketArn: { 'Fn::GetAtt': ['DestC383B82A', 'Arn'] },
+  });
+});
+
+test('using deployment bucket references the destination bucket by means of the CustomResource', () => {
+  // GIVEN
+  const stack = new cdk.Stack();
+  const bucket = new s3.Bucket(stack, 'Dest');
+  const deployment = new s3deploy.BucketDeployment(stack, 'Deployment', {
+    destinationBucket: bucket,
+    sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
+  });
+
+  // WHEN
+  new cdk.CfnOutput(stack, 'DestinationArn', {
+    value: deployment.deployedBucket.bucketArn,
+  });
+  new cdk.CfnOutput(stack, 'DestinationName', {
+    value: deployment.deployedBucket.bucketName,
+  });
+
+  // THEN
+
+  const template = Template.fromStack(stack);
+  expect(template.findOutputs('*')).toEqual({
+    DestinationArn: {
+      Value: { 'Fn::GetAtt': ['DeploymentCustomResource47E8B2E6', 'DestinationBucketArn'] },
+    },
+    DestinationName: {
+      Value: {
+        'Fn::Select': [0, {
+          'Fn::Split': ['/', {
+            'Fn::Select': [5, {
+              'Fn::Split': [':',
+                { 'Fn::GetAtt': ['DeploymentCustomResource47E8B2E6', 'DestinationBucketArn'] }],
+            }],
+          }],
+        }],
+      },
+    },
+  });
+});
+
 test('resource id includes memory and vpc', () => {
 
   // GIVEN
@@ -1139,4 +1201,4 @@ function readDataFile(casm: cxapi.CloudAssembly, assetId: string, filePath: stri
   const asset = casm.stacks[0].assets.find(a => a.id === assetId);
   if (!asset) { throw new Error('Asset not found'); }
   return readFileSync(path.join(casm.directory, asset.path, filePath), 'utf-8');
-}
+}