feat(rds): cluster retention, reference KMS key by object (#2063)

Add control over DeletionPolicy and UpdateReplacePolicy, both defaulting to Retain
to avoid data loss.

Reference encryption key reference with key interface.

BREAKING CHANGE: Replaced `kmsKeyArn: string` by `kmsKey: kms.IEncryptionKey` in `DatabaseClusterProps`

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

@@ -68,7 +68,7 @@ When the master password is generated and stored in AWS Secrets Manager, it can
 
 Rotation of the master password is also supported for an existing cluster:
 ```ts
-new rds.RotationSingleUser(stack, 'Rotation', {
+new RotationSingleUser(stack, 'Rotation', {
     secret: importedSecret,
     engine: DatabaseEngine.Oracle,
     target: importedCluster,

packages/@aws-cdk/aws-rds/lib/cluster.ts

@@ -1,4 +1,5 @@
 import ec2 = require('@aws-cdk/aws-ec2');
+import kms = require('@aws-cdk/aws-kms');
 import secretsmanager = require('@aws-cdk/aws-secretsmanager');
 import cdk = require('@aws-cdk/cdk');
 import { IClusterParameterGroup } from './cluster-parameter-group';
@@ -72,9 +73,19 @@ export interface DatabaseClusterProps {
   defaultDatabaseName?: string;
 
   /**
-   * ARN of KMS key if you want to enable storage encryption
+   * Whether to enable storage encryption
+   *
+   * @default false
+   */
+  storageEncrypted?: boolean
+
+  /**
+   * The KMS key for storage encryption. If specified `storageEncrypted`
+   * will be set to `true`.
+   *
+   * @default default master key
    */
-  kmsKeyArn?: string;
+  kmsKey?: kms.IEncryptionKey;
 
   /**
    * A daily time range in 24-hours UTC format in which backups preferably execute.
@@ -91,6 +102,14 @@ export interface DatabaseClusterProps {
    * @default No parameter group
    */
   parameterGroup?: IClusterParameterGroup;
+
+  /**
+   * The CloudFormation policy to apply when the cluster and its instances
+   * are removed from the stack or replaced during an update.
+   *
+   * @default Retain
+   */
+  deleteReplacePolicy?: cdk.DeletionPolicy
 }
 
 /**
@@ -261,10 +280,14 @@ export class DatabaseCluster extends DatabaseClusterBase implements IDatabaseClu
       preferredMaintenanceWindow: props.preferredMaintenanceWindow,
       databaseName: props.defaultDatabaseName,
       // Encryption
-      kmsKeyId: props.kmsKeyArn,
-      storageEncrypted: props.kmsKeyArn ? true : false,
+      kmsKeyId: props.kmsKey && props.kmsKey.keyArn,
+      storageEncrypted: props.kmsKey ? true : props.storageEncrypted
     });
 
+    const deleteReplacePolicy = props.deleteReplacePolicy || cdk.DeletionPolicy.Retain;
+    cluster.options.deletionPolicy = deleteReplacePolicy;
+    cluster.options.updateReplacePolicy = deleteReplacePolicy;
+
     this.clusterIdentifier = cluster.ref;
     this.clusterEndpoint = new Endpoint(cluster.dbClusterEndpointAddress, cluster.dbClusterEndpointPort);
     this.readerEndpoint = new Endpoint(cluster.dbClusterReadEndpointAddress, cluster.dbClusterEndpointPort);
@@ -303,6 +326,9 @@ export class DatabaseCluster extends DatabaseClusterBase implements IDatabaseClu
         dbSubnetGroupName: subnetGroup.ref,
       });
 
+      instance.options.deletionPolicy = deleteReplacePolicy;
+      instance.options.updateReplacePolicy = deleteReplacePolicy;
+
       // We must have a dependency on the NAT gateway provider here to create
       // things in the right order.
       instance.node.addDependency(internetConnected);

packages/@aws-cdk/aws-rds/test/integ.cluster-rotation.lit.expected.json

@@ -650,7 +650,6 @@
             ]
           ]
         },
-        "StorageEncrypted": false,
         "VpcSecurityGroupIds": [
           {
             "Fn::GetAtt": [
@@ -659,7 +658,9 @@
             ]
           }
         ]
-      }
+      },
+      "DeletionPolicy": "Retain",
+      "UpdateReplacePolicy": "Retain"
     },
     "DatabaseInstance1844F58FD": {
       "Type": "AWS::RDS::DBInstance",
@@ -677,7 +678,9 @@
         "VPCPrivateSubnet1DefaultRouteAE1D6490",
         "VPCPrivateSubnet2DefaultRouteF4F5CFD2",
         "VPCPrivateSubnet3DefaultRoute27F311AE"
-      ]
+      ],
+      "DeletionPolicy": "Retain",
+      "UpdateReplacePolicy": "Retain"
     },
     "DatabaseInstance2AA380DEE": {
       "Type": "AWS::RDS::DBInstance",
@@ -695,7 +698,9 @@
         "VPCPrivateSubnet1DefaultRouteAE1D6490",
         "VPCPrivateSubnet2DefaultRouteF4F5CFD2",
         "VPCPrivateSubnet3DefaultRoute27F311AE"
-      ]
+      ],
+      "DeletionPolicy": "Retain",
+      "UpdateReplacePolicy": "Retain"
     },
     "DatabaseRotationSecurityGroup17736B63": {
       "Type": "AWS::EC2::SecurityGroup",

packages/@aws-cdk/aws-rds/test/integ.cluster.expected.json

@@ -484,7 +484,9 @@
             ]
           }
         ]
-      }
+      },
+      "DeletionPolicy": "Retain",
+      "UpdateReplacePolicy": "Retain"
     },
     "DatabaseInstance1844F58FD": {
       "Type": "AWS::RDS::DBInstance",
@@ -502,7 +504,9 @@
       "DependsOn": [
         "VPCPublicSubnet1DefaultRoute91CEF279",
         "VPCPublicSubnet2DefaultRouteB7481BBA"
-      ]
+      ],
+      "DeletionPolicy": "Retain",
+      "UpdateReplacePolicy": "Retain"
     },
     "DatabaseInstance2AA380DEE": {
       "Type": "AWS::RDS::DBInstance",
@@ -520,7 +524,9 @@
       "DependsOn": [
         "VPCPublicSubnet1DefaultRoute91CEF279",
         "VPCPublicSubnet2DefaultRouteB7481BBA"
-      ]
+      ],
+      "DeletionPolicy": "Retain",
+      "UpdateReplacePolicy": "Retain"
     }
   }
-}
+}

packages/@aws-cdk/aws-rds/test/integ.cluster.ts

@@ -28,7 +28,7 @@ const cluster = new DatabaseCluster(stack, 'Database', {
     vpc
   },
   parameterGroup: params,
-  kmsKeyArn: kmsKey.keyArn,
+  kmsKey,
 });
 
 cluster.connections.allowDefaultPortFromAnyIpv4('Open to the world');

packages/@aws-cdk/aws-rds/test/test.cluster.ts

@@ -1,5 +1,6 @@
-import { expect, haveResource } from '@aws-cdk/assert';
+import { expect, haveResource, ResourcePart } from '@aws-cdk/assert';
 import ec2 = require('@aws-cdk/aws-ec2');
+import kms = require('@aws-cdk/aws-kms');
 import cdk = require('@aws-cdk/cdk');
 import { Test } from 'nodeunit';
 import { ClusterParameterGroup, DatabaseCluster, DatabaseClusterEngine } from '../lib';
@@ -25,12 +26,21 @@ export = {
 
     // THEN
     expect(stack).to(haveResource('AWS::RDS::DBCluster', {
-      Engine: "aurora",
-      DBSubnetGroupName: { Ref: "DatabaseSubnets56F17B9A" },
-      MasterUsername: "admin",
-      MasterUserPassword: "tooshort",
-      VpcSecurityGroupIds: [ {"Fn::GetAtt": ["DatabaseSecurityGroup5C91FDCB", "GroupId"]}]
-    }));
+      Properties: {
+        Engine: "aurora",
+        DBSubnetGroupName: { Ref: "DatabaseSubnets56F17B9A" },
+        MasterUsername: "admin",
+        MasterUserPassword: "tooshort",
+        VpcSecurityGroupIds: [ {"Fn::GetAtt": ["DatabaseSecurityGroup5C91FDCB", "GroupId"]}]
+      },
+      DeletionPolicy: 'Retain',
+      UpdateReplacePolicy: 'Retain'
+    }, ResourcePart.CompleteDefinition));
+
+    expect(stack).to(haveResource('AWS::RDS::DBInstance', {
+      DeletionPolicy: 'Retain',
+      UpdateReplacePolicy: 'Retain'
+    }, ResourcePart.CompleteDefinition));
 
     test.done();
   },
@@ -232,6 +242,37 @@ export = {
       }
     }));
 
+    test.done();
+  },
+
+  'create an encrypted cluster with custom KMS key'(test: Test) {
+    // GIVEN
+    const stack = testStack();
+    const vpc = new ec2.VpcNetwork(stack, 'VPC');
+
+    // WHEN
+    new DatabaseCluster(stack, 'Database', {
+      engine: DatabaseClusterEngine.AuroraMysql,
+      masterUser: {
+        username: 'admin'
+      },
+      instanceProps: {
+        instanceType: new ec2.InstanceTypePair(ec2.InstanceClass.Burstable2, ec2.InstanceSize.Small),
+        vpc
+      },
+      kmsKey: new kms.EncryptionKey(stack, 'Key')
+    });
+
+    // THEN
+    expect(stack).to(haveResource('AWS::RDS::DBCluster', {
+      KmsKeyId: {
+        'Fn::GetAtt': [
+          'Key961B73FD',
+          'Arn'
+        ]
+      }
+    }));
+
     test.done();
   }
 };