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

@@ -22,6 +22,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;
+
+const kmsKey = new Key(this, 'KmsKey')
+
+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,25 @@ 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 (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 +61,7 @@ function synthesizeBlockDeviceMappings<RT, NDT>(construct: Construct, blockDevic
       finalEbs = {
         ...rest,
         iops,
+        throughput,
         volumeType,
         kmsKeyId: kmsKey?.keyArn,
       };

packages/aws-cdk-lib/aws-ec2/lib/volume.ts

@@ -70,6 +70,17 @@ export interface EbsDeviceOptionsBase {
    * `@aws-cdk/aws-ec2:ebsDefaultGp3Volume` is enabled.
    */
   readonly volumeType?: EbsDeviceVolumeType;
+
+  /**
+   * The throughput to provision for a `gp3` volume.
+   *
+   * Valid Range: Minimum value of 125. Maximum value of 1000.
+   *
+   * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
+   *
+   * @default - 125 MiB/s.
+   */
+  readonly throughput?: number;
 }
 
 /**

packages/aws-cdk-lib/aws-ec2/test/launch-template.test.ts

@@ -314,6 +314,12 @@ describe('LaunchTemplate', () => {
       }, {
         deviceName: 'ephemeral',
         volume: BlockDeviceVolume.ephemeral(0),
+      }, {
+        deviceName: 'gp3-with-throughput',
+        volume: BlockDeviceVolume.ebs(15, {
+          volumeType: EbsDeviceVolumeType.GP3,
+          throughput: 350,
+        }),
       },
     ];
 
@@ -366,10 +372,60 @@ describe('LaunchTemplate', () => {
             DeviceName: 'ephemeral',
             VirtualName: 'ephemeral0',
           },
+          {
+            DeviceName: 'gp3-with-throughput',
+            Ebs: {
+              VolumeSize: 15,
+              VolumeType: 'gp3',
+              Throughput: 350,
+            },
+          },
         ],
       },
     });
   });
+  test.each([124, 1001])('throws if throughput is set less than 125 or more than 1000', (throughput) => {
+    expect(() => {
+      new LaunchTemplate(stack, 'LaunchTemplate', {
+        blockDevices: [{
+          deviceName: 'ebs',
+          volume: BlockDeviceVolume.ebs(15, {
+            volumeType: EbsDeviceVolumeType.GP3,
+            throughput,
+          }),
+        }],
+      });
+    }).toThrow(/throughput property takes a minimum of 125 and a maximum of 1000/);
+  });
+  test.each([
+    ...Object.values(EbsDeviceVolumeType).filter((v) => v !== 'gp3'),
+  ])('throws if throughput is set on any volume type other than GP3', (volumeType) => {
+    expect(() => {
+      new LaunchTemplate(stack, 'LaunchTemplate', {
+        blockDevices: [{
+          deviceName: 'ebs',
+          volume: BlockDeviceVolume.ebs(15, {
+            volumeType: volumeType,
+            throughput: 150,
+          }),
+        }],
+      });
+    }).toThrow(/throughput property requires volumeType: EbsDeviceVolumeType.GP3/);
+  });
+  test('throws if throughput / iops ratio is greater than 0.25', () => {
+    expect(() => {
+      new LaunchTemplate(stack, 'LaunchTemplate', {
+        blockDevices: [{
+          deviceName: 'ebs',
+          volume: BlockDeviceVolume.ebs(15, {
+            volumeType: EbsDeviceVolumeType.GP3,
+            throughput: 751,
+            iops: 3000,
+          }),
+        }],
+      });
+    }).toThrow('Throughput (MiBps) to iops ratio of 0.25033333333333335 is too high; maximum is 0.25 MiBps per iops');
+  });
 
   test('Given instance profile', () => {
     // GIVEN