feat(redshift): manage database users and tables via cdk

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

@@ -75,4 +75,106 @@ cluster.addRotationMultiUser('MyUser', {
 });
 ```
 
-This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
+## Database Resources
+
+This module allows for the creation of non-CloudFormation database resources via [custom
+resources](https://docs.aws.amazon.com/cdk/api/latest/docs/custom-resources-readme.html).
+These resources include database users and database tables. Access to the cluster is
+granted via administrator credentials; these can be supplied explicitly through the
+`adminUser` property. Alternatively, they can be automatically pulled from the Redshift
+cluster destination if the cluster generated the password for its own administrator
+credentials (ie., no value vas provided for [the `masterPassword`
+property](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Login.html#masterpasswordspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)
+of
+[`Cluster.masterUser`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Cluster.html#masteruserspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)).
+
+### Creating Users
+
+Create a user within a Redshift cluster database by instantiating a `User` construct. This
+will generate a username and password, store the credentials in a [AWS Secrets Manager
+`Secret`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.Secret.html),
+and make a query to the Redshift cluster to create a new database user with the
+credentials.
+
+```ts
+new redshift.User(this, 'User', {
+  cluster: cluster,
+  databaseName: 'databaseName',
+});
+```
+
+By default, the user credentials are encrypted with your AWS account's default Secrets
+Manager encryption key. You can specify the encryption key used for this purpose by
+supplying a key in the `encryptionKey` property.
+
+```ts
+import * as kms from '@aws-cdk/aws-kms';
+
+const encryptionKey = new kms.Key(this, 'Key');
+new redshift.User(stack, 'User', {
+  encryptionKey: encryptionKey,
+  cluster: cluster,
+  databaseName: 'databaseName',
+});
+```
+
+By default, a username is automatically generated from the user construct ID and its path
+in the construct tree. You can specify a particular username by providing a value for the
+`username` property. Usernames must be valid identifiers; see: [Names and
+identifiers](https://docs.aws.amazon.com/redshift/latest/dg/r_names.html) in the *Amazon
+Redshift Database Developer Guide*.
+
+```ts
+new redshift.User(stack, 'User', {
+  username: 'myuser'
+  cluster: cluster,
+  databaseName: 'databaseName',
+});
+```
+
+The user password is generated by AWS Secrets Manager using the default configuration
+found in
+[`secretsmanager.SecretStringGenerator`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.SecretStringGenerator.html),
+except with password length `30` and some SQL-incompliant characters excluded. The
+plaintext for the password will never be present in the CDK application; instead, a
+[CloudFormation Dynamic
+Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)
+will be used wherever the password value is required.
+
+### Creating Tables
+
+Create a table within a Redshift cluster database by instantiating a `Table`
+construct. This will make a query to the Redshift cluster to create a new database table
+with the supplied schema.
+
+```ts
+new redshift.Table(this, 'Table', {
+  cluster: cluster,
+  databaseName: 'databaseName',
+  tableColumns: [{ name: 'col1', dataType: 'varchar(4)' }, { name: 'col2', dataType: 'float' }],
+});
+```
+
+### Granting Privileges
+
+You can give a user privileges to perform certain actions on a table by using the `User.addPrivilege` method.
+
+```ts
+const databaseProps = {
+  cluster: cluster,
+  databaseName: 'databaseName',
+};
+const user = new redshift.User(this, 'User', databaseProps);
+const table = new redshift.Table(this, 'Table', {
+  ...databaseProps,
+  tableColumns: [{ name: 'col1', dataType: 'varchar(4)' }, { name: 'col2', dataType: 'float' }],
+});
+
+user.addPrivilege(table, Privilege.INSERT, Privilege.UPDATE);
+```
+
+Privileges on the table can also be given by using the `Table.grant` method.
+
+```ts
+table.grant(user, Privilege.DROP, Privilege.SELECT);
+```

packages/@aws-cdk/aws-redshift/lib/database-props.ts

@@ -0,0 +1,26 @@
+import * as secretsmanager from '@aws-cdk/aws-secretsmanager';
+import { ICluster } from './cluster';
+
+/**
+ * Properties for accessing a Redshift database
+ */
+export interface DatabaseProps {
+  /**
+   * The cluster containing the database.
+   */
+  readonly cluster: ICluster;
+
+  /**
+   * The name of the database.
+   */
+  readonly databaseName: string;
+
+  /**
+   * The secret containing credentials to a Redshift user with administrator privileges.
+   *
+   * Secret JSON schema: `{ username: string; password: string }`.
+   *
+   * @default - the admin secret is taken from the cluster
+   */
+  readonly adminUser?: secretsmanager.ISecret;
+}

packages/@aws-cdk/aws-redshift/lib/database-query-provider/create-table.ts

@@ -0,0 +1,71 @@
+/* eslint-disable-next-line import/no-unresolved */
+import * as AWSLambda from 'aws-lambda';
+import { ClusterProps, executeStatement, getClusterPropsFromEvent, getResourceNameFromPhysicalId, getResourceProperty, makePhysicalId } from './util';
+
+interface Column {
+  name: string;
+  dataType: string;
+}
+
+export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent) {
+  const tableColumns = JSON.parse(getResourceProperty('tableColumns', event.ResourceProperties)) as Column[];
+  const tableName = event.ResourceProperties.tableName;
+  const clusterProps = getClusterPropsFromEvent(event.ResourceProperties);
+
+  if (event.RequestType === 'Create') {
+    await createTable(tableName, tableColumns, clusterProps);
+    return { PhysicalResourceId: makePhysicalId(tableName, clusterProps), Data: { tableName: tableName } };
+  } else if (event.RequestType === 'Delete') {
+    await dropTable(getResourceNameFromPhysicalId(event.PhysicalResourceId), clusterProps);
+    return;
+  } else if (event.RequestType === 'Update') {
+    await updateTable(tableName, tableColumns, clusterProps, event.OldResourceProperties);
+    return { PhysicalResourceId: makePhysicalId(tableName, clusterProps), Data: { tableName: tableName } };
+  } else {
+    /* eslint-disable-next-line dot-notation */
+    throw new Error(`Unrecognized event type: ${event['RequestType']}`);
+  }
+}
+
+async function createTable(tableName: string, tableColumns: Column[], clusterProps: ClusterProps) {
+  const tableColumnsString = tableColumns.map(column => `${column.name} ${column.dataType}`).join();
+  await executeStatement(`CREATE TABLE ${tableName} (${tableColumnsString})`, clusterProps);
+}
+
+async function dropTable(tableName: string, clusterProps: ClusterProps) {
+  await executeStatement(`DROP TABLE ${tableName}`, clusterProps);
+}
+
+async function updateTable(tableName: string, tableColumns: Column[], clusterProps: ClusterProps, oldResourceProperties: { [Key: string]: any }) {
+  const oldClusterProps = getClusterPropsFromEvent(oldResourceProperties);
+  if (clusterProps !== oldClusterProps) {
+    return createTable(tableName, tableColumns, clusterProps);
+  }
+
+  const oldTableColumns = JSON.parse(getResourceProperty('tableColumns', oldResourceProperties)) as Column[];
+  const oldTableName = oldResourceProperties.tableName;
+
+  if (tableName !== oldTableName) {
+    return createTable(tableName, tableColumns, clusterProps);
+  }
+
+  const changes: string[] = [];
+  tableColumns.forEach(tableColumn => {
+    const oldTableColumn = oldTableColumns.find(({ name: oldName }) => tableColumn.name === oldName);
+    if (!oldTableColumn) {
+      changes.push(`ADD ${tableColumn.name} ${tableColumn.dataType}`);
+    } else {
+      if (tableColumn.dataType !== oldTableColumn.dataType) {
+        changes.push(`ALTER COLUMN ${tableColumn.name} TYPE ${tableColumn.dataType}`);
+      }
+    }
+  });
+  oldTableColumns.forEach(oldTableColumn => {
+    const tableColumn = tableColumns.find(({ name }) => oldTableColumn.name === name);
+    if (!tableColumn) {
+      changes.push(`DROP ${oldTableColumn.name}`);
+      // TODO: not sure if this is the right choice. can we simply ignore this? will queries break if the schema has extra columns? dropping could lose data "silently"
+    }
+  });
+  await Promise.all(changes.map(change => executeStatement(`ALTER TABLE ${tableName} ${change}`, clusterProps)));
+}

packages/@aws-cdk/aws-redshift/lib/database-query-provider/create-user.ts

@@ -0,0 +1,72 @@
+/* eslint-disable-next-line import/no-unresolved */
+import * as AWSLambda from 'aws-lambda';
+/* eslint-disable-next-line import/no-extraneous-dependencies */
+import * as SecretsManager from 'aws-sdk/clients/secretsmanager';
+import { ClusterProps, executeStatement, getClusterPropsFromEvent, getResourceNameFromPhysicalId, getResourceProperty, makePhysicalId } from './util';
+
+const secretsManager = new SecretsManager();
+
+export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent) {
+  const username = getResourceProperty('username', event.ResourceProperties);
+  const passwordSecretArn = getResourceProperty('passwordSecretArn', event.ResourceProperties);
+  const clusterProps = getClusterPropsFromEvent(event.ResourceProperties);
+
+  if (event.RequestType === 'Create') {
+    await createUser(username, passwordSecretArn, clusterProps);
+    return { PhysicalResourceId: makePhysicalId(username, clusterProps), Data: { username: username } };
+  } else if (event.RequestType === 'Delete') {
+    await dropUser(getResourceNameFromPhysicalId(event.PhysicalResourceId), clusterProps);
+    return;
+  } else if (event.RequestType === 'Update') {
+    await updateUser(username, passwordSecretArn, clusterProps, event.OldResourceProperties);
+    return { PhysicalResourceId: makePhysicalId(username, clusterProps), Data: { username: username } };
+  } else {
+    /* eslint-disable-next-line dot-notation */
+    throw new Error(`Unrecognized event type: ${event['RequestType']}`);
+  }
+}
+
+async function dropUser(username: string, clusterProps: ClusterProps) {
+  await executeStatement(`DROP USER ${username}`, clusterProps);
+}
+
+async function createUser(username: string, passwordSecretArn: string, clusterProps: ClusterProps) {
+  const password = await getPasswordFromSecret(passwordSecretArn);
+
+  await executeStatement(`CREATE USER ${username} PASSWORD '${password}'`, clusterProps);
+}
+
+async function updateUser(username: string, passwordSecretArn: string, clusterProps: ClusterProps, oldResourceProperties: { [Key: string]: any }) {
+  const oldClusterProps = getClusterPropsFromEvent(oldResourceProperties);
+  if (clusterProps !== oldClusterProps) {
+    await createUser(username, passwordSecretArn, clusterProps);
+    return;
+  }
+
+  const oldUsername = getResourceProperty('username', oldResourceProperties);
+  const oldPasswordSecretArn = getResourceProperty('passwordSecretArn', oldResourceProperties);
+  const oldPassword = await getPasswordFromSecret(oldPasswordSecretArn);
+  const password = await getPasswordFromSecret(passwordSecretArn);
+
+  if (username !== oldUsername) {
+    await createUser(username, passwordSecretArn, clusterProps);
+    return;
+  }
+
+  if (password !== oldPassword) {
+    await executeStatement(`ALTER USER ${username} PASSWORD ${password}`, clusterProps);
+  }
+}
+
+async function getPasswordFromSecret(passwordSecretArn: string): Promise<string> {
+  const secretValue = await secretsManager.getSecretValue({
+    SecretId: passwordSecretArn,
+  }).promise();
+  const secretString = secretValue.SecretString;
+  if (!secretString) {
+    throw new Error(`Secret string for ${passwordSecretArn} was empty`);
+  }
+  const { password } = JSON.parse(secretString);
+
+  return password;
+}

packages/@aws-cdk/aws-redshift/lib/database-query-provider/grant-privileges.ts

@@ -0,0 +1,54 @@
+/* eslint-disable-next-line import/no-unresolved */
+import * as AWSLambda from 'aws-lambda';
+import { ClusterProps, executeStatement, getClusterPropsFromEvent, getResourceProperty } from './util';
+
+interface TablePrivilege {
+  readonly tableName: string;
+  readonly privileges: string[];
+}
+
+export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent) {
+  const username = getResourceProperty('username', event.ResourceProperties);
+  const tablePrivileges = JSON.parse(getResourceProperty('tablePrivileges', event.ResourceProperties)) as TablePrivilege[];
+  const clusterProps = getClusterPropsFromEvent(event.ResourceProperties);
+
+  if (event.RequestType === 'Create') {
+    await grantPrivileges(username, tablePrivileges, clusterProps);
+    return { PhysicalResourceId: username };
+  } else if (event.RequestType === 'Delete') {
+    await revokePrivileges(username, tablePrivileges, clusterProps);
+    return;
+  } else if (event.RequestType === 'Update') {
+    await updatePrivileges(username, tablePrivileges, clusterProps, event.OldResourceProperties);
+    return { PhysicalResourceId: username };
+  } else {
+    /* eslint-disable-next-line dot-notation */
+    throw new Error(`Unrecognized event type: ${event['RequestType']}`);
+  }
+}
+
+async function revokePrivileges(username: string, tablePrivileges: TablePrivilege[], clusterProps: ClusterProps) {
+  await Promise.all(tablePrivileges.map(({ tableName, privileges }) => {
+    return executeStatement(`REVOKE ${privileges.join(', ')} ON ${tableName} FROM ${username}`, clusterProps);
+  }));
+}
+
+async function grantPrivileges(username: string, tablePrivileges: TablePrivilege[], clusterProps: ClusterProps) {
+  await Promise.all(tablePrivileges.map(({ tableName, privileges }) => {
+    return executeStatement(`GRANT ${privileges.join(', ')} ON ${tableName} TO ${username}`, clusterProps);
+  }));
+}
+
+async function updatePrivileges(
+  username: string,
+  tablePrivileges: TablePrivilege[],
+  clusterProps: ClusterProps,
+  oldResourceProperties: { [Key: string]: any },
+) {
+  const oldUsername = getResourceProperty('username', oldResourceProperties);
+  const oldTablePrivileges = JSON.parse(getResourceProperty('tablePrivileges', oldResourceProperties)) as TablePrivilege[];
+  if (oldUsername === username) {
+    await revokePrivileges(username, oldTablePrivileges, clusterProps);
+  }
+  await grantPrivileges(username, tablePrivileges, clusterProps);
+}

packages/@aws-cdk/aws-redshift/lib/database-query-provider/index.ts

@@ -0,0 +1,20 @@
+/* eslint-disable-next-line import/no-unresolved */
+import * as AWSLambda from 'aws-lambda';
+import { handler as createTable } from './create-table';
+import { handler as createUser } from './create-user';
+import { handler as grantPrivileges } from './grant-privileges';
+import { getResourceProperty } from './util';
+
+const HANDLERS: { [key: string]: ((event: AWSLambda.CloudFormationCustomResourceEvent) => Promise<any>) } = {
+  'create-table': createTable,
+  'create-user': createUser,
+  'grant-privileges': grantPrivileges,
+};
+
+export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent) {
+  const subHandler = HANDLERS[getResourceProperty('handler', event.ResourceProperties)];
+  if (!subHandler) {
+    throw new Error(`Requested ${process.env.handler} handler is not in supported set: ${JSON.stringify(Object.keys(HANDLERS))}`);
+  }
+  return subHandler(event);
+}