feat(dynamodb): add seed capacity property to support changing table …

…billing mode (#27734)

This PR adds `seedCapacity` as a property on the `AutoscaledCapacityOptions` interface. `seedCapacity` must be provided for each autoscaled resource when changing a table's billing from on-demand to provisioned or from provisioned to on-demand.

Closes #27735.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk-testing/framework-integ/test/aws-dynamodb/test/integ.table-v2-global.js.snapshot/aws-cdk-global-table.template.json

@@ -49,6 +49,7 @@
        "WriteCapacityAutoScalingSettings": {
         "MaxCapacity": 20,
         "MinCapacity": 1,
+        "SeedCapacity": 10,
         "TargetTrackingScalingPolicyConfiguration": {
          "TargetValue": 60
         }
@@ -251,6 +252,7 @@
      "WriteCapacityAutoScalingSettings": {
       "MaxCapacity": 20,
       "MinCapacity": 1,
+      "SeedCapacity": 10,
       "TargetTrackingScalingPolicyConfiguration": {
        "TargetValue": 60
       }

packages/@aws-cdk-testing/framework-integ/test/aws-dynamodb/test/integ.table-v2-global.ts

@@ -16,7 +16,7 @@ class TestStack extends Stack {
       sortKey: { name: 'sk', type: AttributeType.NUMBER },
       billing: Billing.provisioned({
         readCapacity: Capacity.fixed(10),
-        writeCapacity: Capacity.autoscaled({ maxCapacity: 20, targetUtilizationPercent: 60 }),
+        writeCapacity: Capacity.autoscaled({ maxCapacity: 20, targetUtilizationPercent: 60, seedCapacity: 10 }),
       }),
       encryption: TableEncryptionV2.awsManagedKey(),
       contributorInsights: true,

packages/aws-cdk-lib/aws-dynamodb/README.md

@@ -201,6 +201,18 @@ const globalTable = new dynamodb.TableV2(stack, 'GlobalTable', {
 });
 ```
 
+When changing the billing for a table from provisioned to on-demand or from on-demand to provisioned, `seedCapacity` must be configured for each autoscaled resource:
+
+```ts
+const globalTable = new dynamodb.TableV2(this, 'Table', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+  billing: dynamodb.Billing.provisioned({
+    readCapacity: dynamodb.Capacity.fixed(10),
+    writeCapacity: dynamodb.Capacity.autoscaled({ maxCapacity: 10, seedCapacity: 20 }),
+  }),
+});
+```
+
 Further reading:
 https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html
 

packages/aws-cdk-lib/aws-dynamodb/lib/capacity.ts

@@ -39,7 +39,16 @@ export interface AutoscaledCapacityOptions {
    *
    * @default 70
    */
-  readonly targetUtilizationPercent?: number
+  readonly targetUtilizationPercent?: number;
+
+  /**
+   * If you want to switch a table's billing mode from on-demand to provisioned or
+   * from provisioned to on-demand, you must specify a value for this property for
+   * each autoscaled resource.
+   *
+   * @default no seed capacity
+   */
+  readonly seedCapacity?: number;
 }
 
 /**
@@ -85,6 +94,10 @@ export abstract class Capacity {
         if (options.targetUtilizationPercent !== undefined && (options.targetUtilizationPercent < 20 || options.targetUtilizationPercent > 90)) {
           throw new Error('`targetUtilizationPercent` cannot be less than 20 or greater than 90');
         }
+
+        if (options.seedCapacity !== undefined && (options.seedCapacity < 1)) {
+          throw new Error(`'seedCapacity' cannot be less than 1 - received ${options.seedCapacity}`);
+        }
       }
 
       public _renderReadCapacity() {
@@ -103,6 +116,7 @@ export abstract class Capacity {
         return {
           minCapacity: options.minCapacity ?? 1,
           maxCapacity: options.maxCapacity,
+          seedCapacity: options.seedCapacity,
           targetTrackingScalingPolicyConfiguration: {
             targetValue: options.targetUtilizationPercent ?? 70,
           },

packages/aws-cdk-lib/aws-dynamodb/test/capacity.test.ts

@@ -90,6 +90,23 @@ describe('autoscaled capacity', () => {
     });
   });
 
+  test('can specify seed capacity', () => {
+    // GIVEN
+    const capacity = Capacity.autoscaled({ maxCapacity: 10, seedCapacity: 20 });
+
+    // WHEN / THEN
+    expect(capacity._renderReadCapacity()).toEqual({
+      readCapacityAutoScalingSettings: {
+        minCapacity: 1,
+        maxCapacity: 10,
+        seedCapacity: 20,
+        targetTrackingScalingPolicyConfiguration: {
+          targetValue: 70,
+        },
+      },
+    });
+  });
+
   test('capacity mode is AUTOSCALED', () => {
     // GIVEN
     const capacity = Capacity.autoscaled({ minCapacity: 1, maxCapacity: 10 });
@@ -118,4 +135,11 @@ describe('autoscaled capacity', () => {
       Capacity.autoscaled({ maxCapacity: 10, targetUtilizationPercent: 91 });
     }).toThrow('`targetUtilizationPercent` cannot be less than 20 or greater than 90');
   });
+
+  test('throws if seed capacity is less than 1', () => {
+    // GIVEN / WHEN / THEN
+    expect(() => {
+      Capacity.autoscaled({ maxCapacity: 10, seedCapacity: 0 });
+    }).toThrow("'seedCapacity' cannot be less than 1 - received 0");
+  });
 });