fix(rds): customizing secret results in unusable password and lost attachment

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

@@ -23,7 +23,7 @@ your instances will be launched privately or publicly:
 ```ts
 const cluster = new rds.DatabaseCluster(this, 'Database', {
   engine: rds.DatabaseClusterEngine.auroraMysql({ version: rds.AuroraMysqlEngineVersion.VER_2_08_1 }),
-  credentials: rds.Credentials.fromUsername('clusteradmin'), // Optional - will default to admin
+  credentials: rds.Credentials.fromGeneratedPassword('clusteradmin'), // Optional - will default to admin
   instanceProps: {
     // optional , defaults to t3.medium
     instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.SMALL),
@@ -70,7 +70,7 @@ const instance = new rds.DatabaseInstance(this, 'Instance', {
   engine: rds.DatabaseInstanceEngine.oracleSe2({ version: rds.OracleEngineVersion.VER_19_0_0_0_2020_04_R1 }),
   // optional, defaults to m5.large
   instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.SMALL),
-  credentials: rds.Credentials.fromUsername('syscdk'), // Optional - will default to admin
+  credentials: rds.Credentials.fromGeneratedPassword('syscdk'), // Optional - will default to admin
   vpc,
   vpcSubnets: {
     subnetType: ec2.SubnetType.PRIVATE
@@ -146,13 +146,13 @@ const engine = rds.DatabaseInstanceEngine.postgres({ version: rds.PostgresEngine
 new rds.DatabaseInstance(this, 'InstanceWithUsername', {
   engine,
   vpc,
-  credentials: rds.Credentials.fromUsername('postgres'), // Creates an admin user of postgres with a generated password
+  credentials: rds.Credentials.fromGeneratedPassword('postgres'), // Creates an admin user of postgres with a generated password
 });
 
-new rds.DatabaseInstance(this, 'InstanceWithUsernameAndPassword', {
+new rds.DatabaseInstance(this, 'InstanceWithPassword', {
   engine,
   vpc,
-  credentials: rds.Credentials.fromUsername('postgres', { password: SecretValue.ssmSecure('/dbPassword', 1) }), // Use password from SSM
+  credentials: rds.Credentials.fromPassword('admin', SecretValue.ssmSecure('/dbPassword', '1')), // Use password from SSM
 });
 
 const mySecret = secretsmanager.Secret.fromSecretName(this, 'DBSecret', 'myDBLoginInfo');
@@ -412,7 +412,7 @@ in the cloud without managing any database instances.
 
 The following example initializes an Aurora Serverless PostgreSql cluster.
 Aurora Serverless clusters can specify scaling properties which will be used to
-automatically scale the database cluster seamlessly based on the workload. 
+automatically scale the database cluster seamlessly based on the workload.
 
 ```ts
 import * as ec2 from '@aws-cdk/aws-ec2';

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

@@ -8,10 +8,9 @@ import { Annotations, Duration, RemovalPolicy, Resource, Token } from '@aws-cdk/
 import { Construct } from 'constructs';
 import { IClusterEngine } from './cluster-engine';
 import { DatabaseClusterAttributes, IDatabaseCluster } from './cluster-ref';
-import { DatabaseSecret } from './database-secret';
 import { Endpoint } from './endpoint';
 import { IParameterGroup } from './parameter-group';
-import { applyRemovalPolicy, DEFAULT_PASSWORD_EXCLUDE_CHARS, defaultDeletionProtection, setupS3ImportExport } from './private/util';
+import { applyRemovalPolicy, DEFAULT_PASSWORD_EXCLUDE_CHARS, defaultDeletionProtection, renderCredentials, setupS3ImportExport } from './private/util';
 import { BackupProps, Credentials, InstanceProps, PerformanceInsightRetention, RotationSingleUserOptions, RotationMultiUserOptions } from './props';
 import { DatabaseProxy, DatabaseProxyOptions, ProxyTarget } from './proxy';
 import { CfnDBCluster, CfnDBClusterProps, CfnDBInstance } from './rds.generated';
