Merge branch 'master' into yashda/efs-L2-construct

package.json

@@ -21,7 +21,7 @@
     "jsii-rosetta": "^0.22.0",
     "lerna": "^3.20.2",
     "standard-version": "^7.1.0",
-    "typescript": "~3.8.2"
+    "typescript": "~3.8.3"
   },
   "repository": {
     "type": "git",

packages/@aws-cdk/aws-applicationautoscaling/lib/target-tracking-scaling-policy.ts

@@ -35,14 +35,24 @@ export interface BaseTargetTrackingProps {
   /**
    * Period after a scale in activity completes before another scale in activity can start.
    *
-   * @default - No scale in cooldown.
+   * @default Duration.seconds(300) for the following scalable targets: ECS services,
+   * Spot Fleet requests, EMR clusters, AppStream 2.0 fleets, Aurora DB clusters,
+   * Amazon SageMaker endpoint variants, Custom resources. For all other scalable
+   * targets, the default value is Duration.seconds(0): DynamoDB tables, DynamoDB
+   * global secondary indexes, Amazon Comprehend document classification endpoints,
+   * Lambda provisioned concurrency
    */
   readonly scaleInCooldown?: cdk.Duration;
 
   /**
    * Period after a scale out activity completes before another scale out activity can start.
    *
-   * @default - No scale out cooldown.
+   * @default Duration.seconds(300) for the following scalable targets: ECS services,
+   * Spot Fleet requests, EMR clusters, AppStream 2.0 fleets, Aurora DB clusters,
+   * Amazon SageMaker endpoint variants, Custom resources. For all other scalable
+   * targets, the default value is Duration.seconds(0): DynamoDB tables, DynamoDB
+   * global secondary indexes, Amazon Comprehend document classification endpoints,
+   * Lambda provisioned concurrency
    */
   readonly scaleOutCooldown?: cdk.Duration;
 }

packages/@aws-cdk/aws-cloudfront/package.json

@@ -64,7 +64,7 @@
   "devDependencies": {
     "@aws-cdk/assert": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",

packages/@aws-cdk/aws-cloudtrail/package.json

@@ -64,7 +64,7 @@
   "devDependencies": {
     "@aws-cdk/assert": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",

packages/@aws-cdk/aws-codebuild/package.json

@@ -70,7 +70,7 @@
     "@aws-cdk/aws-sns": "0.0.0",
     "@aws-cdk/aws-sqs": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",

packages/@aws-cdk/aws-codecommit/package.json

@@ -70,7 +70,7 @@
     "@aws-cdk/assert": "0.0.0",
     "@aws-cdk/aws-sns": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",

packages/@aws-cdk/aws-dynamodb/package.json

@@ -64,7 +64,7 @@
   "devDependencies": {
     "@aws-cdk/assert": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "aws-sdk-mock": "^5.0.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",

packages/@aws-cdk/aws-eks/package.json

@@ -64,7 +64,7 @@
   "devDependencies": {
     "@aws-cdk/assert": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",

packages/@aws-cdk/aws-events-targets/package.json

@@ -86,7 +86,7 @@
   "devDependencies": {
     "@aws-cdk/assert": "0.0.0",
     "@aws-cdk/aws-codecommit": "0.0.0",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "aws-sdk-mock": "^5.0.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",

packages/@aws-cdk/aws-lambda/package.json

@@ -71,13 +71,13 @@
     "@types/lodash": "^4.14.149",
     "@types/nodeunit": "^0.0.30",
     "@types/sinon": "^7.5.2",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "aws-sdk-mock": "^5.0.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",
     "lodash": "^4.17.15",
-    "nock": "^12.0.1",
+    "nock": "^12.0.2",
     "nodeunit": "^0.11.3",
     "pkglint": "0.0.0",
     "sinon": "^9.0.0"

packages/@aws-cdk/aws-route53/package.json

@@ -64,7 +64,7 @@
   "devDependencies": {
     "@aws-cdk/assert": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",

packages/@aws-cdk/aws-sqs/package.json

@@ -65,7 +65,7 @@
     "@aws-cdk/assert": "0.0.0",
     "@aws-cdk/aws-s3": "0.0.0",
     "@types/nodeunit": "^0.0.30",
-    "aws-sdk": "^2.628.0",
+    "aws-sdk": "^2.630.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",

packages/@aws-cdk/custom-resources/README.md

@@ -63,7 +63,7 @@ The following example is a skeleton for a Python implementation of `onEvent`:
 
 ```py
 def on_event(event, context):
-  print(event)  
+  print(event)
   request_type = event['RequestType']
   if request_type == 'Create': return on_create(event)
   if request_type == 'Update': return on_update(event)
@@ -76,9 +76,9 @@ def on_create(event):
 
   # add your create code here...
   physical_id = ...
-  
+
   return { 'PhysicalResourceId': physical_id }
-  
+
 def on_update(event):
   physical_id = event["PhysicalResourceId"]
   props = event["ResourceProperties"]
@@ -104,8 +104,8 @@ def is_complete(event, context):
   request_type = event["RequestType"]
 
   # check if resource is stable based on request_type
-  is_ready = ... 
-  
+  is_ready = ...
+
   return { 'IsComplete': is_ready }
 ```
 
@@ -121,7 +121,7 @@ If `onEvent` returns successfully, the framework will submit a "SUCCESS" respons
 to AWS CloudFormation for this resource operation.  If the provider is
 [asynchronous](#asynchronous-providers-iscomplete) (`isCompleteHandler` is
 defined), the framework will only submit a response based on the result of
-`isComplete`. 
+`isComplete`.
 
 If `onEvent` throws an error, the framework will submit a "FAILED" response to
 AWS CloudFormation.
@@ -153,10 +153,10 @@ The return value from `onEvent` must be a JSON object with the following fields:
 
 It is not uncommon for the provisioning of resources to be an asynchronous
 operation, which means that the operation does not immediately finish, and we
-need to "wait" until the resource stabilizes. 
+need to "wait" until the resource stabilizes.
 
 The provider framework makes it easy to implement "waiters" by allowing users to
-specify an additional AWS Lambda function in `isCompleteHandler`. 
+specify an additional AWS Lambda function in `isCompleteHandler`.
 
 The framework will repeatedly invoke the handler every `queryInterval`. When
 `isComplete` returns with `IsComplete: true`, the framework will submit a
@@ -230,7 +230,7 @@ lifecycle events:
 ### Execution Policy
 
 Similarly to any AWS Lambda function, if the user-defined handlers require
-access to AWS resources, you will have to define these permissions  
+access to AWS resources, you will have to define these permissions
 by calling "grant" methods such as `myBucket.grantRead(myHandler)`), using `myHandler.addToRolePolicy`
 or specifying an `initialPolicy` when defining the function.
 
@@ -353,7 +353,7 @@ const awsCustom1 = new AwsCustomResource(this, 'API1', {
   onCreate: {
     service: '...',
     action: '...',
-    physicalResourceId: '...'
+    physicalResourceId: PhysicalResourceId.of('...')
   }
 });
 
@@ -364,7 +364,7 @@ const awsCustom2 = new AwsCustomResource(this, 'API2', {
     parameters: {
       text: awsCustom1.getDataString('Items.0.text')
     },
-    physicalResourceId: '...'
+    physicalResourceId: PhysicalResourceId.of('...')
   }
 })
 ```
@@ -381,7 +381,7 @@ const verifyDomainIdentity = new AwsCustomResource(this, 'VerifyDomainIdentity',
     parameters: {
       Domain: 'example.com'
     },
-    physicalResourceIdPath: 'VerificationToken' // Use the token returned by the call as physical id
+    physicalResourceId: PhysicalResourceId.fromResponse('VerificationToken') // Use the token returned by the call as physical id
   }
 });
 
@@ -403,7 +403,7 @@ const getParameter = new AwsCustomResource(this, 'GetParameter', {
       Name: 'my-parameter',
       WithDecryption: true
     },
-    physicalResourceId: Date.now().toString() // Update physical id to always fetch the latest version
+    physicalResourceId: PhysicalResourceId.of(Date.now().toString()) // Update physical id to always fetch the latest version
   }
 });
 

packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts

@@ -16,6 +16,32 @@ export type AwsSdkMetadata = {[key: string]: any};
 
 const awsSdkMetadata: AwsSdkMetadata = metadata;
 
+/**
+ * Physical ID of the custom resource.
+ */
+export class PhysicalResourceId {
+
+  /**
+   * Extract the physical resource id from the path (dot notation) to the data in the API call response.
+   */
+  public static fromResponse(responsePath: string): PhysicalResourceId {
+    return new PhysicalResourceId(responsePath, undefined);
+  }
+
+  /**
+   * Explicit physical resource id.
+   */
+  public static of(id: string): PhysicalResourceId {
+    return new PhysicalResourceId(undefined, id);
+  }
+
+  /**
+   * @param responsePath Path to a response data element to be used as the physical id.
+   * @param id Literal string to be used as the physical id.
+   */
+  private constructor(public readonly responsePath?: string, public readonly id?: string) { }
+}
+
 /**
  * An AWS SDK call.
  */
@@ -37,27 +63,18 @@ export interface AwsSdkCall {
   /**
    * The parameters for the service action
    *
+   * @default - no paramters
    * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html
    */
   readonly parameters?: any;
 
   /**
-   * The path to the data in the API call response to use as the physical
-   * resource id. Either `physicalResourceId` or `physicalResourceIdPath`
-   * must be specified for onCreate or onUpdate calls.
-   *
-   * @default - no path
-   */
-  readonly physicalResourceIdPath?: string;
-
-  /**
-   * The physical resource id of the custom resource for this call. Either
-   * `physicalResourceId` or `physicalResourceIdPath` must be specified for
-   * onCreate or onUpdate calls.
+   * The physical resource id of the custom resource for this call.
+   * Mandatory for onCreate or onUpdate calls.
    *
    * @default - no physical resource id
    */
-  readonly physicalResourceId?: string;
+  readonly physicalResourceId?: PhysicalResourceId;
 
   /**
    * The regex pattern to use to catch API errors. The `code` property of the
@@ -98,6 +115,11 @@ export interface AwsSdkCall {
   readonly outputPath?: string;
 }
 
+/**
+ * Properties for AwsCustomResource.
+ *
+ * Note that at least onCreate, onUpdate or onDelete must be specified.
+ */
 export interface AwsCustomResourceProps {
   /**
    * Cloudformation Resource type.
@@ -108,7 +130,6 @@ export interface AwsCustomResourceProps {
 
   /**
    * The AWS SDK call to make when the resource is created.
-   * At least onCreate, onUpdate or onDelete must be specified.
    *
    * @default - the call when the resource is updated
    */
@@ -161,11 +182,20 @@ export interface AwsCustomResourceProps {
   readonly timeout?: cdk.Duration
 }
 
+/**
+ * Defines a custom resource that is materialized using specific AWS API calls.
+ *
+ * Use this to bridge any gap that might exist in the CloudFormation Coverage.
+ * You can specify exactly which calls are invoked for the 'CREATE', 'UPDATE' and 'DELETE' life cycle events.
+ *
+ */
 export class AwsCustomResource extends cdk.Construct implements iam.IGrantable {
   public readonly grantPrincipal: iam.IPrincipal;
 
   private readonly customResource: CustomResource;
 
+  // 'props' cannot be optional, even though all its properties are optional.
+  // this is because at least one sdk call must be provided.
   constructor(scope: cdk.Construct, id: string, props: AwsCustomResourceProps) {
     super(scope, id);
 
@@ -174,8 +204,8 @@ export class AwsCustomResource extends cdk.Construct implements iam.IGrantable {
     }
 
     for (const call of [props.onCreate, props.onUpdate]) {
-      if (call && !call.physicalResourceId && !call.physicalResourceIdPath) {
-        throw new Error('Either `physicalResourceId` or `physicalResourceIdPath` must be specified for onCreate and onUpdate calls.');
+      if (call && !call.physicalResourceId) {
+        throw new Error('`physicalResourceId` must be specified for onCreate and onUpdate calls.');
       }
     }
 

packages/@aws-cdk/custom-resources/lib/aws-custom-resource/runtime/index.ts

@@ -90,14 +90,14 @@ export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent
     let physicalResourceId: string;
     switch (event.RequestType) {
       case 'Create':
-        physicalResourceId = event.ResourceProperties.Create?.physicalResourceId ??
-                             event.ResourceProperties.Update?.physicalResourceId ??
-                             event.ResourceProperties.Delete?.physicalResourceId ??
+        physicalResourceId = event.ResourceProperties.Create?.physicalResourceId?.id ??
+                             event.ResourceProperties.Update?.physicalResourceId?.id ??
+                             event.ResourceProperties.Delete?.physicalResourceId?.id ??
                              event.LogicalResourceId;
         break;
       case 'Update':
       case 'Delete':
-        physicalResourceId = event.ResourceProperties[event.RequestType]?.physicalResourceId ?? event.PhysicalResourceId;
+        physicalResourceId = event.ResourceProperties[event.RequestType]?.physicalResourceId?.id ?? event.PhysicalResourceId;
         break;
     }
 
@@ -127,8 +127,8 @@ export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent
         }
       }
 
-      if (call.physicalResourceIdPath) {
-        physicalResourceId = flatData[call.physicalResourceIdPath];
+      if (call.physicalResourceId?.responsePath) {
+        physicalResourceId = flatData[call.physicalResourceId.responsePath];
       }
     }