+1. Grants for TableV2 will propagate and be applied to the primary table and all replica tables. +2. Grants for TableV2 will only apply to the primary table. + +### Decision + +After considering the two choices for implementing grants for TableV2, it was decided that a grant should only apply to the primary table. + +### Considerations + +We have decided to implement grants for TableV2 such that they only apply to the primary table for the following reasons:
+1. Implementing grants to apply to all replica tables would contradict the implementation of metrics which only apply to the primary table. This would result in a confusing user experience due to behavioral differences between metrics and grants which are both defined on the ITable interface. +2. Applying grants to all replica tables and all associated customer-managed KMS keys is counter to the principal of least privilege. Permissions may be given for keys and replica tables that a user is not intending permissions to be given for. +3. The TableV2 API offers users a replica method that can be used to work with an individual instance of a replica table. This can be used to apply grants on a per-replica basis if needed, but this decision should be made by the user. + +### Consequences + +Some users may expect grants to apply to all replica tables (see: https://github.com/aws/aws-cdk/issues/7362). However, unlike the Table L2 that is replaced by the TableV2 L2, the TableV2 API offers users the replica method as a way to work with individual replica tables. Additionally, the TableV2 API design can support the future implementation of a method allowing a user to retrieve a list of all replica tables. A user could then iterate over each replica table and apply grants each one individually. This design decision supports both use cases while upholding the principle of least privilege. diff --git a/packages/aws-cdk-lib/aws-dynamodb/lib/billing.ts b/packages/aws-cdk-lib/aws-dynamodb/lib/billing.ts new file mode 100644 index 0000000000000..c319a7023f709 --- /dev/null +++ b/packages/aws-cdk-lib/aws-dynamodb/lib/billing.ts @@ -0,0 +1,69 @@ +import { Capacity } from './capacity'; +import { BillingMode } from './shared'; + +/** + * Properties used to configure provisioned throughput for a DynamoDB table. + */ +export interface ThroughputProps { + /** + * The read capacity. + */ + readonly readCapacity: Capacity; + + /** + * The write capacity. + */ + readonly writeCapacity: Capacity; +} + +/** + * Represents how capacity is managed and how you are charged for read and write throughput + * for a DynamoDB table. + */ +export abstract class Billing { + /** + * Flexible billing option capable of serving requests without capacity planning. + * + * Note: Billing mode will be PAY_PER_REQUEST. + */ + public static onDemand(): Billing { + return new (class extends Billing { + public _renderReadCapacity() { + return undefined; + } + + public _renderWriteCapacity() { + return undefined; + } + }) (BillingMode.PAY_PER_REQUEST); + } + + /** + * Specify the number of reads and writes per second that you need for your application. + * + * @param props specifiy read and write capacity configurations. + */ + public static provisioned(props: ThroughputProps): Billing { + return new (class extends Billing { + public _renderReadCapacity() { + return props.readCapacity._renderReadCapacity(); + } + + public _renderWriteCapacity() { + return props.writeCapacity._renderWriteCapacity(); + } + }) (BillingMode.PROVISIONED); + } + + private constructor (public readonly mode: BillingMode) {} + + /** + * @internal + */ + public abstract _renderReadCapacity(): any; + + /** + * @internal + */ + public abstract _renderWriteCapacity(): any; +} diff --git a/packages/aws-cdk-lib/aws-dynamodb/lib/capacity.ts b/packages/aws-cdk-lib/aws-dynamodb/lib/capacity.ts new file mode 100644 index 0000000000000..0df1591d17178 --- /dev/null +++ b/packages/aws-cdk-lib/aws-dynamodb/lib/capacity.ts @@ -0,0 +1,126 @@ +import { CfnGlobalTable } from './dynamodb.generated'; + +/** + * Capacity modes + */ +export enum CapacityMode { + /** + * Fixed + */ + FIXED = 'FIXED', + + /** + * Autoscaled + */ + AUTOSCALED = 'AUTOSCALED', +} + +/** + * Options used to configure autoscaled capacity. + */ +export interface AutoscaledCapacityOptions { + /** + * The maximum allowable capacity. + */ + readonly maxCapacity: number; + + /** + * The minimum allowable capacity. + * + * @default 1 + */ + readonly minCapacity?: number; + + /** + * The ratio of consumed capacity units to provisioned capacity units. + * + * Note: Target utilization percent cannot be less than 20 and cannot be greater + * than 90. + * + * @default 70 + */ + readonly targetUtilizationPercent?: number +} + +/** + * Represents the amount of read and write operations supported by a DynamoDB table. + */ +export abstract class Capacity { + /** + * Provisioned throughput capacity is configured with fixed capacity units. + * + * Note: You cannot configure write capacity using fixed capacity mode. + * + * @param iops the number of I/O operations per second. + */ + public static fixed(iops: number): Capacity { + return new (class extends Capacity { + public _renderReadCapacity() { + return { + readCapacityUnits: iops, + } satisfies CfnGlobalTable.ReadProvisionedThroughputSettingsProperty; + } + + public _renderWriteCapacity() { + throw new Error(`You cannot configure 'writeCapacity' with ${CapacityMode.FIXED} capacity mode`); + } + }) (CapacityMode.FIXED); + } + + /** + * Dynamically adjusts provisioned throughput capacity on your behalf in response to actual + * traffic patterns. + * + * @param options options used to configure autoscaled capacity mode. + */ + public static autoscaled(options: AutoscaledCapacityOptions): Capacity { + return new (class extends Capacity { + public constructor(mode: CapacityMode) { + super(mode); + + if ((options.minCapacity ?? 1) > options.maxCapacity) { + throw new Error('`minCapacity` must be less than or equal to `maxCapacity`'); + } + + if (options.targetUtilizationPercent !== undefined && (options.targetUtilizationPercent < 20 || options.targetUtilizationPercent > 90)) { + throw new Error('`targetUtilizationPercent` cannot be less than 20 or greater than 90'); + } + } + + public _renderReadCapacity() { + return { + readCapacityAutoScalingSettings: this.renderAutoscaledCapacity(), + } satisfies CfnGlobalTable.ReadProvisionedThroughputSettingsProperty; + } + + public _renderWriteCapacity() { + return { + writeCapacityAutoScalingSettings: this.renderAutoscaledCapacity(), + } satisfies CfnGlobalTable.WriteProvisionedThroughputSettingsProperty; + } + + private renderAutoscaledCapacity() { + return { + minCapacity: options.minCapacity ?? 1, + maxCapacity: options.maxCapacity, + targetTrackingScalingPolicyConfiguration: { + targetValue: options.targetUtilizationPercent ?? 70, + }, + }; + } + + }) (CapacityMode.AUTOSCALED); + } + + private constructor(public readonly mode: CapacityMode) {} + + /** + * @internal + */ + public abstract _renderReadCapacity(): any; + + /** + * @internal + */ + public abstract _renderWriteCapacity(): any; +} diff --git a/packages/aws-cdk-lib/aws-dynamodb/lib/encryption.ts b/packages/aws-cdk-lib/aws-dynamodb/lib/encryption.ts new file mode 100644 index 0000000000000..74c5c7f50fae9 --- /dev/null +++ b/packages/aws-cdk-lib/aws-dynamodb/lib/encryption.ts @@ -0,0 +1,103 @@ +import { Construct } from 'constructs'; +import { CfnGlobalTable } from './dynamodb.generated'; +import { TableEncryption } from './shared'; +import { IKey } from '../../aws-kms'; +import { Stack, Token } from '../../core'; + +/** + * Represents server-side encryption for a DynamoDB table. + */ +export abstract class TableEncryptionV2 { + /** + * Configure server-side encryption using a DynamoDB owned key. + */ + public static dynamoOwnedKey(): TableEncryptionV2 { + return new (class extends TableEncryptionV2 { + public _renderSseSpecification() { + return { + sseEnabled: false, + } satisfies CfnGlobalTable.SSESpecificationProperty; + } + + public _renderReplicaSseSpecification(_scope: Construct, _region: string) { + return undefined; + } + }) (TableEncryption.DEFAULT); + } + + /** + * Configure server-side encryption using a DynamoDB owned key. + */ + public static awsManagedKey(): TableEncryptionV2 { + return new (class extends TableEncryptionV2 { + public _renderSseSpecification() { + return { + sseEnabled: true, + sseType: 'KMS', + } satisfies CfnGlobalTable.SSESpecificationProperty; + } + + public _renderReplicaSseSpecification(_scope: Construct, _region: string) { + return undefined; + } + }) (TableEncryption.AWS_MANAGED); + } + + /** + * Configure server-side encryption using customer managed keys. + * + * @param tableKey the KMS key for the primary table. + * @param replicaKeyArns an object containing the ARN of the KMS key to use for each replica table. + */ + public static customerManagedKey(tableKey: IKey, replicaKeyArns: { [region: string]: string } = {}): TableEncryptionV2 { + return new (class extends TableEncryptionV2 { + public _renderSseSpecification() { + return { + sseEnabled: true, + sseType: 'KMS', + } satisfies CfnGlobalTable.SSESpecificationProperty; + } + + public _renderReplicaSseSpecification(scope: Construct, replicaRegion: string) { + const stackRegion = Stack.of(scope).region; + if (Token.isUnresolved(stackRegion)) { + throw new Error('Replica SSE specification cannot be rendered in a region agnostic stack'); + } + + if (replicaKeyArns.hasOwnProperty(stackRegion)) { + throw new Error(`KMS key for deployment region ${stackRegion} cannot be defined in 'replicaKeyArns'`); + } + + if (replicaRegion === stackRegion) { + return { + kmsMasterKeyId: tableKey.keyArn, + } satisfies CfnGlobalTable.ReplicaSSESpecificationProperty; + } + + const regionInReplicaKeyArns = replicaKeyArns.hasOwnProperty(replicaRegion); + if (!regionInReplicaKeyArns) { + throw new Error(`KMS key for ${replicaRegion} was not found in 'replicaKeyArns'`); + } + + return { + kmsMasterKeyId: replicaKeyArns[replicaRegion], + } satisfies CfnGlobalTable.ReplicaSSESpecificationProperty; + } + }) (TableEncryption.CUSTOMER_MANAGED, tableKey, replicaKeyArns); + } + + private constructor ( + public readonly type: TableEncryption, + public readonly tableKey?: IKey, + public readonly replicaKeyArns?: { [region: string]: string }) {} + + /** + * @internal + */ + public abstract _renderSseSpecification(): any; + + /** + * @internal + */ + public abstract _renderReplicaSseSpecification(scope: Construct, region: string): any; +} diff --git a/packages/aws-cdk-lib/aws-dynamodb/lib/index.ts b/packages/aws-cdk-lib/aws-dynamodb/lib/index.ts index 7ebef5008608a..b5cf7b87b53de 100644 --- a/packages/aws-cdk-lib/aws-dynamodb/lib/index.ts +++ b/packages/aws-cdk-lib/aws-dynamodb/lib/index.ts @@ -1,3 +1,9 @@ export * from './dynamodb.generated'; export * from './table'; export * from './scalable-attribute-api'; +export * from './table-v2'; +export * from './table-v2-base'; +export * from './shared'; +export * from './capacity'; +export * from './billing'; +export * from './encryption'; diff --git a/packages/aws-cdk-lib/aws-dynamodb/lib/shared.ts b/packages/aws-cdk-lib/aws-dynamodb/lib/shared.ts new file mode 100644 index 0000000000000..8d66e8b85ea17 --- /dev/null +++ b/packages/aws-cdk-lib/aws-dynamodb/lib/shared.ts @@ -0,0 +1,445 @@ +import * as cloudwatch from '../../aws-cloudwatch'; +import * as iam from '../../aws-iam'; +import * as kms from '../../aws-kms'; +import { IResource } from '../../core'; + +/** + * Supported DynamoDB table operations. + */ +export enum Operation { + + /** GetItem */ + GET_ITEM = 'GetItem', + + /** BatchGetItem */ + BATCH_GET_ITEM = 'BatchGetItem', + + /** Scan */ + SCAN = 'Scan', + + /** Query */ + QUERY = 'Query', + + /** GetRecords */ + GET_RECORDS = 'GetRecords', + + /** PutItem */ + PUT_ITEM = 'PutItem', + + /** DeleteItem */ + DELETE_ITEM = 'DeleteItem', + + /** UpdateItem */ + UPDATE_ITEM = 'UpdateItem', + + /** BatchWriteItem */ + BATCH_WRITE_ITEM = 'BatchWriteItem', + + /** TransactWriteItems */ + TRANSACT_WRITE_ITEMS = 'TransactWriteItems', + + /** TransactGetItems */ + TRANSACT_GET_ITEMS = 'TransactGetItems', + + /** ExecuteTransaction */ + EXECUTE_TRANSACTION = 'ExecuteTransaction', + + /** BatchExecuteStatement */ + BATCH_EXECUTE_STATEMENT = 'BatchExecuteStatement', + + /** ExecuteStatement */ + EXECUTE_STATEMENT = 'ExecuteStatement', +} + +/** + * Options for configuring a system errors metric that considers multiple operations. + */ +export interface SystemErrorsForOperationsMetricOptions extends cloudwatch.MetricOptions { + + /** + * The operations to apply the metric to. + * + * @default - All operations available by DynamoDB tables will be considered. + */ + readonly operations?: Operation[]; +} + +/** + * Options for configuring metrics that considers multiple operations. + */ +export interface OperationsMetricOptions extends SystemErrorsForOperationsMetricOptions {} + +/** + * Represents an attribute for describing the key schema for the table + * and indexes. + */ +export interface Attribute { + /** + * The name of an attribute. + */ + readonly name: string; + + /** + * The data type of an attribute. + */ + readonly type: AttributeType; +} + +/** + * Data types for attributes within a table + * + * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes + */ +export enum AttributeType { + /** + * Up to 400KiB of binary data (which must be encoded as base64 before sending to DynamoDB) + */ + BINARY = 'B', + + /** + * Numeric values made of up to 38 digits (positive, negative or zero) + */ + NUMBER = 'N', + + /** + * Up to 400KiB of UTF-8 encoded text + */ + STRING = 'S', +} + +/** + * DynamoDB's Read/Write capacity modes. + */ +export enum BillingMode { + /** + * Pay only for what you use. You don't configure Read/Write capacity units. + */ + PAY_PER_REQUEST = 'PAY_PER_REQUEST', + + /** + * Explicitly specified Read/Write capacity units. + */ + PROVISIONED = 'PROVISIONED', +} + +/** + * The set of attributes that are projected into the index + * + * @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Projection.html + */ +export enum ProjectionType { + /** + * Only the index and primary keys are projected into the index. + */ + KEYS_ONLY = 'KEYS_ONLY', + + /** + * Only the specified table attributes are projected into the index. The list + * of projected attributes is in `nonKeyAttributes`. + */ + INCLUDE = 'INCLUDE', + + /** + * All of the table attributes are projected into the index. + */ + ALL = 'ALL' +} + +/** + * DynamoDB's table class. + * + * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.TableClasses.html + */ +export enum TableClass { + /** + * Default table class for DynamoDB. + */ + STANDARD = 'STANDARD', + + /** + * Table class for DynamoDB that reduces storage costs compared to existing DynamoDB + * standard tables. + */ + STANDARD_INFREQUENT_ACCESS = 'STANDARD_INFREQUENT_ACCESS', +} + +/** + * What kind of server-side encryption to apply to this table. + */ +export enum TableEncryption { + /** + * Server-side KMS encryption with a master key owned by AWS. + */ + DEFAULT = 'AWS_OWNED', + + /** + * Server-side KMS encryption with a customer master key managed by customer. + * If `encryptionKey` is specified, this key will be used, otherwise, one will be defined. + * + * > **NOTE**: if `encryptionKey` is not specified and the `Table` construct creates + * > a KMS key for you, the key will be created with default permissions. If you are using + * > CDKv2, these permissions will be sufficient to enable the key for use with DynamoDB tables. + * > If you are using CDKv1, make sure the feature flag `@aws-cdk/aws-kms:defaultKeyPolicies` + * > is set to `true` in your `cdk.json`. + */ + CUSTOMER_MANAGED = 'CUSTOMER_MANAGED', + + /** + * Server-side KMS encryption with a master key managed by AWS. + */ + AWS_MANAGED = 'AWS_MANAGED', +} + +/** + * When an item in the table is modified, StreamViewType determines what information + * is written to the stream for this table. + * + * @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_StreamSpecification.html + */ +export enum StreamViewType { + /** + * The entire item, as it appears after it was modified, is written to the stream. + */ + NEW_IMAGE = 'NEW_IMAGE', + + /** + * The entire item, as it appeared before it was modified, is written to the stream. + */ + OLD_IMAGE = 'OLD_IMAGE', + + /** + * Both the new and the old item images of the item are written to the stream. + */ + NEW_AND_OLD_IMAGES = 'NEW_AND_OLD_IMAGES', + + /** + * Only the key attributes of the modified item are written to the stream. + */ + KEYS_ONLY = 'KEYS_ONLY' +} + +/** + * Properties for a secondary index + */ +export interface SecondaryIndexProps { + /** + * The name of the secondary index. + */ + readonly indexName: string; + + /** + * The set of attributes that are projected into the secondary index. + * @default ALL + */ + readonly projectionType?: ProjectionType; + + /** + * The non-key attributes that are projected into the secondary index. + * @default - No additional attributes + */ + readonly nonKeyAttributes?: string[]; +} + +/** + * Properties for a local secondary index + */ +export interface LocalSecondaryIndexProps extends SecondaryIndexProps { + /** + * The attribute of a sort key for the local secondary index. + */ + readonly sortKey: Attribute; +} + +/** + * An interface that represents a DynamoDB Table - either created with the CDK, or an existing one. + */ +export interface ITable extends IResource { + /** + * Arn of the dynamodb table. + * + * @attribute + */ + readonly tableArn: string; + + /** + * Table name of the dynamodb table. + * + * @attribute + */ + readonly tableName: string; + + /** + * ARN of the table's stream, if there is one. + * + * @attribute + */ + readonly tableStreamArn?: string; + + /** + * + * Optional KMS encryption key associated with this table. + */ + readonly encryptionKey?: kms.IKey; + + /** + * Adds an IAM policy statement associated with this table to an IAM + * principal's policy. + * + * If `encryptionKey` is present, appropriate grants to the key needs to be added + * separately using the `table.encryptionKey.grant*` methods. + * + * @param grantee The principal (no-op if undefined) + * @param actions The set of actions to allow (i.e. "dynamodb:PutItem", "dynamodb:GetItem", ...) + */ + grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant; + + /** + * Adds an IAM policy statement associated with this table's stream to an + * IAM principal's policy. + * + * If `encryptionKey` is present, appropriate grants to the key needs to be added + * separately using the `table.encryptionKey.grant*` methods. + * + * @param grantee The principal (no-op if undefined) + * @param actions The set of actions to allow (i.e. "dynamodb:DescribeStream", "dynamodb:GetRecords", ...) + */ + grantStream(grantee: iam.IGrantable, ...actions: string[]): iam.Grant; + + /** + * Permits an IAM principal all data read operations from this table: + * BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan. + * + * Appropriate grants will also be added to the customer-managed KMS key + * if one was configured. + * + * @param grantee The principal to grant access to + */ + grantReadData(grantee: iam.IGrantable): iam.Grant; + + /** + * Permits an IAM Principal to list streams attached to current dynamodb table. + * + * @param grantee The principal (no-op if undefined) + */ + grantTableListStreams(grantee: iam.IGrantable): iam.Grant; + + /** + * Permits an IAM principal all stream data read operations for this + * table's stream: + * DescribeStream, GetRecords, GetShardIterator, ListStreams. + * + * Appropriate grants will also be added to the customer-managed KMS key + * if one was configured. + * + * @param grantee The principal to grant access to + */ + grantStreamRead(grantee: iam.IGrantable): iam.Grant; + + /** + * Permits an IAM principal all data write operations to this table: + * BatchWriteItem, PutItem, UpdateItem, DeleteItem. + * + * Appropriate grants will also be added to the customer-managed KMS key + * if one was configured. + * + * @param grantee The principal to grant access to + */ + grantWriteData(grantee: iam.IGrantable): iam.Grant; + + /** + * Permits an IAM principal to all data read/write operations to this table. + * BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, + * BatchWriteItem, PutItem, UpdateItem, DeleteItem + * + * Appropriate grants will also be added to the customer-managed KMS key + * if one was configured. + * + * @param grantee The principal to grant access to + */ + grantReadWriteData(grantee: iam.IGrantable): iam.Grant; + + /** + * Permits all DynamoDB operations ("dynamodb:*") to an IAM principal. + * + * Appropriate grants will also be added to the customer-managed KMS key + * if one was configured. + * + * @param grantee The principal to grant access to + */ + grantFullAccess(grantee: iam.IGrantable): iam.Grant; + + /** + * Metric for the number of Errors executing all Lambdas + */ + metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric; + + /** + * Metric for the consumed read capacity units + * + * @param props properties of a metric + */ + metricConsumedReadCapacityUnits(props?: cloudwatch.MetricOptions): cloudwatch.Metric; + + /** + * Metric for the consumed write capacity units + * + * @param props properties of a metric + */ + metricConsumedWriteCapacityUnits(props?: cloudwatch.MetricOptions): cloudwatch.Metric; + + /** + * Metric for the system errors + * + * @param props properties of a metric + * + * @deprecated use `metricSystemErrorsForOperations` + */ + metricSystemErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric; + + /** + * Metric for the system errors this table + * + * @param props properties of a metric + * + */ + metricSystemErrorsForOperations(props?: SystemErrorsForOperationsMetricOptions): cloudwatch.IMetric; + + /** + * Metric for the user errors + * + * @param props properties of a metric + */ + metricUserErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric; + + /** + * Metric for the conditional check failed requests + * + * @param props properties of a metric + */ + metricConditionalCheckFailedRequests(props?: cloudwatch.MetricOptions): cloudwatch.Metric; + + /** + * Metric for throttled requests + * + * @param props properties of a metric + * + * @deprecated use `metricThrottledRequestsForOperations` + */ + metricThrottledRequests(props?: cloudwatch.MetricOptions): cloudwatch.Metric; + + /** + * Metric for throttled requests + * + * @param props properties of a metric + * + */ + metricThrottledRequestsForOperations(props?: OperationsMetricOptions): cloudwatch.IMetric; + + /** + * Metric for the successful request latency + * + * @param props properties of a metric + * + */ + metricSuccessfulRequestLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric; +} diff --git a/packages/aws-cdk-lib/aws-dynamodb/lib/table-v2-base.ts b/packages/aws-cdk-lib/aws-dynamodb/lib/table-v2-base.ts new file mode 100644 index 0000000000000..9c9607a74404c --- /dev/null +++ b/packages/aws-cdk-lib/aws-dynamodb/lib/table-v2-base.ts @@ -0,0 +1,460 @@ +import { DynamoDBMetrics } from './dynamodb-canned-metrics.generated'; +import * as perms from './perms'; +import { Operation, SystemErrorsForOperationsMetricOptions, OperationsMetricOptions, ITable } from './shared'; +import { IMetric, MathExpression, Metric, MetricOptions, MetricProps } from '../../aws-cloudwatch'; +import { Grant, IGrantable } from '../../aws-iam'; +import { IKey } from '../../aws-kms'; +import { Resource } from '../../core'; + +/** + * Represents an instance of a DynamoDB table. + */ +export interface ITableV2 extends ITable { + /** + * The ID of the table. + * + * @attribute + */ + readonly tableId?: string; +} + +/** + * Base class for a DynamoDB table. + */ +export abstract class TableBaseV2 extends Resource implements ITableV2 { + /** + * The ARN of the table. + * + * @attribute + */ + public abstract readonly tableArn: string; + + /** + * The name of the table. + * + * @attribute + */ + public abstract readonly tableName: string; + + /** + * The stream ARN of the table. + * + * @attribute + */ + public abstract readonly tableStreamArn?: string; + + /** + * The ID of the table. + * + * @attribute + */ + public abstract readonly tableId?: string; + + /** + * The KMS encryption key for the table. + */ + public abstract readonly encryptionKey?: IKey; + + protected abstract readonly region: string; + + protected abstract get hasIndex(): boolean; + + /** + * Adds an IAM policy statement associated with this table to an IAM principal's policy. + * + * Note: If `encryptionKey` is present, appropriate grants to the key needs to be added + * separately using the `table.encryptionKey.grant*` methods. + * + * @param grantee the principal (no-op if undefined) + * @param actions the set of actions to allow (i.e., 'dynamodb:PutItem', 'dynamodb:GetItem', etc.) + */ + public grant(grantee: IGrantable, ...actions: string[]): Grant { + const resourceArns = [this.tableArn]; + this.hasIndex && resourceArns.push(`${this.tableArn}/index/*`); + return Grant.addToPrincipal({ + grantee, + actions, + resourceArns, + scope: this, + }); + } + + /** + * Adds an IAM policy statement associated with this table to an IAM principal's policy. + * + * Note: If `encryptionKey` is present, appropriate grants to the key needs to be added + * separately using the `table.encryptionKey.grant*` methods. + * + * @param grantee the principal (no-op if undefined) + * @param actions the set of actions to allow (i.e., 'dynamodb:DescribeStream', 'dynamodb:GetRecords', etc.) + */ + public grantStream(grantee: IGrantable, ...actions: string[]): Grant { + if (!this.tableStreamArn) { + throw new Error(`No stream ARN found on the table ${this.node.path}`); + } + + return Grant.addToPrincipal({ + grantee, + actions, + resourceArns: [this.tableStreamArn], + }); + } + + /** + * Adds an IAM policy statement associated with this table to an IAM principal's policy. + * + * Actions: DescribeStream, GetRecords, GetShardIterator, ListStreams. + * + * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this + * table if one was configured. + * + * @param grantee the principal to grant access to + */ + public grantStreamRead(grantee: IGrantable): Grant { + this.grantTableListStreams(grantee); + + const keyActions = perms.KEY_READ_ACTIONS; + const streamActions = perms.READ_STREAM_DATA_ACTIONS; + + return this.combinedGrant(grantee, { keyActions, streamActions }); + } + + /** + * Permits an IAM principal to list streams attached to this table. + * + * @param grantee the principal to grant access to + */ + public grantTableListStreams(grantee: IGrantable): Grant { + if (!this.tableStreamArn) { + throw new Error(`No stream ARN found on the table ${this.node.path}`); + } + + return Grant.addToPrincipal({ + grantee, + actions: ['dynamodb:ListStreams'], + resourceArns: [this.tableStreamArn], + }); + } + + /** + * Permits an IAM principal all data read operations on this table. + * + * Actions: BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, DescribeTable. + * + * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this + * table if one was configured. + * + * @param grantee the principal to grant access to + */ + public grantReadData(grantee: IGrantable): Grant { + const tableActions = perms.READ_DATA_ACTIONS.concat(perms.DESCRIBE_TABLE); + return this.combinedGrant(grantee, { keyActions: perms.KEY_READ_ACTIONS, tableActions }); + } + + /** + * Permits an IAM principal all data write operations on this table. + * + * Actions: BatchWriteItem, PutItem, UpdateItem, DeleteItem, DescribeTable. + * + * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this + * table if one was configured. + * + * @param grantee the principal to grant access to + */ + public grantWriteData(grantee: IGrantable): Grant { + const tableActions = perms.WRITE_DATA_ACTIONS.concat(perms.DESCRIBE_TABLE); + const keyActions = perms.KEY_READ_ACTIONS.concat(perms.KEY_WRITE_ACTIONS); + return this.combinedGrant(grantee, { keyActions, tableActions }); + } + + /** + * Permits an IAM principal to all data read/write operations on this table. + * + * Actions: BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, BatchWriteItem, PutItem, UpdateItem, + * DeleteItem, DescribeTable. + * + * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this + * table if one was configured. + * + * @param grantee the principal to grant access to + */ + public grantReadWriteData(grantee: IGrantable): Grant { + const tableActions = perms.READ_DATA_ACTIONS.concat(perms.WRITE_DATA_ACTIONS).concat(perms.DESCRIBE_TABLE); + const keyActions = perms.KEY_READ_ACTIONS.concat(perms.KEY_WRITE_ACTIONS); + return this.combinedGrant(grantee, { keyActions, tableActions }); + } + + /** + * Permits an IAM principal to all DynamoDB operations ('dynamodb:*') on this table. + * + * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this + * table if one was configured. + * + * @param grantee the principal to grant access to + */ + public grantFullAccess(grantee: IGrantable): Grant { + const keyActions = perms.KEY_READ_ACTIONS.concat(perms.KEY_WRITE_ACTIONS); + return this.combinedGrant(grantee, { keyActions, tableActions: ['dynamodb:*'] }); + } + + /** + * Return the given named metric for this table. + * + * By default, the metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metric(metricName: string, props?: MetricOptions): Metric { + const metricProps: MetricProps = { + namespace: 'AWS/DynamoDB', + metricName, + dimensionsMap: { TableName: this.tableName }, + ...props, + }; + return this.configureMetric(metricProps); + } + + /** + * Metric for the consumed read capacity units for this table. + * + * By default, the metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricConsumedReadCapacityUnits(props?: MetricOptions): Metric { + const metricProps: MetricProps = { + ...DynamoDBMetrics.consumedReadCapacityUnitsSum({ TableName: this.tableName }), + ...props, + }; + return this.configureMetric(metricProps); + } + + /** + * Metric for the consumed write capacity units for this table. + * + * By default, the metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricConsumedWriteCapacityUnits(props?: MetricOptions): Metric { + const metricProps: MetricProps = { + ...DynamoDBMetrics.consumedWriteCapacityUnitsSum({ TableName: this.tableName }), + ...props, + }; + return this.configureMetric(metricProps); + } + + /** + * Metric for the user errors for this table. + * + * Note: This metric reports user errors across all the tables in the account and region the table + * resides in. + * + * By default, the metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricUserErrors(props?: MetricOptions): Metric { + if (props?.dimensions) { + throw new Error('`dimensions` is not supported for the `UserErrors` metric'); + } + + return this.metric('UserErrors', { statistic: 'sum', ...props, dimensionsMap: {} }); + } + + /** + * Metric for the conditional check failed requests for this table. + * + * By default, the metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricConditionalCheckFailedRequests(props?: MetricOptions): Metric { + return this.metric('ConditionalCheckFailedRequests', { statistic: 'sum', ...props }); + } + + /** + * Metric for the successful request latency for this table. + * + * By default, the metric will be calculated as an average over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricSuccessfulRequestLatency(props?: MetricOptions): Metric { + if (!props?.dimensions?.Operation && !props?.dimensionsMap?.Operation) { + throw new Error('`Operation` dimension must be passed for the `SuccessfulRequestLatency` metric'); + } + + const dimensionsMap = { + TableName: this.tableName, + Operation: props.dimensionsMap?.Operation ?? props.dimensions?.Operation, + }; + + const metricProps: MetricProps = { + ...DynamoDBMetrics.successfulRequestLatencyAverage(dimensionsMap), + ...props, + dimensionsMap, + }; + return this.configureMetric(metricProps); + } + + /** + * How many requests are throttled on this table for the given operation + * + * By default, the metric will be calculated as an average over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricThrottledRequestsForOperation(operation: string, props?: OperationsMetricOptions): IMetric { + const metricProps: MetricProps = { + ...DynamoDBMetrics.throttledRequestsSum({ Operation: operation, TableName: this.tableName }), + ...props, + }; + return this.configureMetric(metricProps); + } + + /** + * How many requests are throttled on this table. This will sum errors across all possible operations. + * + * By default, each individual metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricThrottledRequestsForOperations(props?: OperationsMetricOptions): IMetric { + return this.sumMetricsForOperations('ThrottledRequests', 'Sum of throttled requests across all operations', props); + } + + /** + * Metric for the system errors for this table. This will sum errors across all possible operations. + * + * By default, each individual metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + */ + public metricSystemErrorsForOperations(props?: SystemErrorsForOperationsMetricOptions): IMetric { + return this.sumMetricsForOperations('SystemErrors', 'Sum of errors across all operations', props); + } + + /** + * How many requests are throttled on this table. + * + * By default, each individual metric will be calculated as a sum over a period of 5 minutes. + * You can customize this by using the `statistic` and `period` properties. + * + * @deprecated Do not use this function. It returns an invalid metric. Use `metricThrottledRequestsForOperation` instead. + */ + public metricThrottledRequests(props?: MetricOptions): Metric { + return this.metric('ThrottledRequests', { statistic: 'sum', ...props }); + } + + /** + * Metric for the system errors this table + * + * @deprecated use `metricSystemErrorsForOperations`. + */ + public metricSystemErrors(props?: MetricOptions): Metric { + if (!props?.dimensions?.Operation && !props?.dimensionsMap?.Operation) { + // 'Operation' must be passed because its an operational metric. + throw new Error("'Operation' dimension must be passed for the 'SystemErrors' metric."); + } + + const dimensionsMap = { + TableName: this.tableName, + ...props?.dimensions ?? {}, + ...props?.dimensionsMap ?? {}, + }; + + return this.metric('SystemErrors', { statistic: 'sum', ...props, dimensionsMap }); + } + + /** + * Create a math expression for operations. + */ + private sumMetricsForOperations(metricName: string, expressionLabel: string, props?: OperationsMetricOptions) { + if (props?.dimensions?.Operation) { + throw new Error('The Operation dimension is not supported. Use the `operations` property'); + } + + const operations = props?.operations ?? Object.values(Operation); + const values = this.createMetricForOperations(metricName, operations, { statistic: 'sum', ...props }); + const sum = new MathExpression({ + expression: `${Object.keys(values).join(' + ')}`, + usingMetrics: { ...values }, + color: props?.color, + label: expressionLabel, + period: props?.period, + }); + + return sum; + } + + /** + * Create a map of metrics that can be used in a math expression. + * + * Using the return value of this function as the `usingMetrics` property in `cloudwatch.MathExpression` allows you to + * use the keys of this map as metric names inside you expression. + */ + private createMetricForOperations(metricName: string, operations: Operation[], props?: MetricOptions, + metricNameMapper?: (op: Operation) => string) { + const metrics: Record