class Volume (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.EC2.Volume`
Go	`github.com/aws/aws-cdk-go/awscdk/v2/awsec2#Volume`
Java	`software.amazon.awscdk.services.ec2.Volume`
Python	`aws_cdk.aws_ec2.Volume`
TypeScript (source)	`aws-cdk-lib` » `aws_ec2` » `Volume`

Implements IConstruct, IDependable, IResource, IVolume

Creates a new EBS Volume in AWS EC2.

Example

declare const instance: ec2.Instance;
declare const role: iam.Role;

const volume = new ec2.Volume(this, 'Volume', {
  availabilityZone: 'us-west-2a',
  size: Size.gibibytes(500),
  encrypted: true,
});

volume.grantAttachVolume(role, [instance]);

Initializer

new Volume(scope: Construct, id: string, props: VolumeProps)

Parameters

scope Construct
id string
props VolumeProps

Construct Props

Name	Type	Description
availabilityZone	`string`	The Availability Zone in which to create the volume.
autoEnableIo?	`boolean`	Indicates whether the volume is auto-enabled for I/O operations.
enableMultiAttach?	`boolean`	Indicates whether Amazon EBS Multi-Attach is enabled.
encrypted?	`boolean`	Specifies whether the volume should be encrypted.
encryptionKey?	`IKey`	The customer-managed encryption key that is used to encrypt the Volume.
iops?	`number`	The number of I/O operations per second (IOPS) to provision for the volume.
removalPolicy?	`RemovalPolicy`	Policy to apply when the volume is removed from the stack.
size?	`Size`	The size of the volume, in GiBs.
snapshotId?	`string`	The snapshot from which to create the volume.
throughput?	`number`	The throughput that the volume supports, in MiB/s Takes a minimum of 125 and maximum of 1000.
volumeName?	`string`	The value of the physicalName property of this resource.
volumeType?	`EbsDeviceVolumeType`	The type of the volume;

availabilityZone

Type: string

The Availability Zone in which to create the volume.

autoEnableIo?

Type: boolean (optional, default: false)

Indicates whether the volume is auto-enabled for I/O operations.

By default, Amazon EBS disables I/O to the volume from attached EC2 instances when it determines that a volume's data is potentially inconsistent. If the consistency of the volume is not a concern, and you prefer that the volume be made available immediately if it's impaired, you can configure the volume to automatically enable I/O.

enableMultiAttach?

Type: boolean (optional, default: false)

Indicates whether Amazon EBS Multi-Attach is enabled.

See Considerations and limitations for the constraints of multi-attach.

encrypted?

Type: boolean (optional, default: false)

Specifies whether the volume should be encrypted.

The effect of setting the encryption state to true depends on the volume origin (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information, see Encryption by Default in the Amazon Elastic Compute Cloud User Guide.

Encrypted Amazon EBS volumes must be attached to instances that support Amazon EBS encryption. For more information, see Supported Instance Types.

encryptionKey?

Type: IKey (optional, default: The default KMS key for the account, region, and EC2 service is used.)

The customer-managed encryption key that is used to encrypt the Volume.

The encrypted property must be true if this is provided.

Note: If using an aws-kms.IKey created from a aws-kms.Key.fromKeyArn() here, then the KMS key must have the following in its Key policy; otherwise, the Volume will fail to create.

{
  "Effect": "Allow",
  "Principal": { "AWS": "<arn for your account-user> ex: arn:aws:iam::00000000000:root" },
  "Resource": "*",
  "Action": [
    "kms:DescribeKey",
    "kms:GenerateDataKeyWithoutPlainText",
  ],
  "Condition": {
    "StringEquals": {
      "kms:ViaService": "ec2.<Region>.amazonaws.com", (eg: ec2.us-east-1.amazonaws.com)
      "kms:CallerAccount": "0000000000" (your account ID)
    }
  }
}

iops?

Type: number (optional, default: None -- Required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS if omitted.)

The number of I/O operations per second (IOPS) to provision for the volume.

The maximum ratio is 50 IOPS/GiB for PROVISIONED_IOPS_SSD, and 500 IOPS/GiB for both PROVISIONED_IOPS_SSD_IO2 and GENERAL_PURPOSE_SSD_GP3. See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-volume.html for more information.

This parameter is valid only for PROVISIONED_IOPS_SSD, PROVISIONED_IOPS_SSD_IO2 and GENERAL_PURPOSE_SSD_GP3 volumes.

removalPolicy?

Type: RemovalPolicy (optional, default: RemovalPolicy.RETAIN)

Policy to apply when the volume is removed from the stack.

size?

Type: Size (optional, default: If you're creating the volume from a snapshot and don't specify a volume size, the default is the snapshot size.)

The size of the volume, in GiBs.

You must specify either a snapshot ID or a volume size. See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-volume.html for details on the allowable size for each type of volume.

snapshotId?

Type: string (optional, default: The EBS volume is not created from a snapshot.)

The snapshot from which to create the volume.

You must specify either a snapshot ID or a volume size.

throughput?

Type: number (optional, default: 125 MiB/s. Only valid on gp3 volumes.)

The throughput that the volume supports, in MiB/s Takes a minimum of 125 and maximum of 1000.

volumeName?

Type: string (optional, default: The physical name will be allocated by CloudFormation at deployment time)

The value of the physicalName property of this resource.

volumeType?

Type: EbsDeviceVolumeType (optional, default: EbsDeviceVolumeType.GENERAL_PURPOSE_SSD)

The type of the volume;

what type of storage to use to form the EBS Volume.

Properties

Name	Type	Description
availabilityZone	`string`	The availability zone that the EBS Volume is contained within (ex: us-west-2a).
env	`ResourceEnvironment`	The environment this resource belongs to.
node	`Node`	The tree node.
stack	`Stack`	The stack in which this resource is defined.
volumeId	`string`	The EBS Volume's ID.
encryptionKey?	`IKey`	The customer-managed encryption key that is used to encrypt the Volume.

availabilityZone

Type: string

The availability zone that the EBS Volume is contained within (ex: us-west-2a).

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

node

Type: Node

The tree node.

stack

Type: Stack

The stack in which this resource is defined.

volumeId

Type: string

The EBS Volume's ID.

encryptionKey?

Type: IKey (optional)

The customer-managed encryption key that is used to encrypt the Volume.

Methods

Name	Description
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
grantAttachVolume(grantee, instances?)	Grants permission to attach this Volume to an instance.
grantAttachVolumeByResourceTag(grantee, constructs, tagKeySuffix?)	Grants permission to attach the Volume by a ResourceTag condition.
grantDetachVolume(grantee, instances?)	Grants permission to detach this Volume from an instance CAUTION: Granting an instance permission to detach from itself using this method will lead to an unresolvable circular reference between the instance role and the instance.
grantDetachVolumeByResourceTag(grantee, constructs, tagKeySuffix?)	Grants permission to detach the Volume by a ResourceTag condition.
toString()	Returns a string representation of this construct.
protected validateProps(props)
static fromVolumeAttributes(scope, id, attrs)	Import an existing EBS Volume into the Stack.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

grantAttachVolume(grantee, instances?)

public grantAttachVolume(grantee: IGrantable, instances?: IInstance[]): Grant

Parameters

grantee IGrantable
instances IInstance[]

Returns

Grant

Grants permission to attach this Volume to an instance.

CAUTION: Granting an instance permission to attach to itself using this method will lead to an unresolvable circular reference between the instance role and the instance. Use IVolume.grantAttachVolumeToSelf to grant an instance permission to attach this volume to itself.

grantAttachVolumeByResourceTag(grantee, constructs, tagKeySuffix?)

public grantAttachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant

Parameters

grantee IGrantable
constructs Construct[]
tagKeySuffix string

Returns

Grant

Grants permission to attach the Volume by a ResourceTag condition.

If you are looking to grant an Instance, AutoScalingGroup, EC2-Fleet, SpotFleet, ECS host, etc the ability to attach this volume to itself then this is the method you want to use.

This is implemented by adding a Tag with key VolumeGrantAttach-<suffix> to the given constructs and this Volume, and then conditioning the Grant such that the grantee is only given the ability to AttachVolume if both the Volume and the destination Instance have that tag applied to them.

grantDetachVolume(grantee, instances?)

public grantDetachVolume(grantee: IGrantable, instances?: IInstance[]): Grant

Parameters

grantee IGrantable
instances IInstance[]

Returns

Grant

Grants permission to detach this Volume from an instance CAUTION: Granting an instance permission to detach from itself using this method will lead to an unresolvable circular reference between the instance role and the instance.

Use IVolume.grantDetachVolumeFromSelf to grant an instance permission to detach this volume from itself.

grantDetachVolumeByResourceTag(grantee, constructs, tagKeySuffix?)

public grantDetachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant

Parameters

grantee IGrantable
constructs Construct[]
tagKeySuffix string

Returns

Grant

Grants permission to detach the Volume by a ResourceTag condition.

This is implemented via the same mechanism as IVolume.grantAttachVolumeByResourceTag, and is subject to the same conditions.

toString()

public toString(): string

Returns

string

Returns a string representation of this construct.

protected validateProps(props)

protected validateProps(props: VolumeProps): void

Parameters

props VolumeProps

static fromVolumeAttributes(scope, id, attrs)

public static fromVolumeAttributes(scope: Construct, id: string, attrs: VolumeAttributes): IVolume

Parameters

scope Construct — the scope of the import.
id string — the ID of the imported Volume in the construct tree.
attrs VolumeAttributes — the attributes of the imported Volume.

Returns

IVolume

Import an existing EBS Volume into the Stack.