feat(lambda): add alias to latest version through code hash

It is a common use case to define an alias for the latest version of a function. In order to do that, one needs to define a Version resource that points to the latest version and then associate an Alias with it.

This was not trivial to do so far. Now it is:

    fn.addAlias('foo')

This will define a lambda.Version with a name the derives from the hash of the lambda's source code and then define a lambda.Alias associated with this version object. Since the name of the version resource is based on the hash, when the code changes, a new version will be created automatically.

To support this, `lambda.Code.bind()` now returns an optional `codeHash` attribute. It is supported for `lambda.Code.fromAsset` and `lambda.Code.fromInline`, for which we can calculate the source hash based on the content.

Resolves #6750
Resolves #5334

Author: Elad Ben-Israel

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

@@ -49,6 +49,35 @@ to our CDK project directory. This is especially important when we want to share
 this construct through a library. Different programming languages will have
 different techniques for bundling resources into libraries.
 
+When using `fromAsset` or `fromInline`, you can obtain the hash of source
+through the `function.codeHash` property. This property will return `undefined`
+if the code hash cannot be calculated during synthesis (e.g. when using code
+from an S3 bucket).
+
+### Versions and Aliases
+
+You can define one or more
+[aliases](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html)
+for your AWS Lambda function. A Lambda alias is like a pointer to a specific
+Lambda function version. Users can access the function version using the alias
+ARN.
+
+To define an alias that points to the latest version of your function's code,
+you can use the `function.addAlias` method like so:
+
+```ts
+const alias = lambdaFunction.addAlias('latest');
+```
+
+This will define an alias that points to a
+[Version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html)
+resource that will get updated every time your lambda code changes based on your code's hash.
+
+> Automatically creating version objects based on the code's hash is only supported
+> for `lambda.Code.fromAsset` and `lambda.Code.fromInline`. Other types of code
+> providers require that you will maintain the `versionName` explicitly when you
+> define the alias (and update it manually when your code changes). 
+
 ### Layers
 
 The `lambda.LayerVersion` class can be used to define Lambda layers and manage

packages/@aws-cdk/aws-lambda/lib/alias.ts

@@ -20,28 +20,16 @@ export interface IAlias extends IFunction {
 }
 
 /**
- * Properties for a new Lambda alias
+ * Options for `lambda.Alias`.
  */
