feat(lambda): function.addAlias() simplifies Alias creation (#20034)

Deprecate `version.addAlias()` in favor of a new method called
`function.addAlias()`.

- When Aliases get created underneath Versions, there's the risk
  that it's `currentVersion` whose logical ID changes on every
  deployment, causing a (probably failing) replacement of the `Alias`
  on every function update.
- The most common use for `function.currentVersion` is to create an
  `Alias` for a Function. Might as well take out the middle man.


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

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

@@ -336,7 +336,7 @@ const fn = new lambda.Function(this, 'MyFunction', {
   code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
 });
 
-fn.currentVersion.addAlias('live');
+fn.addAlias('live');
 ```
 
 ## Function URL
@@ -687,10 +687,7 @@ You can use Application AutoScaling to automatically configure the provisioned c
 import * as autoscaling from '@aws-cdk/aws-autoscaling';
 
 declare const fn: lambda.Function;
-const alias = new lambda.Alias(this, 'Alias', {
-  aliasName: 'prod',
-  version: fn.latestVersion,
-});
+const alias = fn.addAlias('prod');
 
 // Create AutoScaling target
 const as = alias.addAutoScaling({ maxCapacity: 50 });

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

@@ -26,6 +26,8 @@ import { Runtime } from './runtime';
 // keep this import separate from other imports to reduce chance for merge conflicts with v2-main
 // eslint-disable-next-line
 import { LogRetentionRetryOptions } from './log-retention';
+import { AliasOptions, Alias } from './alias';
+import { addAlias } from './util';
 
 /**
  * X-Ray Tracing Modes (https://docs.aws.amazon.com/lambda/latest/dg/API_TracingConfig.html)
@@ -959,6 +961,31 @@ export class Function extends FunctionBase {
     });
   }
 
+  /**
+   * Defines an alias for this function.
+   *
+   * The alias will automatically be updated to point to the latest version of
+   * the function as it is being updated during a deployment.
+   *
+   * ```ts
+   * declare const fn: lambda.Function;
+   *
+   * fn.addAlias('Live');
+   *
+   * // Is equivalent to
+   *
+   * new lambda.Alias(this, 'AliasLive', {
+   *   aliasName: 'Live',
+   *   version: fn.currentVersion,
+   * });
+   *
+   * @param aliasName The name of the alias
+   * @param options Alias options
+   */
+  public addAlias(aliasName: string, options?: AliasOptions): Alias {
+    return addAlias(this, this.currentVersion, aliasName, options);
+  }
+
   /**
    * The LogGroup where the Lambda function's logs are made available.
    *

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

@@ -30,6 +30,8 @@ export interface IVersion extends IFunction {
    * Defines an alias for this version.
    * @param aliasName The name of the alias
    * @param options Alias options
+   *
+   * @deprecated Calling `addAlias` on a `Version` object will cause the Alias to be replaced on every function update. Call `function.addAlias()` or `new Alias()` instead.
    */
   addAlias(aliasName: string, options?: AliasOptions): Alias;
 }
@@ -244,6 +246,7 @@ export class Version extends QualifiedFunctionBase implements IVersion {
    * Defines an alias for this version.
    * @param aliasName The name of the alias (e.g. "live")
    * @param options Alias options
+   * @deprecated Calling `addAlias` on a `Version` object will cause the Alias to be replaced on every function update. Call `function.addAlias()` or `new Alias()` instead.
    */
   public addAlias(aliasName: string, options: AliasOptions = {}): Alias {
     return addAlias(this, this, aliasName, options);

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

@@ -547,6 +547,18 @@ describe('function', () => {
         Annotations.fromStack(stack).hasNoWarning('/Default/MyLambda/$LATEST', Match.stringLikeRegexp(warningMessage));
       });
 
+      test('function.addAlias', () => {
+        // WHEN
+        fn.addAlias('prod');
+
+        // THEN
+        Template.fromStack(stack).hasResourceProperties('AWS::Lambda::Alias', {
+          Name: 'prod',
+          FunctionName: { Ref: 'MyLambdaCCE802FB' },
+          FunctionVersion: { 'Fn::GetAtt': ['MyLambdaCurrentVersionE7A382CC60ef151b20ae483ee1018f73f30bc10e', 'Version'] },
+        });
+      });
+
       describe('permission on alias', () => {
         test('of current version', () => {
           // GIVEN

packages/@aws-cdk/aws-lambda/test/lambda-version.test.ts

@@ -1,6 +1,7 @@
 import { Template } from '@aws-cdk/assertions';
 import * as cdk from '@aws-cdk/core';
 import * as lambda from '../lib';
+import { testDeprecated } from '@aws-cdk/cdk-build-tools';
 
 describe('lambda version', () => {
   test('can import a Lambda version by ARN', () => {
@@ -103,7 +104,7 @@ describe('lambda version', () => {
     });
   });
 
-  test('addAlias can be used to add an alias that points to a version', () => {
+  testDeprecated('addAlias can be used to add an alias that points to a version', () => {
     // GIVEN
     const stack = new cdk.Stack();
     const fn = new lambda.Function(stack, 'Fn', {

packages/@aws-cdk/aws-lambda/test/singleton-lambda.test.ts

@@ -4,6 +4,7 @@ import * as iam from '@aws-cdk/aws-iam';
 import * as s3 from '@aws-cdk/aws-s3';
 import * as cdk from '@aws-cdk/core';
 import * as lambda from '../lib';
+import { testDeprecated } from '@aws-cdk/cdk-build-tools';
 
 describe('singleton lambda', () => {
   test('can add same singleton Lambda multiple times, only instantiated once in template', () => {
@@ -241,7 +242,7 @@ describe('singleton lambda', () => {
     expect(singleton.runtime).toStrictEqual(lambda.Runtime.PYTHON_3_9);
   });
 
-  test('current version of a singleton function', () => {
+  testDeprecated('current version of a singleton function', () => {
     // GIVEN
     const stack = new cdk.Stack();
     const singleton = new lambda.SingletonFunction(stack, 'Singleton', {