@@ -489,14 +488,7 @@ export class DatabaseCluster extends DatabaseClusterNew {
     this.singleUserRotationApplication = props.engine.singleUserRotationApplication;
     this.multiUserRotationApplication = props.engine.multiUserRotationApplication;
 
-    let credentials = props.credentials ?? Credentials.fromUsername(props.engine.defaultUsername ?? 'admin');
-    if (!credentials.secret && !credentials.password) {
-      credentials = Credentials.fromSecret(new DatabaseSecret(this, 'Secret', {
-        username: credentials.username,
-        encryptionKey: credentials.encryptionKey,
-        excludeCharacters: credentials.excludeCharacters,
-      }));
-    }
+    const credentials = renderCredentials(this, props.credentials, props.engine.defaultUsername);
     const secret = credentials.secret;
 
     const cluster = new CfnDBCluster(this, 'Resource', {

packages/@aws-cdk/aws-rds/lib/database-secret.ts

@@ -1,3 +1,4 @@
+import * as crypto from 'crypto';
 import * as kms from '@aws-cdk/aws-kms';
 import * as secretsmanager from '@aws-cdk/aws-secretsmanager';
 import { Aws } from '@aws-cdk/core';
@@ -33,6 +34,16 @@ export interface DatabaseSecretProps {
    * @default " %+~`#$&*()|[]{}:;<>?!'/@\"\\"
    */
   readonly excludeCharacters?: string;
+
+  /**
+   * Whether to override the logical id of the AWS::SecretsManager::Secret
+   * with a hash of the options that influence the password generation. This
+   * way a new secret will be created when the password is regenerated and the
+   * cluster or instance consuming this secret will have its credentials updated.
+   *
+   * @default false
+   */
+  readonly overrideLogicalId?: boolean;
 }
 
 /**
@@ -55,5 +66,20 @@ export class DatabaseSecret extends secretsmanager.Secret {
         excludeCharacters: props.excludeCharacters ?? DEFAULT_PASSWORD_EXCLUDE_CHARS,
       },
     });
+
+    if (props.overrideLogicalId) {
+      const hash = crypto.createHash('md5');
+      hash.update(JSON.stringify({
+        path: this.node.path, // make it unique
+        // Use here the options that influence the password generation.
+        // If at some point we add other password customization options
+        // they sould be added here below (e.g. `passwordLength`).
+        excludeCharacters: props.excludeCharacters,
+      }));
+      const logicalId = `${this.node.path.replace(/([^A-Za-z0-9]|\/)/g, '')}${hash.digest('hex')}`;
+
+      const secret = this.node.defaultChild as secretsmanager.CfnSecret;
+      secret.overrideLogicalId(logicalId.slice(0, 255));
+    }
   }
 }

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

@@ -12,7 +12,7 @@ import { Endpoint } from './endpoint';
 import { IInstanceEngine } from './instance-engine';
 import { IOptionGroup } from './option-group';
 import { IParameterGroup } from './parameter-group';
-import { applyRemovalPolicy, DEFAULT_PASSWORD_EXCLUDE_CHARS, defaultDeletionProtection, engineDescription, setupS3ImportExport } from './private/util';
+import { applyRemovalPolicy, DEFAULT_PASSWORD_EXCLUDE_CHARS, defaultDeletionProtection, engineDescription, renderCredentials, setupS3ImportExport } from './private/util';
 import { Credentials, PerformanceInsightRetention, RotationMultiUserOptions, RotationSingleUserOptions, SnapshotCredentials } from './props';
 import { DatabaseProxy, DatabaseProxyOptions, ProxyTarget } from './proxy';
 import { CfnDBInstance, CfnDBInstanceProps } from './rds.generated';
@@ -947,14 +947,7 @@ export class DatabaseInstance extends DatabaseInstanceSource implements IDatabas
   constructor(scope: Construct, id: string, props: DatabaseInstanceProps) {
     super(scope, id, props);
 
-    let credentials = props.credentials ?? Credentials.fromUsername(props.engine.defaultUsername ?? 'admin');
-    if (!credentials.secret && !credentials.password) {
-      credentials = Credentials.fromSecret(new DatabaseSecret(this, 'Secret', {
-        username: credentials.username,
-        encryptionKey: credentials.encryptionKey,
-        excludeCharacters: credentials.excludeCharacters,
-      }));
-    }
+    const credentials = renderCredentials(this, props.credentials, props.engine.defaultUsername);
     const secret = credentials.secret;
 
     const instance = new CfnDBInstance(this, 'Resource', {
@@ -1032,6 +1025,9 @@ export class DatabaseInstanceFromSnapshot extends DatabaseInstanceSource impleme
         username: credentials.username,
         encryptionKey: credentials.encryptionKey,
         excludeCharacters: credentials.excludeCharacters,
+        // Always replace secret when customization options are changed
+        // (MasterUsername is not specified for an instance created from a snapshot)
+        overrideLogicalId: true,
       });
     }
 

packages/@aws-cdk/aws-rds/lib/private/util.ts

@@ -1,7 +1,9 @@
 import * as iam from '@aws-cdk/aws-iam';
 import * as s3 from '@aws-cdk/aws-s3';
 import { Construct, CfnDeletionPolicy, CfnResource, RemovalPolicy } from '@aws-cdk/core';
+import { DatabaseSecret } from '../database-secret';
 import { IEngine } from '../engine';
+import { Credentials } from '../props';
 
 /**
  * The default set of characters we exclude from generated passwords for database users.
@@ -90,3 +92,27 @@ export function defaultDeletionProtection(deletionProtection?: boolean, removalP
     ? deletionProtection
     : (removalPolicy === RemovalPolicy.RETAIN ? true : undefined);
 }
+
+/**
+ * Renders the credentials for an instance or cluster
+ */
+export function renderCredentials(scope: Construct, credentials?: Credentials, engineDefaultUsername?: string): Credentials {
+  let renderedCredentials = credentials ?? Credentials.fromUsername(engineDefaultUsername ?? 'admin'); // For backwards compatibilty
+
+  if (!renderedCredentials.secret && !renderedCredentials.password) {
+    renderedCredentials = Credentials.fromSecret(
+      new DatabaseSecret(scope, 'Secret', {
+        username: renderedCredentials.username,
+        encryptionKey: renderedCredentials.encryptionKey,
+        excludeCharacters: renderedCredentials.excludeCharacters,
+        // if username must be referenced as a string we can safely replace the
+        // secret when customization options are changed without risking a replacement
+        overrideLogicalId: credentials?.usernameAsString,
+      }),
+      // pass username if it must be referenced as a string
+      credentials?.usernameAsString ? renderedCredentials.username : undefined,
+    );
+  }
+
+  return renderedCredentials;
+}

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

@@ -116,18 +116,9 @@ export interface BackupProps {
 }
 
 /**
- * Options for creating a Login from a username.
+ * Base options for creating Credentials.
  */
-export interface CredentialsFromUsernameOptions {
-  /**
-   * Password
-   *
-   * Do not put passwords in your CDK code directly.
-   *
-   * @default - a Secrets Manager generated password
-   */
-  readonly password?: SecretValue;
-
+export interface CredentialsBaseOptions {
   /**
    * KMS encryption key to encrypt the generated secret.
    *
@@ -144,14 +135,55 @@ export interface CredentialsFromUsernameOptions {
   readonly excludeCharacters?: string;
 }
 
+/**
+ * Options for creating Credentials from a username.
+ */
+export interface CredentialsFromUsernameOptions extends CredentialsBaseOptions {
+  /**
+   * Password
+   *
+   * Do not put passwords in your CDK code directly.
+   *
+   * @default - a Secrets Manager generated password
+   */
+  readonly password?: SecretValue;
+}
+
 /**
  * Username and password combination
  */
 export abstract class Credentials {
+  /**
+   * Creates Credentials with a password generated and stored in SecretsManager.
+   */
+  public static fromGeneratedPassword(username: string, options: CredentialsBaseOptions = {}): Credentials {
+    return {
+      ...options,
+      username,
+      usernameAsString: true,
+    };
+  }
+
+  /**
+   * Creates Credentials from a password
+   *
+   * Do not put passwords in your CDK code directly.
+   */
+  public static fromPassword(username: string, password: SecretValue): Credentials {
+    return {
+      username,
+      password,
+      usernameAsString: true,
+    };
+  }
 
   /**
    * Creates Credentials for the given username, and optional password and key.
    * If no password is provided, one will be generated and stored in SecretsManager.
+   *
+   * @deprecated use `fromGeneratedPassword()` or `fromPassword()` for new deployments only.
+   *   Switching to `fromGeneratedPassword()` or `fromPassword()` for existing instances/clusters
+   *   will have them replaced.
    */
   public static fromUsername(username: string, options: CredentialsFromUsernameOptions = {}): Credentials {
     return {
@@ -171,10 +203,15 @@ export abstract class Credentials {
    *   "password": <required: password>,
    * }
    * ```
+   *
+   * @param secret The secret where the credentials are stored
+   * @param username The username defined in the secret. If specified the username
+   * will be referenced as a string and not as dynamic reference to the username
+   * field in the secret
    */
-  public static fromSecret(secret: secretsmanager.ISecret): Credentials {
+  public static fromSecret(secret: secretsmanager.ISecret, username?: string): Credentials {
     return {
-      username: secret.secretValueFromJson('username').toString(),
+      username: username ?? secret.secretValueFromJson('username').toString(),
       password: secret.secretValueFromJson('password'),
       encryptionKey: secret.encryptionKey,
       secret,
@@ -186,6 +223,14 @@ export abstract class Credentials {
    */
   public abstract readonly username: string;
 
+  /**
+   * Whether the username should be referenced as a string and not as a dynamic
+   * reference to the username in the secret.
+   *
+   * @default false
+   */
+  public abstract readonly usernameAsString?: boolean;
+
   /**
    * Password
    *

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

@@ -4,10 +4,9 @@ import * as secretsmanager from '@aws-cdk/aws-secretsmanager';
 import { Resource, Duration, Token, Annotations, RemovalPolicy, IResource, Stack } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { IClusterEngine } from './cluster-engine';
-import { DatabaseSecret } from './database-secret';
 import { Endpoint } from './endpoint';
 import { IParameterGroup } from './parameter-group';
-import { applyRemovalPolicy, defaultDeletionProtection, DEFAULT_PASSWORD_EXCLUDE_CHARS } from './private/util';
+import { applyRemovalPolicy, defaultDeletionProtection, DEFAULT_PASSWORD_EXCLUDE_CHARS, renderCredentials } from './private/util';
 import { Credentials, RotationMultiUserOptions, RotationSingleUserOptions } from './props';
 import { CfnDBCluster } from './rds.generated';
 import { ISubnetGroup, SubnetGroup } from './subnet-group';
@@ -376,14 +375,7 @@ export class ServerlessCluster extends ServerlessClusterBase {
       }
     }
 
-    let credentials = props.credentials ?? Credentials.fromUsername(props.engine.defaultUsername ?? 'admin');
-    if (!credentials.secret && !credentials.password) {
-      credentials = Credentials.fromSecret(new DatabaseSecret(this, 'Secret', {
-        username: credentials.username,
-        encryptionKey: credentials.encryptionKey,
-        excludeCharacters: credentials.excludeCharacters,
-      }));
-    }
+    const credentials = renderCredentials(this, props.credentials, props.engine.defaultUsername);
     const secret = credentials.secret;
 
     // bind the engine to the Cluster