feat(lambda): layer version removal policy (#12792)

closes #12718

Allows providing a removal policy for the  `Lambda::LayerVersion` L2 construct to retain previous layer versions when the layer is updated. When a value is not provided, the default CloudFormation behavior is used, which is to delete the previous version defined in the stack.

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

@@ -189,6 +189,17 @@ granting permissions to other AWS accounts or organizations.
 
 [Example of Lambda Layer usage](test/integ.layer-version.lit.ts)
 
+By default, updating a layer creates a new layer version, and CloudFormation will delete the old version as part of the stack update.
+
+Alternatively, a removal policy can be used to retain the old version:
+
+```ts
+import { LayerVersion } from '@aws-cdk/aws-lambda';
+new LayerVersion(this, 'MyLayer', {
+  removalPolicy: RemovalPolicy.RETAIN
+});
+```
+
 ## Event Rule Target
 
 You can use an AWS Lambda function as a target for an Amazon CloudWatch event

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

@@ -1,4 +1,4 @@
-import { IResource, Resource } from '@aws-cdk/core';
+import { IResource, RemovalPolicy, Resource } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { Code } from './code';
 import { CfnLayerVersion, CfnLayerVersionPermission } from './lambda.generated';
@@ -28,6 +28,14 @@ export interface LayerVersionOptions {
    * @default - A name will be generated.
    */
   readonly layerVersionName?: string;
+
+  /**
+   * Whether to retain this version of the layer when a new version is added
+   * or when the stack is deleted.
+   *
+   * @default RemovalPolicy.DESTROY
+   */
+  readonly removalPolicy?: RemovalPolicy;
 }
 
 export interface LayerVersionProps extends LayerVersionOptions {
@@ -198,6 +206,10 @@ export class LayerVersion extends LayerVersionBase {
       licenseInfo: props.license,
     });
 
+    if (props.removalPolicy) {
+      resource.applyRemovalPolicy(props.removalPolicy);
+    }
+
     props.code.bindToResource(resource, {
       resourceProperty: 'Content',
     });

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

@@ -86,4 +86,21 @@ describe('layers', () => {
       },
     }, ResourcePart.CompleteDefinition);
   });
+
+  test('creating a layer with a removal policy', () => {
+    // GIVEN
+    const stack = new cdk.Stack();
+
+    // WHEN
+    new lambda.LayerVersion(stack, 'layer', {
+      code: lambda.Code.fromAsset(path.join(__dirname, 'layer-code')),
+      removalPolicy: cdk.RemovalPolicy.RETAIN,
+    });
+
+    // THEN
+    expect(canonicalizeTemplate(SynthUtils.toCloudFormation(stack))).toHaveResource('AWS::Lambda::LayerVersion', {
+      UpdateReplacePolicy: 'Retain',
+      DeletionPolicy: 'Retain',
+    }, ResourcePart.CompleteDefinition);
+  });
 });