refactor: use construct interfaces in public api (awslint:ref-via-interface) (#2499)

Adds a new awslint:ref-via-interface rule which validates that all input APIs
(e.g. props, method arguments) use construct interface (IBucket) and not concrete
classes (Bucket). This is in order to enable passing in unowned resources and
in accordance with the aws construct library guidelines.

There are situations where an owned resource is required. In those, the rule
can be disabled by adding [disable-awslint:ref-via-interface] to the element's
inline documentation.

To enable this, the following new construct interfaces were added, along with `fromXxx` import methods:
* `applicationautoscaling.IScalableTarget`
* `cloudwatch.IAlarm`
* `ecs.IService`
* `ecs.IEc2Service`
* `ec2.IFargateService`
* `ecs.ITaskDefinition`
* `iam.IGroup`
* `iam.IUser`
* `iam.IPolicy`
* `lambda.IVersion`

Fixes #2412 

BREAKING CHANGE: `apigateway.ResourceBase.trackChild` is now internal.
* `cloudfront.S3OriginConfig.originAccessIdentity` is now `originAccessIdentityId`
* `codedeploy.LambdaDeploymentGroup.alarms` is now `cloudwatch.IAlarm[]` (previously `cloudwatch.Alarm[]`)
* `codepipeline.crossRegionScaffoldingStacks` renamed to `crossRegionScaffolding`
* `codepipeline.CrossRegionScaffoldingStack` renamed to `codepipeline.CrossRegionScaffolding` and cannot be instantiated (abstract)
* `ec2.VpcSubnet.addDefaultRouteToNAT` renamed to `addDefaultNatRoute` and made public
* `ec2.VpcSubnet.addDefaultRouteToIGW` renamed to `addDefaultInternetRoute`, made public and first argument is the gateway ID (string) and not the CFN L1 class
* `ecs.Ec2EventRuleTarget.taskDefinition` is now `ITaskDefinition` (previously `TaskDefinition`)
* `lambda.IEventSource.bind` now accepts `IFunction` instead of `FunctionBase`. Use `IFunction.addEventSourceMapping` to add an event source mapping under the function.
* `lambda.Layer.grantUsage` renamed to `lambda.layer.addPermission` and returns void
* `stepfunctions.StateMachine.role` is now `iam.IRole` (previously `iam.Role`)

Author: Elad Ben-Israel

.gitignore

@@ -1,4 +1,5 @@
 *.tsbuildinfo
+.cdk.staging
 
 .vscode
 # VSCode extension

packages/@aws-cdk/assets/lib/asset.ts

@@ -158,7 +158,7 @@ export class Asset extends cdk.Construct {
    *
    * @see https://github.com/awslabs/aws-cdk/issues/1432
    *
-   * @param resource The CloudFormation resource which is using this asset.
+   * @param resource The CloudFormation resource which is using this asset [disable-awslint:ref-via-interface]
    * @param resourceProperty The property name where this asset is referenced
    * (e.g. "Code" for AWS::Lambda::Function)
    */

packages/@aws-cdk/aws-apigateway/lib/resource.ts

@@ -144,7 +144,10 @@ export abstract class ResourceBase extends ResourceConstruct implements IResourc
     return this.children[pathPart];
   }
 
-  public trackChild(pathPart: string, resource: Resource) {
+  /**
+   * @internal
+   */
+  public _trackChild(pathPart: string, resource: Resource) {
     this.children[pathPart] = resource;
   }
 
@@ -194,7 +197,7 @@ export class Resource extends ResourceBase {
     this.parentResource = props.parent;
 
     if (props.parent instanceof ResourceBase) {
-      props.parent.trackChild(props.pathPart, this);
+      props.parent._trackChild(props.pathPart, this);
     }
 
     const resourceProps: CfnResourceProps = {

packages/@aws-cdk/aws-apigateway/lib/stage.ts

@@ -69,7 +69,7 @@ export interface StageOptions extends MethodDeploymentOptions {
 
 export interface StageProps extends StageOptions {
   /**
-   * The deployment that this stage points to.
+   * The deployment that this stage points to [disable-awslint:ref-via-interface].
    */
   readonly deployment: Deployment;
 }

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

@@ -86,9 +86,7 @@
   },
   "awslint": {
     "exclude": [
-      "resource-attribute:@aws-cdk/aws-apigateway.IRestApi.restApiRootResourceId",
-      "from-method:@aws-cdk/aws-apigateway.Resource",
-      "construct-base-is-private:@aws-cdk/aws-apigateway.ResourceBase"
+      "from-method:@aws-cdk/aws-apigateway.Resource"
     ]
   }
 }

packages/@aws-cdk/aws-applicationautoscaling/lib/scalable-target.ts

@@ -1,9 +1,16 @@
 import iam = require('@aws-cdk/aws-iam');
-import { Construct, Resource } from '@aws-cdk/cdk';
+import { Construct, IResource, Resource } from '@aws-cdk/cdk';
 import { CfnScalableTarget } from './applicationautoscaling.generated';
 import { BasicStepScalingPolicyProps, StepScalingPolicy } from './step-scaling-policy';
 import { BasicTargetTrackingScalingPolicyProps, TargetTrackingScalingPolicy } from './target-tracking-scaling-policy';
 
+export interface IScalableTarget extends IResource {
+  /**
+   * @attribute
+   */
+  readonly scalableTargetId: string;
+}
+
 /**
  * Properties for a scalable target
  */
@@ -61,7 +68,15 @@ export interface ScalableTargetProps {
 /**
  * Define a scalable target
  */
-export class ScalableTarget extends Resource {
+export class ScalableTarget extends Resource implements IScalableTarget {
+
+  public static fromScalableTargetId(scope: Construct, id: string, scalableTargetId: string): IScalableTarget {
+    class Import extends Resource implements IScalableTarget {
+      public readonly scalableTargetId = scalableTargetId;
+    }
+    return new Import(scope, id);
+  }
+
   /**
    * ID of the Scalable Target
    *

packages/@aws-cdk/aws-applicationautoscaling/lib/step-scaling-action.ts

@@ -1,7 +1,7 @@
 import cloudwatch = require('@aws-cdk/aws-cloudwatch');
 import cdk = require('@aws-cdk/cdk');
 import { CfnScalingPolicy } from './applicationautoscaling.generated';
-import { ScalableTarget } from './scalable-target';
+import { IScalableTarget } from './scalable-target';
 
 /**
  * Properties for a scaling policy
@@ -10,7 +10,7 @@ export interface StepScalingActionProps {
   /**
    * The scalable target
    */
-  readonly scalingTarget: ScalableTarget;
+  readonly scalingTarget: IScalableTarget;
 
   /**
    * A name for the scaling policy

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

@@ -1,7 +1,7 @@
 import { findAlarmThresholds, normalizeIntervals } from '@aws-cdk/aws-autoscaling-common';
 import cloudwatch = require('@aws-cdk/aws-cloudwatch');
 import cdk = require('@aws-cdk/cdk');
-import { ScalableTarget } from './scalable-target';
+import { IScalableTarget } from './scalable-target';
 import { AdjustmentType, MetricAggregationType, StepScalingAction } from './step-scaling-action';
 
 export interface BasicStepScalingPolicyProps {
@@ -52,7 +52,7 @@ export interface StepScalingPolicyProps extends BasicStepScalingPolicyProps {
   /**
    * The scaling target
    */
-  readonly scalingTarget: ScalableTarget;
+  readonly scalingTarget: IScalableTarget;
 }
 
 /**

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

@@ -1,7 +1,7 @@
 import cloudwatch = require('@aws-cdk/aws-cloudwatch');
 import cdk = require('@aws-cdk/cdk');
 import { CfnScalingPolicy } from './applicationautoscaling.generated';
-import { ScalableTarget } from './scalable-target';
+import { IScalableTarget } from './scalable-target';
 
 /**
  * Base interface for target tracking props
@@ -95,7 +95,7 @@ export interface TargetTrackingScalingPolicyProps extends BasicTargetTrackingSca
   /*
    * The scalable target
    */
-  readonly scalingTarget: ScalableTarget;
+  readonly scalingTarget: IScalableTarget;
 }
 
 export class TargetTrackingScalingPolicy extends cdk.Construct {

packages/@aws-cdk/aws-cloudfront/lib/web_distribution.ts

@@ -1,7 +1,7 @@
 import route53 = require('@aws-cdk/aws-route53');
 import s3 = require('@aws-cdk/aws-s3');
 import cdk = require('@aws-cdk/cdk');
-import { CfnCloudFrontOriginAccessIdentity, CfnDistribution } from './cloudfront.generated';
+import { CfnDistribution } from './cloudfront.generated';
 
 export enum HttpVersion {
   HTTP1_1 = "http1.1",
@@ -237,12 +237,12 @@ export interface S3OriginConfig {
   /**
    * The source bucket to serve content from
    */
-  readonly s3BucketSource: s3.IBucket,
+  readonly s3BucketSource: s3.IBucket;
 
   /**
-   * The optional origin identity cloudfront will use when calling your s3 bucket.
+   * The optional ID of the origin identity cloudfront will use when calling your s3 bucket.
    */
-  readonly originAccessIdentity?: CfnCloudFrontOriginAccessIdentity
+  readonly originAccessIdentityId?: string;
 }
 
 /**
@@ -570,8 +570,8 @@ export class CloudFrontWebDistribution extends cdk.Construct implements route53.
           : originConfig.customOriginSource!.domainName,
         originPath: originConfig.originPath,
         originCustomHeaders: originHeaders.length > 0 ? originHeaders : undefined,
-        s3OriginConfig: originConfig.s3OriginSource && originConfig.s3OriginSource.originAccessIdentity
-          ? { originAccessIdentity: `origin-access-identity/cloudfront/${originConfig.s3OriginSource.originAccessIdentity.ref}` }
+        s3OriginConfig: originConfig.s3OriginSource && originConfig.s3OriginSource.originAccessIdentityId
+          ? { originAccessIdentity: `origin-access-identity/cloudfront/${originConfig.s3OriginSource.originAccessIdentityId}` }
           : originConfig.s3OriginSource
           ? { }
           : undefined,