feat(codedeploy) lambda application and deployment groups (#1628)

Adds `LambdaApplication` and `LambdaDeploymentGroup` such that an `Alias` to a Lambda `Function` can be deployed via CodeDeploy; supports pre/post hook functions, traffic-shifting and alarm monitoring and rollback.

packages/@aws-cdk/aws-apigateway/test/test.lambda-api.ts

@@ -126,9 +126,12 @@ export = {
               },
               ":lambda:path/2015-03-31/functions/",
               {
-                "Ref": "alias68BF17F5"
+                "Fn::GetAtt": [
+                  "handlerE1533BD5",
+                  "Arn"
+                ]
               },
-              "/invocations"
+              ":my-alias/invocations"
             ]
           ]
         }

packages/@aws-cdk/aws-codedeploy/README.md

@@ -1,6 +1,10 @@
 ## The CDK Construct Library for AWS CodeDeploy
 
-### Applications
+AWS CodeDeploy is a deployment service that automates application deployments to Amazon EC2 instances, on-premises instances, serverless Lambda functions, or Amazon ECS services.
+
+The CDK currently supports Amazon EC2, on-premise and AWS Lambda applications.
+
+### EC2/on-premise Applications
 
 To create a new CodeDeploy Application that deploys to EC2/on-premise instances:
 
@@ -20,7 +24,7 @@ const application = codedeploy.ServerApplication.import(this, 'ExistingCodeDeplo
 });
 ```
 
-### Deployment Groups
+### EC2/on-premise Deployment Groups
 
 To create a new CodeDeploy Deployment Group that deploys to EC2/on-premise instances:
 
@@ -184,3 +188,115 @@ You can also add the Deployment Group to the Pipeline directly:
 // equivalent to the code above:
 deploymentGroup.addToPipeline(deployStage, 'CodeDeploy');
 ```
+
+### Lambda Applications
+
+To create a new CodeDeploy Application that deploys to a Lambda function:
+
+```ts
+import codedeploy = require('@aws-cdk/aws-codedeploy');
+
+const application = new codedeploy.LambdaApplication(this, 'CodeDeployApplication', {
+    applicationName: 'MyApplication', // optional property
+});
+```
+
+To import an already existing Application:
+
+```ts
+const application = codedeploy.LambdaApplication.import(this, 'ExistingCodeDeployApplication', {
+    applicationName: 'MyExistingApplication',
+});
+```
+
+### Lambda Deployment Groups
+
+To enable traffic shifting deployments for Lambda functions, CodeDeploy uses Lambda Aliases, which can balance incoming traffic between two different versions of your function.
+Before deployment, the alias sends 100% of invokes to the version used in production.
+When you publish a new version of the function to your stack, CodeDeploy will send a small percentage of traffic to the new version, monitor, and validate before shifting 100% of traffic to the new version.
+
+To create a new CodeDeploy Deployment Group that deploys to a Lambda function:
+
+```ts
+import codedeploy = require('@aws-cdk/aws-codedeploy');
+import lambda = require('@aws-cdk/aws-lambda');
+
+const myApplication = new codedeploy.LambdaApplication(..);
+const func = new lambda.Function(..);
+const version = func.addVersion('1');
+const version1Alias = new lambda.Alias({
+  aliasName: 'prod',
+  version
+});
+
+const deploymentGroup = new codedeploy.LambdaDeploymentGroup(stack, 'BlueGreenDeployment', {
+  application: myApplication, // optional property: one will be created for you if not provided
+  alias: version1Alias,
+  deploymentConfig: codedeploy.LambdaDeploymentConfig.Linear10PercentEvery1Minute,
+});
+```
+
+In order to deploy a new version of this function:
+1. Increment the version, e.g. `const version = func.addVersion('2')`.
+2. Re-deploy the stack (this will trigger a deployment).
+3. Monitor the CodeDeploy deployment as traffic shifts between the versions.
+
+#### Rollbacks and Alarms
+
+CodeDeploy will roll back if the deployment fails. You can optionally trigger a rollback when one or more alarms are in a failed state:
+
+```ts
+const deploymentGroup = new codedeploy.LambdaDeploymentGroup(stack, 'BlueGreenDeployment', {
+  alias,
+  deploymentConfig: codedeploy.LambdaDeploymentConfig.Linear10PercentEvery1Minute,
+  alarms: [
+    // pass some alarms when constructing the deployment group
+    new cloudwatch.Alarm(stack, 'Errors', {
+      comparisonOperator: cloudwatch.ComparisonOperator.GreaterThanThreshold,
+      threshold: 1,
+      evaluationPeriods: 1,
+      metric: alias.metricErrors()
+    })
+  ]
+});
+
+// or add alarms to an existing group
+deploymentGroup.addAlarm(new cloudwatch.Alarm(stack, 'BlueGreenErrors', {
+  comparisonOperator: cloudwatch.ComparisonOperator.GreaterThanThreshold,
+  threshold: 1,
+  evaluationPeriods: 1,
+  metric: blueGreenAlias.metricErrors()
+}));
+```
+
+#### Pre and Post Hooks
+
+CodeDeploy allows you to run an arbitrary Lambda function before traffic shifting actually starts (PreTraffic Hook) and after it completes (PostTraffic Hook).
+With either hook, you have the opportunity to run logic that determines whether the deployment must succeed or fail.
+For example, with PreTraffic hook you could run integration tests against the newly created Lambda version (but not serving traffic). With PostTraffic hook, you could run end-to-end validation checks.
+
+```ts
+const warmUpUserCache = new lambda.Function(..);
+const endToEndValidation = new lambda.Function(..);
+
+// pass a hook whe creating the deployment group
+const deploymentGroup = new codedeploy.LambdaDeploymentGroup(stack, 'BlueGreenDeployment', {
+  alias: alias,
+  deploymentConfig: codedeploy.LambdaDeploymentConfig.Linear10PercentEvery1Minute,
+  preHook: warmUpUserCache,
+});
+
+// or configure one on an existing deployment group
+deploymentGroup.onPostHook(endToEndValidation);
+```
+
+#### Import an existing Deployment Group
+
+To import an already existing Deployment Group:
+
+```ts
+const deploymentGroup = codedeploy.LambdaDeploymentGroup.import(this, 'ExistingCodeDeployDeploymentGroup', {
+    application,
+    deploymentGroupName: 'MyExistingDeploymentGroup',
+});
+```

