feat(rds): new DatabaseInstance.fromLookup (#33258)

pcheungamz · web-flow · commit eb97d2d2afd1 · 2025-04-10T20:12:18.000Z
### Issue # (if applicable) Closes #31720 This replaces my previous PR #32901. I addressed the PR comments in this new PR. This depends on this PR: cdklabs/cloud-assembly-schema#124. Also depends on this CDK CLI PR: aws/aws-cdk-cli#138. That PR should be merged first and the CLI released, before this PR can be merged. ### Reason for this change Add DatabaseInstance.fromLookup() feature ### Description of changes * Add CC API Context Provider. Needs this PR: cdklabs/cloud-assembly-schema#124 * DatabaseInstance.fromLookup call CC API to get the database instance info from instanceIdentifier. * Add units tests. ### Describe any new or updated permissions being added User will need to have permission to run CloudControl API. ### Description of how you validated changes Tested with this code. I already have an RDS DB in my AWS account. I want to look it up and grant connect to a new user. Saved to packages/@aws-cdk-testing/framework-integ/test/aws-rds/test/my-test-app.ts ``` import * as cdk from 'aws-cdk-lib'; import * as iam from 'aws-cdk-lib/aws-iam'; import * as rds from 'aws-cdk-lib/aws-rds'; const awsAccountId = 'XXXXXXXXXX79'; const instanceId = 'XXXXXXXXXX-instance-1'; const appWithDb = new cdk.App(); const stack = new cdk.Stack(appWithDb, 'StackWithVpc', { env: { region: 'us-east-1', account: awsAccountId, }, }); const dbFromLookup = rds.DatabaseInstance.fromLookup(stack, 'dbFromLookup', { instanceIdentifier: instanceId, }); /* eslint-disable no-console */ console.log('lookup values', dbFromLookup.dbInstanceEndpointAddress, dbFromLookup.dbInstanceEndpointPort); const consoleReadOnlyRole = new iam.Role(stack, 'TestRole', { assumedBy: new iam.ArnPrincipal('arn_for_trusted_principal'), }); dbFromLookup.grantConnect(consoleReadOnlyRole, 'dbTestUser'); ``` Ran this command: ``` ../../aws-cdk/bin/cdk -a 'npx ts-node test/aws-rds/test/my-test-app.ts' synth ``` ### Checklist - [ X ] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
diff --git a/packages/aws-cdk-lib/aws-rds/README.md b/packages/aws-cdk-lib/aws-rds/README.md
@@ -1553,6 +1553,25 @@ new rds.DatabaseCluster(this, 'Cluster', {
 });
 ```
 
+## Importing existing DatabaseInstance
+
+### Lookup DatabaseInstance by instanceIdentifier
+
+You can lookup an existing DatabaseInstance by its instanceIdentifier using `DatabaseInstance.fromLookup()`.  This method returns an `IDatabaseInstance`.
+
+Here's how `DatabaseInstance.fromLookup()` can be used:
+
+```ts
+declare const myUserRole: iam.Role;
+
+const dbFromLookup = rds.DatabaseInstance.fromLookup(this, 'dbFromLookup', {
+  instanceIdentifier: 'instanceId',
+});
+
+// Grant a connection
+dbFromLookup.grantConnect(myUserRole, 'my-user-id');
+```
+
 ## Limitless Database Cluster
 
 Amazon Aurora [PostgreSQL Limitless Database](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/limitless.html) provides automated horizontal scaling to process millions of write transactions per second and manages petabytes of data while maintaining the simplicity of operating inside a single database.
diff --git a/packages/aws-cdk-lib/aws-rds/lib/instance.ts b/packages/aws-cdk-lib/aws-rds/lib/instance.ts
@@ -17,7 +17,8 @@ import * as kms from '../../aws-kms';
 import * as logs from '../../aws-logs';
 import * as s3 from '../../aws-s3';
 import * as secretsmanager from '../../aws-secretsmanager';
-import { ArnComponents, ArnFormat, Duration, FeatureFlags, IResource, Lazy, RemovalPolicy, Resource, Stack, Token, Tokenization } from '../../core';
+import * as cxschema from '../../cloud-assembly-schema';
+import { ArnComponents, ArnFormat, ContextProvider, Duration, FeatureFlags, IResource, Lazy, RemovalPolicy, Resource, Stack, Token, Tokenization } from '../../core';
 import { ValidationError } from '../../core/lib/errors';
 import { addConstructMetadata } from '../../core/lib/metadata-resource';
 import * as cxapi from '../../cx-api';
@@ -134,6 +135,60 @@ export interface DatabaseInstanceAttributes {
  * A new or imported database instance.
  */
 export abstract class DatabaseInstanceBase extends Resource implements IDatabaseInstance {
+  /**
+   * Lookup an existing DatabaseInstance using instanceIdentifier.
+   */
+  public static fromLookup(scope: Construct, id: string, options: DatabaseInstanceLookupOptions): IDatabaseInstance {
+    const response: {[key: string]: any}[] = ContextProvider.getValue(scope, {
+      provider: cxschema.ContextProvider.CC_API_PROVIDER,
+      props: {
+        typeName: 'AWS::RDS::DBInstance',
+        exactIdentifier: options.instanceIdentifier,
+        propertiesToReturn: [
+          'DBInstanceArn',
+          'Endpoint.Address',
+          'Endpoint.Port',
+          'DbiResourceId',
+          'DBSecurityGroups',
+        ],
+      } as cxschema.CcApiContextQuery,
+      dummyValue: [
+        {
+          'Identifier': 'TEST',
+          'DBInstanceArn': 'TESTARN',
+          'Endpoint.Address': 'TESTADDRESS',
+          'Endpoint.Port': '5432',
+          'DbiResourceId': 'TESTID',
+          'DBSecurityGroups': [],
+        },
+      ],
+    }).value;
+
+    // getValue returns a list of result objects.  We are expecting 1 result or Error.
+    const instance = response[0];
+
+    // Get ISecurityGroup from securityGroupId
+    let securityGroups: ec2.ISecurityGroup[] = [];
+    const dbsg: string[] = instance.DBSecurityGroups;
+    if (dbsg) {
+      securityGroups = dbsg.map(securityGroupId => {
+        return ec2.SecurityGroup.fromSecurityGroupId(
+          scope,
+          `LSG-${securityGroupId}`,
+          securityGroupId,
+        );
+      });
+    }
+
+    return this.fromDatabaseInstanceAttributes(scope, id, {
+      instanceEndpointAddress: instance['Endpoint.Address'],
+      port: instance['Endpoint.Port'],
+      instanceIdentifier: options.instanceIdentifier,
+      securityGroups: securityGroups,
+      instanceResourceId: instance.DbiResourceId,
+    });
+  }
+
   /**
    * Import an existing database instance.
    */
@@ -1142,6 +1197,16 @@ abstract class DatabaseInstanceSource extends DatabaseInstanceNew implements IDa
   }
 }
 
+/**
+ * Properties for looking up an existing DatabaseInstance.
+ */
+export interface DatabaseInstanceLookupOptions {
+  /**
+   * The instance identifier of the DatabaseInstance
+   */
+  readonly instanceIdentifier: string;
+}
+
 /**
  * Construction properties for a DatabaseInstance.
  */
diff --git a/packages/aws-cdk-lib/aws-rds/test/instance.from-lookup.test.ts b/packages/aws-cdk-lib/aws-rds/test/instance.from-lookup.test.ts
@@ -0,0 +1,127 @@
+import * as cxschema from '../../cloud-assembly-schema';
+import { ContextProvider, Stack } from '../../core';
+import * as rds from '../lib';
+
+/* eslint-disable */
+describe('DatabaseInstanceBase from lookup', () => {
+  test('return correct instance info', () => {
+    // GIVEN
+    const resultObjs = [
+      {
+        'DBInstanceArn': 'arn:aws:rds:us-east-1:123456789012:db:instance-1',
+        'Endpoint.Address': 'instance-1.testserver.us-east-1.rds.amazonaws.com',
+        'Endpoint.Port': '5432',
+        'DbiResourceId': 'db-ABCDEFGHI',
+        'DBSecurityGroups': [],
+        'Identifier': 'instance-1',
+      },
+    ];
+    const value = {
+      value: resultObjs,
+    };
+    const mock = jest.spyOn(ContextProvider, 'getValue').mockReturnValue(value);
+
+    // WHEN
+    const stack = new Stack(undefined, undefined, { env: { region: 'us-east-1', account: '123456789012' } });
+    const instance = rds.DatabaseInstance.fromLookup(stack, 'MyInstance', {
+      instanceIdentifier: 'instance-1',
+    });
+
+    // THEN
+    expect(instance.instanceIdentifier).toEqual('instance-1');
+    expect(instance.dbInstanceEndpointAddress).toEqual('instance-1.testserver.us-east-1.rds.amazonaws.com');
+    expect(instance.dbInstanceEndpointPort).toEqual('5432');
+    expect(instance.instanceResourceId).toEqual('db-ABCDEFGHI');
+    expect(instance.connections.securityGroups.length).toEqual(0);
+
+    expect(mock).toHaveBeenCalledWith(stack, {
+      provider: cxschema.ContextProvider.CC_API_PROVIDER,
+        props: {
+          typeName: 'AWS::RDS::DBInstance',
+          exactIdentifier: 'instance-1',
+          propertiesToReturn: [
+            'DBInstanceArn',
+            'Endpoint.Address',
+            'Endpoint.Port',
+            'DbiResourceId',
+            'DBSecurityGroups',
+          ],
+        } as cxschema.CcApiContextQuery,
+        dummyValue: [
+          {
+            'Identifier': 'TEST',
+            'DBInstanceArn': 'TESTARN',
+            'Endpoint.Address': 'TESTADDRESS',
+            'Endpoint.Port': '5432',
+            'DbiResourceId': 'TESTID',
+            'DBSecurityGroups': [],
+          },
+        ],
+    });
+
+    mock.mockRestore();
+  });
+});
+
+describe('DatabaseInstanceBase from lookup with DBSG', () => {
+  test('return correct instance info', () => {
+    // GIVEN
+    const resultObjs = [
+      {
+        'DBInstanceArn': 'arn:aws:rds:us-east-1:123456789012:db:instance-1',
+        'Endpoint.Address': 'instance-1.testserver.us-east-1.rds.amazonaws.com',
+        'Endpoint.Port': '5432',
+        'DbiResourceId': 'db-ABCDEFGHI',
+        'DBSecurityGroups': ['dbsg-1', 'dbsg-2'],
+        'Identifier': 'instance-1',
+      },
+    ];
+    const value = {
+      value: resultObjs,
+    };
+    const mock = jest.spyOn(ContextProvider, 'getValue').mockReturnValue(value);
+
+    // WHEN
+    const stack = new Stack(undefined, undefined, { env: { region: 'us-east-1', account: '123456789012' } });
+    const instance = rds.DatabaseInstance.fromLookup(stack, 'MyInstance', {
+      instanceIdentifier: 'instance-1',
+    });
+
+    // THEN
+    expect(instance.instanceIdentifier).toEqual('instance-1');
+    expect(instance.dbInstanceEndpointAddress).toEqual('instance-1.testserver.us-east-1.rds.amazonaws.com');
+    expect(instance.dbInstanceEndpointPort).toEqual('5432');
+    expect(instance.instanceResourceId).toEqual('db-ABCDEFGHI');
+    expect(instance.connections.securityGroups.length).toEqual(2);
+    expect(instance.connections.securityGroups[0].securityGroupId).toEqual('dbsg-1');
+    expect(instance.connections.securityGroups[1].securityGroupId).toEqual('dbsg-2');
+
+    expect(mock).toHaveBeenCalledWith(stack, {
+      provider: cxschema.ContextProvider.CC_API_PROVIDER,
+        props: {
+          typeName: 'AWS::RDS::DBInstance',
+          exactIdentifier: 'instance-1',
+          propertiesToReturn: [
+            'DBInstanceArn',
+            'Endpoint.Address',
+            'Endpoint.Port',
+            'DbiResourceId',
+            'DBSecurityGroups',
+          ],
+        } as cxschema.CcApiContextQuery,
+        dummyValue: [
+          {
+            'Identifier': 'TEST',
+            'DBInstanceArn': 'TESTARN',
+            'Endpoint.Address': 'TESTADDRESS',
+            'Endpoint.Port': '5432',
+            'DbiResourceId': 'TESTID',
+            'DBSecurityGroups': [],
+          },
+        ],
+    });
+
+    mock.mockRestore();
+  });
+});
+/* eslint-enable */
