(ec2): support throughput option in EBS volume

[jumic]

For EBS volumes with volume type GP3, the throughput in MiB/s can be configured. This is currently not supported in CDK.

Workaround: use escape hatches

Use Case

Set custom value for throughput, impacts performance and pricing.

Proposed Solution

The property is available in ebs volume and launchtemplate blockdevicemaping. It should be supported in both constructs.

Check if the property can be added to EbsDeviceOptionsBase or only to one of its subclasses (EbsDeviceOptions and EbsDeviceSnapshotOptions). Nothing specific is mentioned in the documentation.

Display a warning if throughput is defined for a volume type that does not support specifying a throughput. Display an error if a throughput value is specified that is not supported.

Other

Originally mentioned as comment in issue #12020.

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change

---

This is a 🚀 Feature Request

[njlynch]

Thanks for the feature request!

We welcome community contributions! If you are able, we encourage you to contribute. If you decide to contribute, please start an engineering discussion in this issue to ensure there is a commonly understood design before submitting code. This will minimize the number of review cycles and get your code merged faster.

[jumic]

@njlynch I would propose the following implementation. Do you have any comments?
Could you please give me a short feedback to my questions? Thanks.

Add new property throughput (specified in MiB/s) to VolumeProps and EbsDeviceOptionsBase.
In Construct LaunchTemplate, throughput can be used when a volume is created and when it is restored. I did a short test with LaunchTemplate in combination with BlockDeviceVolume.ebsFromSnapshot(). Therefore, it should be correct to add it to interface EbsDeviceOptionsBase which is used for creating and restoring volumes.

readonly throughput?: number;

Add validation in validateProps().

• Throw error if throughput is used for EbsDeviceVolumeType != GP3.
• Throw error if value is not in supported range (Minimum value of 125. Maximum value of 1000)

Add validation in synthesizeBlockDeviceMappings().

• Throw error if throughput is used for EbsDeviceVolumeType != GP3. Question: Should this be an error? For iops only a warning is added if it is used for unsupported volume types. However, this behavior is not consistent to validateProps().
• Throw error if value is not in supported range (Minimum value of 125. Maximum value of 1000). Question: Should this be validated? The valid ranges for iops are not validated in this method. Again, this behavior is not consistent to validateProps().
• Throw error if throughput is used in property BlockDeviceMapping for EC2 instances. This is currently not supported (see AWS::EC2::Instance - BlockDeviceMapping-Ebs-Throughput should support gp3 Throughput attribute aws-cloudformation/cloudformation-coverage-roadmap#824).

Add unit test cases and create integration tests that show Volume and LaunchTemplate with throughput can be deployed.

[jonyjalfon94]

Hey, i just stumbled upon this issue while looking for a way of defining the throughput of GP3 volumes.
I understand from this PR that it's not currently supported via the aws_ec2.BlockDeviceVolume.ebs function.

Until this feature is merged, is there any workaround for defining it?

[csumpter]

Hey, i just stumbled upon this issue while looking for a way of defining the throughput of GP3 volumes. I understand from this PR that it's not currently supported via the aws_ec2.BlockDeviceVolume.ebs function.

Until this feature is merged, is there any workaround for defining it?

You can do something like:

    interface ExtendedEbsDeviceOptions extends autoscaling.EbsDeviceOptions {
      throughput: number;
    }

    const asg = new autoscaling.AutoScalingGroup(this, "example", {
      blockDevices: [{
        deviceName: "/dev/sda1",
        volume: autoscaling.BlockDeviceVolume.ebs(1, {
         ...
          volumeType: autoscaling.EbsDeviceVolumeType.GP3,
          throughput: 125,
        } as ExtendedEbsDeviceOptions),
      }],
      ...
    })

This extends the type to include throughput where it will becomes rendered as Throughput by the cdk as it transforms that property.

There are other ways to get the throughput property rendered out with the resource but this is probably the easiest.

If you need to do get the compatibility for an ec2 volume you would do something like:

    interface Ec2VolumeExtended extends ec2.VolumeProps {
      throughput: number;
    }
    const volume = new ec2.Volume(this, "volume", {
      volumeType: ec2.EbsDeviceVolumeType.GP3,
      throughput: 125,
      ...
    } as Ec2VolumeExtended)

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

[aldredb]

@csumpter I don't think the workaround works. This is my code:

export interface ExtendedEbsDeviceOptions extends aws_ec2.EbsDeviceOptions {
    throughput: number;
}

blockDevices: [{
        deviceName: '/dev/xvda',
        volume: aws_ec2.BlockDeviceVolume.ebs(3000, {
            deleteOnTermination: true,
            encrypted: false,
            iops: 16000,
            volumeType: EbsDeviceVolumeType.GP3,
            throughput: 1000,
          } as ExtendedEbsDeviceOptions),
      },
    ]

The throughput is not translated to CF template

[csumpter]

@aldredb You should be able to upgrade to the latest aws-cdk release which now includes support/types for the throughput property.

[aldredb]

@csumpter Yep i used the 2.54.0 release. The throughput property is included in aws_autoscaling.EbsDeviceOptionsBase and aws_ec2.VolumeProps, but not aws_ec2.EbsDeviceOptionsBase, which the static function aws_ec2.BlockDeviceVolume.ebs takes as an argument.

[csumpter]

@aldredb

You are correct that the throughput property is missing from EbsDeviceOptionsBase. Let's add a PR for that addition as it was not caught in the PR review, and I did not see that extra static method at the time I was writing the original PR.

In the meantime are you trying to create a EC2 instance in the example you gave?

[aldredb]

@csumpter

Yes. I'm trying to use this: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Instance.html#blockdevices

[csumpter]

@csumpter

Yes. I'm trying to use this: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Instance.html#blockdevices

@aldredb I don't believe you can set a Throughput property on ebs block devices - see the CFN docs here: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-blockdev-template.html

[tmokmss]

I also stumbled on this today for launch templates. Here's the workaround:

const launchTemplate = new ec2.LaunchTemplate(this, 'LaunchTemplate', {
  // omitting other required properties
  blockDevices: [
    {
      deviceName: '/dev/xvda',
      volume: ec2.BlockDeviceVolume.ebs(100, {
        volumeType: ec2.EbsDeviceVolumeType.GP3,
      }),
    },
  ],
});
(launchTemplate.node.defaultChild as CfnResource).addPropertyOverride("LaunchTemplateData.BlockDeviceMappings.0.Ebs.Throughput", 200)

I'm not sure why LaunchTemplate ebs supports throughput (doc), whereas instance ebs not (doc).

edit)
I found the corresponding issue on CFn repo: aws-cloudformation/cloudformation-coverage-roadmap#824