packages/@aws-cdk/aws-codedeploy/lib/index.ts

@@ -1,7 +1,7 @@
-export * from './application';
-export * from './deployment-config';
-export * from './deployment-group';
+export * from './rollback-config';
+export * from './lambda';
 export * from './pipeline-action';
+export * from './server';
 
 // AWS::CodeDeploy CloudFormation Resources:
 export * from './codedeploy.generated';

packages/@aws-cdk/aws-codedeploy/lib/lambda/application.ts

@@ -0,0 +1,101 @@
+import cdk = require("@aws-cdk/cdk");
+import { CfnApplication } from "../codedeploy.generated";
+import { applicationNameToArn } from "../utils";
+
+/**
+ * Represents a reference to a CodeDeploy Application deploying to AWS Lambda.
+ *
+ * If you're managing the Application alongside the rest of your CDK resources,
+ * use the {@link LambdaApplication} class.
+ *
+ * If you want to reference an already existing Application,
+ * or one defined in a different CDK Stack,
+ * use the {@link LambdaApplication#import} method.
+ */
+export interface ILambdaApplication extends cdk.IConstruct {
+  readonly applicationArn: string;
+  readonly applicationName: string;
+
+  export(): LambdaApplicationImportProps;
+}
+
+/**
+ * Construction properties for {@link LambdaApplication}.
+ */
+export interface LambdaApplicationProps {
+  /**
+   * The physical, human-readable name of the CodeDeploy Application.
+   *
+   * @default an auto-generated name will be used
+   */
+  applicationName?: string;
+}
+
+/**
+ * A CodeDeploy Application that deploys to an AWS Lambda function.
+ */
+export class LambdaApplication extends cdk.Construct implements ILambdaApplication {
+  /**
+   * Import an Application defined either outside the CDK,
+   * or in a different CDK Stack and exported using the {@link ILambdaApplication#export} method.
+   *
+   * @param scope the parent Construct for this new Construct
+   * @param id the logical ID of this new Construct
+   * @param props the properties of the referenced Application
+   * @returns a Construct representing a reference to an existing Application
+   */
+  public static import(scope: cdk.Construct, id: string, props: LambdaApplicationImportProps): ILambdaApplication {
+    return new ImportedLambdaApplication(scope, id, props);
+  }
+
+  public readonly applicationArn: string;
+  public readonly applicationName: string;
+
+  constructor(scope: cdk.Construct, id: string, props: LambdaApplicationProps = {}) {
+    super(scope, id);
+
+    const resource = new CfnApplication(this, 'Resource', {
+      applicationName: props.applicationName,
+      computePlatform: 'Lambda'
+    });
+
+    this.applicationName = resource.ref;
+    this.applicationArn = applicationNameToArn(this.applicationName, this);
+  }
+
+  public export(): LambdaApplicationImportProps {
+    return {
+      applicationName: new cdk.Output(this, 'ApplicationName', { value: this.applicationName }).makeImportValue().toString()
+    };
+  }
+}
+
+/**
+ * Properties of a reference to a CodeDeploy Application.
+ *
+ * @see LambdaApplication#import
+ * @see ILambdaApplication#export
+ */
+export interface LambdaApplicationImportProps {
+  /**
+   * The physical, human-readable name of the Lambda Application we're referencing.
+   * The Application must be in the same account and region as the root Stack.
+   */
+  applicationName: string;
+}
+
+class ImportedLambdaApplication extends cdk.Construct implements ILambdaApplication {
+  public readonly applicationArn: string;
+  public readonly applicationName: string;
+
+  constructor(scope: cdk.Construct, id: string, private readonly props: LambdaApplicationImportProps) {
+    super(scope, id);
+
+    this.applicationName = props.applicationName;
+    this.applicationArn = applicationNameToArn(props.applicationName, this);
+  }
+
+  public export(): LambdaApplicationImportProps {
+    return this.props;
+  }
+}

