feat(kms): Allow opting out of "Retain" deletion policy (#1685)

Gives the user control over whether the key should be retained or
scheduled for deletion when it is removed from the stack (or the stack
is deleted). This is convenient in particular for integration tests, to
avoid accumulating garbage over successive runs.

packages/@aws-cdk/aws-kms/lib/key.ts

@@ -106,6 +106,14 @@ export interface EncryptionKeyProps {
    * administer the key will be created.
    */
   policy?: PolicyDocument;
+
+  /**
+   * Whether the encryption key should be retained when it is removed from the Stack. This is useful when one wants to
+   * retain access to data that was encrypted with a key that is being retired.
+   *
+   * @default true
+   */
+  retain?: boolean;
 }
 
 /**
@@ -155,7 +163,9 @@ export class EncryptionKey extends EncryptionKeyBase {
     });
 
     this.keyArn = resource.keyArn;
-    resource.options.deletionPolicy = DeletionPolicy.Retain;
+    resource.options.deletionPolicy = props.retain === false
+                                    ? DeletionPolicy.Delete
+                                    : DeletionPolicy.Retain;
   }
 
   /**

packages/@aws-cdk/aws-kms/test/integ.key-sharing.lit.expected.json

@@ -46,7 +46,7 @@
             "Version": "2012-10-17"
           }
         },
-        "DeletionPolicy": "Retain"
+        "DeletionPolicy": "Delete"
       },
       "MyKeyAlias1B45D9DA": {
         "Type": "AWS::KMS::Alias",

packages/@aws-cdk/aws-kms/test/integ.key-sharing.lit.ts

@@ -13,7 +13,7 @@ class KeyStack extends cdk.Stack {
 
   constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
     super(scope, id, props);
-    this.key = new kms.EncryptionKey(this, 'MyKey');
+    this.key = new kms.EncryptionKey(this, 'MyKey', { retain: false });
   }
 }
 

packages/@aws-cdk/aws-kms/test/integ.key.expected.json

@@ -55,7 +55,7 @@
           "Version": "2012-10-17"
         }
       },
-      "DeletionPolicy": "Retain"
+      "DeletionPolicy": "Delete"
     },
     "MyKeyAlias1B45D9DA": {
       "Type": "AWS::KMS::Alias",

packages/@aws-cdk/aws-kms/test/integ.key.ts

@@ -6,7 +6,7 @@ const app = new App();
 
 const stack = new Stack(app, `aws-cdk-kms-1`);
 
-const key = new EncryptionKey(stack, 'MyKey');
+const key = new EncryptionKey(stack, 'MyKey', { retain: false });
 
 key.addToResourcePolicy(new PolicyStatement()
   .addAllResources()

packages/@aws-cdk/aws-kms/test/test.key.ts

@@ -1,4 +1,4 @@
-import { exactlyMatchTemplate, expect } from '@aws-cdk/assert';
+import { exactlyMatchTemplate, expect, haveResource, ResourcePart } from '@aws-cdk/assert';
 import { PolicyDocument, PolicyStatement } from '@aws-cdk/aws-iam';
 import { App, Stack, Tag } from '@aws-cdk/cdk';
 import { Test } from 'nodeunit';
@@ -64,6 +64,16 @@ export = {
     test.done();
   },
 
+  'default with no retention'(test: Test) {
+    const app = new App();
+    const stack = new Stack(app, 'TestStack');
+
+    new EncryptionKey(stack, 'MyKey', { retain: false });
+
+    expect(app.synthesizeStack(stack.name)).to(haveResource('AWS::KMS::Key', { DeletionPolicy: "Delete" }, ResourcePart.CompleteDefinition));
+    test.done();
+  },
+
   'default with some permission'(test: Test) {
     const app = new App();
     const stack = new Stack(app, 'Test');