feat(ec2): support throughput on LaunchTemplate EBS volumes

This support was simply not included in ec2 when it was added to
autoscaling in aws#22441. I have copied that PR's implementation
implementation to ec2 and similarly adapted its tests.

Fixes aws#24341.

packages/@aws-cdk-testing/framework-integ/test/aws-ec2/test/integ.launch-template.js.snapshot/aws-cdk-ec2-lt-metadata-1.template.json

@@ -159,6 +159,16 @@
    "Type": "AWS::EC2::LaunchTemplate",
    "Properties": {
     "LaunchTemplateData": {
+     "BlockDeviceMappings": [
+      {
+       "DeviceName": "/dev/xvda",
+       "Ebs": {
+        "Throughput": 250,
+        "VolumeSize": 15,
+        "VolumeType": "gp3"
+       }
+      }
+     ],
      "MetadataOptions": {
       "HttpEndpoint": "enabled",
       "HttpProtocolIpv6": "enabled",

packages/@aws-cdk-testing/framework-integ/test/aws-ec2/test/integ.launch-template.ts

@@ -23,6 +23,13 @@ const lt = new ec2.LaunchTemplate(stack, 'LT', {
   httpTokens: ec2.LaunchTemplateHttpTokens.REQUIRED,
   instanceMetadataTags: true,
   securityGroup: sg1,
+  blockDevices: [{
+    deviceName: '/dev/xvda',
+    volume: ec2.BlockDeviceVolume.ebs(15, {
+      volumeType: ec2.EbsDeviceVolumeType.GP3,
+      throughput: 250,
+    }),
+  }],
 });
 
 const sg2 = new ec2.SecurityGroup(stack, 'sg2', {

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

@@ -1603,6 +1603,33 @@ new ec2.Instance(this, 'Instance', {
 
 ```
 
+To specify the throughput value for `gp3` volumes, use the `throughput` property:
+
+```ts
+declare const vpc: ec2.Vpc;
+declare const instanceType: ec2.InstanceType;
+declare const machineImage: ec2.IMachineImage;
+
+new ec2.Instance(this, 'Instance', {
+  vpc,
+  instanceType,
+  machineImage,
+
+  // ...
+
+  blockDevices: [
+    {
+      deviceName: '/dev/sda1',
+      volume: ec2.BlockDeviceVolume.ebs(100, {
+        volumeType: ec2.EbsDeviceVolumeType.GP3,
+        throughput: 250,
+      }),
+    },
+  ],
+});
+
+```
+
 #### EBS Optimized Instances
 
 An Amazon EBS–optimized instance uses an optimized configuration stack and provides additional, dedicated capacity for Amazon EBS I/O. This optimization provides the best performance for your EBS volumes by minimizing contention between Amazon EBS I/O and other traffic from your instance.

packages/aws-cdk-lib/aws-ec2/lib/private/ebs-util.ts

@@ -25,7 +25,29 @@ function synthesizeBlockDeviceMappings<RT, NDT>(construct: Construct, blockDevic
 
     if (ebs) {
 
-      const { iops, volumeType, kmsKey, ...rest } = ebs;
+      const { iops, throughput, volumeType, kmsKey, ...rest } = ebs;
+
+      if (throughput) {
+        if (volumeType !== EbsDeviceVolumeType.GP3) {
+          throw new Error(`'throughput' requires 'volumeType': ${EbsDeviceVolumeType.GP3}, got: ${volumeType}.`);
+        }
+
+        if (!Number.isInteger(throughput)) {
+          throw new Error(`'throughput' must be an integer, got: ${throughput}.`);
+        }
+
+        if (throughput < 125 || throughput > 1000) {
+          throw new Error(`'throughput' must be between 125 and 1000, got ${throughput}.`);
+        }
+
+        const maximumThroughputRatio = 0.25;
+        if (iops) {
+          const iopsRatio = (throughput / iops);
+          if (iopsRatio > maximumThroughputRatio) {
+            throw new Error(`Throughput (MiBps) to iops ratio of ${iopsRatio} is too high; maximum is ${maximumThroughputRatio} MiBps per iops`);
+          }
+        }
+      }
 
       if (!iops) {
         if (volumeType === EbsDeviceVolumeType.IO1 || volumeType === EbsDeviceVolumeType.IO2) {
@@ -43,6 +65,7 @@ function synthesizeBlockDeviceMappings<RT, NDT>(construct: Construct, blockDevic
       finalEbs = {
         ...rest,
         iops,
+        throughput,
         volumeType,
         kmsKeyId: kmsKey?.keyArn,
       };