feat(lambda): currentVersion, version.addAlias()

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

@@ -49,6 +49,69 @@ 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 use
+[versions](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html)
+to manage the deployment of your AWS Lambda functions. For example, you can
+publish a new version of a function for beta testing without affecting users of
+the stable production version.
+
+The function version includes the following information:
+
+- The function code and all associated dependencies.
+- The Lambda runtime that executes the function.
+- All of the function settings, including the environment variables.
+- A unique Amazon Resource Name (ARN) to identify this version of the function.
+
+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.
+
+The `fn.currentVersion` property can be used to obtain a `lambda.Version`
+resource that represents the AWS Lambda function defined in your application.
+Any change to your function's code or configuration will result in the creation
+of a new version resource. You can specify options for this version through the
+`currentVersionOptions` property.
+
+> The `currentVersion` property is only supported when your AWS Lambda function
+> uses either `lambda.Code.fromAsset` or `lambda.Code.fromInline`. Other types
+> of code providers (such as `lambda.Code.fromBucket`) require that you define a
+> `lambda.Version` resource directly since the CDK is unable to determine if
+> their contents had changed.
+
+The `version.addAlias()` method can be used to define an AWS Lambda alias that
+points to a specific version.
+
+The following example defines an alias named `live` which will always point to a
+version that represents the function as defined in your CDK app. When you change
+your lambda code or configuration, a new resource will be created. You can
+specify options for the current version through the `currentVersionOptions`
+property.
+
+```ts
+const fn = new lambda.Function(this, 'MyFunction', {
+  currentVersionOptions: {
+    removalPolicy: RemovalPolicy.RETAIN, // retain old versions
+    retryAttempts: 1                     // async retry attempts
+  }
+});
+
+fn.currentVersion.addAlias('live');
+```
+
+> NOTE: The `fn.latestVersion` property returns a `lambda.IVersion` which
+> represents the `$LATEST` pseudo-version. Most AWS services require a specific
+> AWS Lambda version, and won't allow you to use `$LATEST`. Therefore, you would
+> normally want to use `lambda.currentVersion`.
+
 ### 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/function-base.ts

@@ -2,12 +2,14 @@ import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import { ConstructNode, IResource, Resource } from '@aws-cdk/core';
+import { AliasOptions } from './alias';
 import { EventInvokeConfig, EventInvokeConfigOptions } from './event-invoke-config';
 import { IEventSource } from './event-source';
 import { EventSourceMapping, EventSourceMappingOptions } from './event-source-mapping';
 import { IVersion } from './lambda-version';
 import { CfnPermission } from './lambda.generated';
 import { Permission } from './permission';