-export interface AliasProps extends EventInvokeConfigOptions {
+export interface AliasOptions extends EventInvokeConfigOptions {
   /**
    * Description for the alias
    *
    * @default No description
    */
   readonly description?: string;
 
-  /**
-   * Function version this alias refers to
-   *
-   * Use lambda.addVersion() to obtain a new lambda version to refer to.
-   */
-  readonly version: IVersion;
-
-  /**
-   * Name of this alias
-   */
-  readonly aliasName: string;
-
   /**
    * Additional versions with individual weights this alias points to
    *
@@ -69,6 +57,23 @@ export interface AliasProps extends EventInvokeConfigOptions {
   readonly provisionedConcurrentExecutions?: number;
 }
 
+/**
+ * Properties for a new Lambda alias
+ */
+export interface AliasProps extends AliasOptions {
+  /**
+   * Name of this alias
+   */
+  readonly aliasName: string;
+
+  /**
+   * Function version this alias refers to
+   *
+   * Use lambda.addVersion() to obtain a new lambda version to refer to.
+   */
+  readonly version: IVersion;
+}
+
 export interface AliasAttributes {
   readonly aliasName: string;
   readonly aliasVersion: IVersion;

packages/@aws-cdk/aws-lambda/lib/code.ts

@@ -1,6 +1,7 @@
 import * as s3 from '@aws-cdk/aws-s3';
 import * as s3_assets from '@aws-cdk/aws-s3-assets';
 import * as cdk from '@aws-cdk/core';
+import * as crypto from 'crypto';
 
 export abstract class Code {
   /**
@@ -104,13 +105,19 @@ export interface CodeConfig {
    * Inline code (mutually exclusive with `s3Location`).
    */
   readonly inlineCode?: string;
+
+  /**
+   * The hash of the lambda code (if applicable).
+   */
+  readonly codeHash?: string;
 }
 
 /**
  * Lambda code from an S3 archive.
  */
 export class S3Code extends Code {
   public readonly isInline = false;
+
   private bucketName: string;
 
   constructor(bucket: s3.IBucket, private key: string, private objectVersion?: string) {
@@ -139,6 +146,7 @@ export class S3Code extends Code {
  */
 export class InlineCode extends Code {
   public readonly isInline = true;
+  private readonly codeHash: string;
 
   constructor(private code: string) {
     super();
@@ -150,11 +158,14 @@ export class InlineCode extends Code {
     if (code.length > 4096) {
       throw new Error("Lambda source is too large, must be <= 4096 but is " + code.length);
     }
+
+    this.codeHash = crypto.createHash('sha256').update(code).digest('hex');
   }
 
   public bind(_scope: cdk.Construct): CodeConfig {
     return {
-      inlineCode: this.code
+      inlineCode: this.code,
+      codeHash: this.codeHash
     };
   }
 }
@@ -164,6 +175,7 @@ export class InlineCode extends Code {
  */
 export class AssetCode extends Code {
   public readonly isInline = false;
+
   private asset?: s3_assets.Asset;
 
   /**
@@ -187,6 +199,7 @@ export class AssetCode extends Code {
     }
 
     return {
+      codeHash: this.asset.sourceHash,
       s3Location: {
         bucketName: this.asset.s3BucketName,
         objectKey: this.asset.s3ObjectKey
@@ -246,6 +259,7 @@ export interface CfnParametersCodeProps {
  */
 export class CfnParametersCode extends Code {
   public readonly isInline = false;
+
   private _bucketNameParam?: cdk.CfnParameter;
   private _objectKeyParam?: cdk.CfnParameter;
 

packages/@aws-cdk/aws-lambda/lib/function.ts

@@ -4,6 +4,7 @@ import * as iam from '@aws-cdk/aws-iam';
 import * as logs from '@aws-cdk/aws-logs';
 import * as sqs from '@aws-cdk/aws-sqs';
 import { Construct, Duration, Fn, Lazy } from '@aws-cdk/core';
+import { Alias, AliasOptions } from './alias';
 import { Code, CodeConfig } from './code';
 import { EventInvokeConfigOptions } from './event-invoke-config';
 import { IEventSource } from './event-source';
@@ -414,6 +415,14 @@ export class Function extends FunctionBase {
 
   public readonly permissionsNode = this.node;
 
+  /**
+   * The hash of the AWS Lambda code.
+   *
+   * This only applies to `lambda.Code.fromAsset` and `lambda.Code.fromInline`.
+   * For other code types this will return `undefined`.
+   */
+  public readonly codeHash?: string;
+
   protected readonly canCreatePermissions = true;
 
   private readonly layers: ILayerVersion[] = [];
@@ -456,6 +465,7 @@ export class Function extends FunctionBase {
     verifyCodeConfig(code, props.runtime);
 
     this.deadLetterQueue = this.buildDeadLetterQueue(props);
+    this.codeHash = code.codeHash;
 
     const resource: CfnFunction = new CfnFunction(this, 'Resource', {
       functionName: this.physicalName,
@@ -557,26 +567,43 @@ export class Function extends FunctionBase {
    * Add a new version for this Lambda
    *
    * If you want to deploy through CloudFormation and use aliases, you need to
-   * add a new version (with a new name) to your Lambda every time you want
-   * to deploy an update. An alias can then refer to the newly created Version.
+   * add a new version (with a new name) to your Lambda every time you want to
+   * deploy an update. An alias can then refer to the newly created Version.
    *
    * All versions should have distinct names, and you should not delete versions
    * as long as your Alias needs to refer to them.
    *
-   * @param name A unique name for this version
-   * @param codeSha256 The SHA-256 hash of the most recently deployed Lambda source code, or
-   *  omit to skip validation.
+   * @param name A unique name for this version. The version name is not
+   * specified, a name will automatically be generated based on the code hash of
+   * the lambda. This means that a new version will automatically be created
+   * every time the lambda code changes. This is only supported for
+   * `lambda.Code.fromAsset` and `lambda.Code.fromInline`. Otherwise `name` is
+   * required.
+   *
+   * @param codeSha256 The SHA-256 hash of the most recently deployed Lambda
+   *  source code, or omit to skip validation.
    * @param description A description for this version.
-   * @param provisionedExecutions A provisioned concurrency configuration for a function's version.
-   * @param asyncInvokeConfig configuration for this version when it is invoked asynchronously.
+   * @param provisionedExecutions A provisioned concurrency configuration for a
+   * function's version.
+   * @param asyncInvokeConfig configuration for this version when it is invoked
+   * asynchronously.
    * @returns A new Version object.
    */
   public addVersion(
-    name: string,
+    name?: string,
     codeSha256?: string,
     description?: string,
     provisionedExecutions?: number,
     asyncInvokeConfig: EventInvokeConfigOptions = {}): Version {
+
+    if (!name) {
+      if (!this.codeHash) {
+        throw new Error(`version name must be provided because the the lambda code hash cannot be calculated. Only "lambda.Code.fromAsset" and "lambda.Code.fromInline" support code hash`);
+      }
+
+      name = this.codeHash;
+    }
+
     return new Version(this, 'Version' + name, {
       lambda: this,
       codeSha256,
@@ -586,6 +613,23 @@ export class Function extends FunctionBase {
     });
   }
 
+  /**
+   * Defines an alias for this function associated with the latest version of
+   * the function.
+   *
+   * @param name The name for this alias.
+   * @param options Options for the alias. If this function uses assets or
+   * inline code, do not specify `versionName`. Otherwise, `versionName` is
+   * required.
+   */
+  public addAlias(name: string, options: AddAliasOptions = { }) {
+    return new Alias(this, `Alias${name}`, {
+      version: this.addVersion(options.versionName),
+      aliasName: name,
+      ...options
+    });
+  }
+
   /**
    * The LogGroup where the Lambda function's logs are made available.
    *
@@ -750,3 +794,24 @@ export function verifyCodeConfig(code: CodeConfig, runtime: Runtime) {
     throw new Error(`Inline source not allowed for ${runtime.name}`);
   }
 }
+
+/**
+ * Options for `function.addAlias`.
+ */
+export interface AddAliasOptions extends AliasOptions {
+  /**
+   * An explicit name for this version.
+   *
+   * It is not recommeneded to specify a name for the version because you will
+   * need to explicitly update it every time your lambda code changes. If you
+   * leave this undefined, the framework will automatically create a new version
+   * every time your lambda code changes.
+   *
+   * @default - a name will automatically be generated based on the code hash of
+   * the lambda. This means that a new version will automatically be created
+   * every time the lambda code changes. This is only supported for
+   * `lambda.Code.fromAsset` and `lambda.Code.fromInline`. Otherwise `name` is
+   * required.
+   */
+  readonly versionName?: string;
+}