packages/@aws-cdk/aws-codedeploy/lib/lambda/deployment-config.ts

@@ -0,0 +1,95 @@
+import cdk = require('@aws-cdk/cdk');
+import { arnForDeploymentConfigName } from '../utils';
+
+/**
+ * The Deployment Configuration of a Lambda Deployment Group.
+ * The default, pre-defined Configurations are available as constants on the {@link LambdaDeploymentConfig} class
+ * (`LambdaDeploymentConfig.AllAtOnce`, `LambdaDeploymentConfig.Canary10Percent30Minutes`, etc.).
+ *
+ * Note: CloudFormation does not currently support creating custom lambda configs outside
+ * of using a custom resource. You can import custom deployment config created outside the
+ * CDK or via a custom resource with {@link LambdaDeploymentConfig#import}.
+ */
+export interface ILambdaDeploymentConfig {
+  readonly deploymentConfigName: string;
+  deploymentConfigArn(scope: cdk.IConstruct): string;
+}
+
+class DefaultLambdaDeploymentConfig implements ILambdaDeploymentConfig {
+  public readonly deploymentConfigName: string;
+
+  constructor(deploymentConfigName: string) {
+    this.deploymentConfigName = `CodeDeployDefault.Lambda${deploymentConfigName}`;
+  }
+
+  public deploymentConfigArn(scope: cdk.IConstruct): string {
+    return arnForDeploymentConfigName(this.deploymentConfigName, scope);
+  }
+}
+
+/**
+ * Properties of a reference to a CodeDeploy Lambda Deployment Configuration.
+ *
+ * @see LambdaDeploymentConfig#import
+ * @see LambdaDeploymentConfig#export
+ */
+export interface LambdaDeploymentConfigImportProps {
+  /**
+   * The physical, human-readable name of the custom CodeDeploy Lambda Deployment Configuration
+   * that we are referencing.
+   */
+  deploymentConfigName: string;
+}
+
+class ImportedLambdaDeploymentConfig extends cdk.Construct implements ILambdaDeploymentConfig {
+  public readonly deploymentConfigName: string;
+
+  constructor(scope: cdk.Construct, id: string, private readonly props: LambdaDeploymentConfigImportProps) {
+    super(scope, id);
+
+    this.deploymentConfigName = props.deploymentConfigName;
+  }
+
+  public deploymentConfigArn(scope: cdk.IConstruct): string {
+    return arnForDeploymentConfigName(this.deploymentConfigName, scope);
+  }
+
+  public export() {
+    return this.props;
+  }
+}
+
+/**
+ * A custom Deployment Configuration for a Lambda Deployment Group.
+ *
+ * Note: This class currently stands as namespaced container of the default configurations
+ * until CloudFormation supports custom Lambda Deployment Configs. Until then it is closed
+ * (private constructor) and does not extend {@link cdk.Construct}
+ */
+export class LambdaDeploymentConfig {
+  public static readonly AllAtOnce: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('AllAtOnce');
+  public static readonly Canary10Percent30Minutes: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Canary10Percent30Minutes');
+  public static readonly Canary10Percent5Minutes: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Canary10Percent5Minutes');
+  public static readonly Canary10Percent10Minutes: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Canary10Percent10Minutes');
+  public static readonly Canary10Percent15Minutes: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Canary10Percent15Minutes');
+  public static readonly Linear10PercentEvery10Minutes: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Linear10PercentEvery10Minutes');
+  public static readonly Linear10PercentEvery1Minute: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Linear10PercentEvery1Minute');
+  public static readonly Linear10PercentEvery2Minutes: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Linear10PercentEvery2Minutes');
+  public static readonly Linear10PercentEvery3Minutes: ILambdaDeploymentConfig = new DefaultLambdaDeploymentConfig('Linear10PercentEvery3Minutes');
+
+  /**
+   * Import a custom Deployment Configuration for a Lambda Deployment Group defined outside the CDK.
+   *
+   * @param scope the parent Construct for this new Construct
+   * @param id the logical ID of this new Construct
+   * @param props the properties of the referenced custom Deployment Configuration
+   * @returns a Construct representing a reference to an existing custom Deployment Configuration
+   */
+  public static import(scope: cdk.Construct, id: string, props: LambdaDeploymentConfigImportProps): ILambdaDeploymentConfig {
+    return new ImportedLambdaDeploymentConfig(scope, id, props);
+  }
+
+  private constructor() {
+    // nothing to do until CFN supports custom lambda deployment configurations
+  }
+}