+import { addAlias } from './util';
 
 export interface IFunction extends IResource, ec2.IConnectable, iam.IGrantable {
 
@@ -39,6 +41,13 @@ export interface IFunction extends IResource, ec2.IConnectable, iam.IGrantable {
 
   /**
    * The `$LATEST` version of this function.
+   *
+   * Note that this is reference to a non-specific AWS Lambda version, which
+   * means the function this version refers to can return different results in
+   * different invocations.
+   *
+   * To obtain a reference to an explicit version which references the current
+   * function configuration, use `lambdaFunction.currentVersion` instead.
    */
   readonly latestVersion: IVersion;
 
@@ -102,7 +111,7 @@ export interface IFunction extends IResource, ec2.IConnectable, iam.IGrantable {
   /**
    * Configures options for asynchronous invocation.
    */
-  configureAsyncInvoke(options: EventInvokeConfigOptions): void
+  configureAsyncInvoke(options: EventInvokeConfigOptions): void;
 }
 
 /**
@@ -235,7 +244,7 @@ export abstract class FunctionBase extends Resource implements IFunction {
   }
 
   public get latestVersion(): IVersion {
-    // Dynamic to avoid invinite recursion when creating the LatestVersion instance...
+    // Dynamic to avoid infinite recursion when creating the LatestVersion instance...
     return new LatestVersion(this);
   }
 
@@ -393,4 +402,8 @@ class LatestVersion extends FunctionBase implements IVersion {
   public get role() {
     return this.lambda.role;
   }
+
+  public addAlias(aliasName: string, options: AliasOptions = {}) {
+    return addAlias(this, this, aliasName, options);
+  }
 }

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

@@ -0,0 +1,23 @@
+import { CfnResource, Stack } from "@aws-cdk/core";
+import * as crypto from 'crypto';
+import { Function as LambdaFunction } from "./function";
+
+export function calculateFunctionHash(fn: LambdaFunction) {
+  const stack = Stack.of(fn);
+
+  const functionResource = fn.node.defaultChild as CfnResource;
+
+  // render the cloudformation resource from this function
+  const config = stack.resolve((functionResource as any)._toCloudFormation());
+
+  const hash = crypto.createHash('md5');
+  hash.update(JSON.stringify(config));
+
+  return hash.digest('hex');
+}
+
+export function trimFromStart(s: string, maxLength: number) {
+  const desiredLength = Math.min(maxLength, s.length);
+  const newStart = s.length - desiredLength;
+  return s.substring(newStart);
+}

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

@@ -3,12 +3,13 @@ import * as ec2 from '@aws-cdk/aws-ec2';
 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 { CfnResource, Construct, Duration, Fn, Lazy, Stack } from '@aws-cdk/core';
 import { Code, CodeConfig } from './code';
 import { EventInvokeConfigOptions } from './event-invoke-config';
 import { IEventSource } from './event-source';
 import { FunctionAttributes, FunctionBase, IFunction } from './function-base';
-import { Version } from './lambda-version';
+import { calculateFunctionHash, trimFromStart } from './function-hash';
+import { Version, VersionOptions } from './lambda-version';
 import { CfnFunction } from './lambda.generated';
 import { ILayerVersion } from './layers';
 import { LogRetention } from './log-retention';
@@ -224,6 +225,13 @@ export interface FunctionOptions extends EventInvokeConfigOptions {
    * @default - A new role is created.
    */
   readonly logRetentionRole?: iam.IRole;
+
+  /**
+   * Options for the `lambda.Version` resource automatically created by the
+   * `fn.currentVersion` method.
+   * @default - default options as described in `VersionOptions`
+   */
+  readonly currentVersionOptions?: VersionOptions;
 }
 
 export interface FunctionProps extends FunctionOptions {
@@ -266,6 +274,28 @@ export interface FunctionProps extends FunctionOptions {
  * library.
  */
 export class Function extends FunctionBase {
+
+  /**
+   * Returns a `lambda.Version` which represents the current version of this
+   * Lambda function. A new version will be created every time the function's
+   * configuration changes.
+   *
+   * You can specify options for this version using the `currentVersionOptions`
+   * prop when initializing the `lambda.Function`.
+   */
+  public get currentVersion(): Version {
+    if (this._currentVersion) {
+      return this._currentVersion;
+    }
+
+    this._currentVersion = new Version(this, `CurrentVersion`, {
+      lambda: this,
+      ...this.currentVersionOptions
+    });
+
+    return this._currentVersion;
+  }
+
   public static fromFunctionArn(scope: Construct, id: string, functionArn: string): IFunction {
     return Function.fromFunctionAttributes(scope, id, { functionArn });
   }
@@ -425,6 +455,9 @@ export class Function extends FunctionBase {
    */
   private readonly environment: { [key: string]: string };
 
+  private readonly currentVersionOptions?: VersionOptions;
+  private _currentVersion?: Version;
+
   constructor(scope: Construct, id: string, props: FunctionProps) {
     super(scope, id, {
       physicalName: props.functionName,
@@ -520,6 +553,8 @@ export class Function extends FunctionBase {
         retryAttempts: props.retryAttempts,
       });
     }
+
+    this.currentVersionOptions = props.currentVersionOptions;
   }
 
   /**
@@ -557,26 +592,35 @@ 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.
+   * @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.
+   *
+   * @deprecated This method will create an AWS::Lambda::Version resource which
+   * snapshots the AWS Lambda function *at the time of its creation* and it
+   * won't get updated when the function changes. Instead, use
+   * `this.currentVersion` to obtain a reference to a version resource that gets
+   * automatically recreated when the function configuration (or code) changes.
    */
   public addVersion(
     name: string,
     codeSha256?: string,
     description?: string,
     provisionedExecutions?: number,
     asyncInvokeConfig: EventInvokeConfigOptions = {}): Version {
+
     return new Version(this, 'Version' + name, {
       lambda: this,
       codeSha256,
@@ -607,14 +651,47 @@ export class Function extends FunctionBase {
     return this._logGroup;
   }
 
+  protected prepare() {
+    super.prepare();
+
+    // if we have a current version resource, override it's logical id
+    // so that it includes the hash of the function code and it's configuration.
+    if (this._currentVersion) {
+      const stack = Stack.of(this);
+      const cfn = this._currentVersion.node.defaultChild as CfnResource;
+      const originalLogicalId: string = stack.resolve(cfn.logicalId);
+
+      const hash = calculateFunctionHash(this);
+
+      const logicalId = trimFromStart(originalLogicalId, 255 - 32);
+      cfn.overrideLogicalId(`${logicalId}${hash}`);
+    }
+  }
+
   private renderEnvironment() {
     if (!this.environment || Object.keys(this.environment).length === 0) {
       return undefined;
     }
 
-    return {
-      variables: this.environment
-    };
+    // for backwards compatibility we do not sort environment variables in case
+    // _currentVersion is not defined. otherwise, this would have invalidated
+    // the template, and for example, may cause unneeded updates for nested
+    // stacks.
+    if (!this._currentVersion) {
+      return {
+        variables: this.environment
+      };
+    }
+
+    // sort environment so the hash of the function used to create
+    // `currentVersion` is not affected by key order (this is how lambda does
+    // it).
+    const variables: { [key: string]: string } = { };
+    for (const key of Object.keys(this.environment).sort()) {
+      variables[key] = this.environment[key];
+    }
+
+    return { variables };
   }
 
   /**
@@ -749,4 +826,4 @@ export function verifyCodeConfig(code: CodeConfig, runtime: Runtime) {
   if (code.inlineCode && !runtime.supportsInlineCode) {
     throw new Error(`Inline source not allowed for ${runtime.name}`);
   }
-}
+}