Skip to main content

volumes

Creates, updates, deletes, gets or lists a volumes resource.

Overview​

Namevolumes
TypeResource
Idaws.ec2.volumes

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
attachmentsstringThis parameter is not returned by CreateVolume. Information about the volume attachments.
availability_zonestringThe Availability Zone for the volume.
availability_zone_idstringThe ID of the Availability Zone for the volume.
create_timestringThe time stamp when volume creation was initiated.
encryptedbooleanIndicates whether the volume is encrypted.
fast_restoredbooleanThis parameter is not returned by CreateVolume. Indicates whether the volume was created using fast snapshot restore.
iopsintegerThe number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
kms_key_idstringThe Amazon Resource Name (ARN) of the KMS key that was used to protect the volume encryption key for the volume.
multi_attach_enabledbooleanIndicates whether Amazon EBS Multi-Attach is enabled.
operatorstringThe service provider that manages the volume.
outpost_arnstringThe Amazon Resource Name (ARN) of the Outpost.
sizeintegerThe size of the volume, in GiBs.
snapshot_idstringThe snapshot from which the volume was created, if applicable.
source_volume_idstringThe ID of the source volume from which the volume copy was created. Only for volume copies.
sse_typestringThis parameter is not returned by CreateVolume. Reserved for future use.
statestringThe volume state.
tagsstringAny tags assigned to the volume.
throughputintegerThe throughput that the volume supports, in MiB/s.
volume_idstringThe ID of the volume.
volume_initialization_rateintegerThe Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate) specified for the volume during creation, in MiB/s. If no volume initialization rate was specified, the value is null.
volume_typestringThe volume type.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_volumesselectregionVolumeId, IncludeManagedResources, DryRun, Filter, NextToken, MaxResultsDescribes the specified EBS volumes or all of your EBS volumes. If you are describing a long list of volumes, we recommend that you paginate the output to make the list more manageable. For more information, see Pagination. For more information about EBS volumes, see Amazon EBS volumes in the Amazon EBS User Guide. We strongly recommend using only paginated requests. Unpaginated requests are susceptible to throttling and timeouts. The order of the elements in the response, including those within nested structures, might vary. Applications should not assume the elements appear in a particular order.
create_volumeinsertregionAvailabilityZone, AvailabilityZoneId, Encrypted, Iops, KmsKeyId, OutpostArn, Size, SnapshotId, VolumeType, TagSpecification, MultiAttachEnabled, Throughput, ClientToken, VolumeInitializationRate, Operator, DryRunCreates an EBS volume that can be attached to an instance in the same Availability Zone. You can create a new empty volume or restore a volume from an EBS snapshot. Any Amazon Web Services Marketplace product codes from the snapshot are propagated to the volume. You can create encrypted volumes. Encrypted volumes must be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are also automatically encrypted. For more information, see Amazon EBS encryption in the Amazon EBS User Guide. You can tag your volumes during creation. For more information, see Tag your Amazon EC2 resources in the Amazon EC2 User Guide. For more information, see Create an Amazon EBS volume in the Amazon EBS User Guide.
attach_volumeupdateInstanceId, VolumeId, regionDevice, EbsCardIndex, DryRunAttaches an Amazon EBS volume to a running or stopped instance, and exposes it to the instance with the specified device name. The maximum number of Amazon EBS volumes that you can attach to an instance depends on the instance type. If you exceed the volume attachment limit for an instance type, the attachment request fails with the AttachmentLimitExceeded error. For more information, see Instance volume limits. After you attach an EBS volume, you must make it available for use. For more information, see Make an EBS volume available for use. If a volume has an Amazon Web Services Marketplace product code: The volume can be attached only to a stopped instance. Amazon Web Services Marketplace product codes are copied from the volume to the instance. You must be subscribed to the product. The instance type and operating system of the instance must support the product. For example, you can't detach a volume from a Windows instance and attach it to a Linux instance. For more information, see Attach an Amazon EBS volume to an instance in the Amazon EBS User Guide.
detach_volumeupdateVolumeId, regionDevice, Force, InstanceId, DryRunDetaches an EBS volume from an instance. Make sure to unmount any file systems on the device within your operating system before detaching the volume. Failure to do so can result in the volume becoming stuck in the busy state while detaching. If this happens, detachment can be delayed indefinitely until you unmount the volume, force detachment, reboot the instance, or all three. If an EBS volume is the root device of an instance, it can't be detached while the instance is running. To detach the root volume, stop the instance first. When a volume with an Amazon Web Services Marketplace product code is detached from an instance, the product code is no longer associated with the instance. You can't detach or force detach volumes that are attached to Amazon Web Services-managed resources. Attempting to do this results in the UnsupportedOperationException exception. For more information, see Detach an Amazon EBS volume in the Amazon EBS User Guide.
delete_volumedeleteVolumeId, regionDryRunDeletes the specified EBS volume. The volume must be in the available state (not attached to an instance). The volume can remain in the deleting state for several minutes. For more information, see Delete an Amazon EBS volume in the Amazon EBS User Guide.
copy_volumesexecSourceVolumeId, regionIops, Size, VolumeType, DryRun, TagSpecification, MultiAttachEnabled, Throughput, ClientTokenCreates a crash-consistent, point-in-time copy of an existing Amazon EBS volume within the same Availability Zone. The volume copy can be attached to an Amazon EC2 instance once it reaches the available state. For more information, see Copy an Amazon EBS volume.
enable_volume_ioexecVolumeId, regionDryRunEnables I/O operations for a volume that had I/O operations disabled because the data on the volume was potentially inconsistent.
modify_volumeexecVolumeId, regionDryRun, Size, VolumeType, Iops, Throughput, MultiAttachEnabledYou can modify several parameters of an existing EBS volume, including volume size, volume type, and IOPS capacity. If your EBS volume is attached to a current-generation EC2 instance type, you might be able to apply these changes without stopping the instance or detaching the volume from it. For more information about modifying EBS volumes, see Amazon EBS Elastic Volumes in the Amazon EBS User Guide. When you complete a resize operation on your volume, you need to extend the volume's file-system size to take advantage of the new storage capacity. For more information, see Extend the file system. For more information, see Monitor the progress of volume modifications in the Amazon EBS User Guide. With previous-generation instance types, resizing an EBS volume might require detaching and reattaching the volume or stopping and restarting the instance. After you initiate a volume modification, you must wait for that modification to reach the completed state before you can initiate another modification for the same volume. You can modify a volume up to four times within a rolling 24-hour period, as long as the volume is in the in-use or available state, and all previous modifications for that volume are completed. If you exceed this limit, you get an error message that indicates when you can perform your next modification.
restore_volume_from_recycle_binexecVolumeId, regionDryRunRestores a volume from the Recycle Bin. For more information, see Restore volumes from the Recycle Bin in the Amazon EBS User Guide.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
InstanceIdstringThe ID of the instance.
SourceVolumeIdstringThe ID of the source EBS volume to copy.
VolumeIdstringThe ID of the volume to restore.
regionstringAWS region (default: us-east-1)
AvailabilityZonestringThe ID of the Availability Zone in which to create the volume. For example, us-east-1a. Either AvailabilityZone or AvailabilityZoneId must be specified, but not both.
AvailabilityZoneIdstringThe ID of the Availability Zone in which to create the volume. For example, use1-az1. Either AvailabilityZone or AvailabilityZoneId must be specified, but not both.
ClientTokenstringUnique, case-sensitive identifier that you provide to ensure the idempotency of the request. For more information, see Ensure Idempotency.
DevicestringThe device name.
DryRunbooleanChecks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.
EbsCardIndexintegerThe index of the EBS card. Some instance types support multiple EBS cards. The default EBS card index is 0.
EncryptedbooleanIndicates 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 EBS User Guide. Encrypted Amazon EBS volumes must be attached to instances that support Amazon EBS encryption. For more information, see Supported instance types.
FilterarrayThe filters. attachment.attach-time - The time stamp when the attachment initiated. attachment.delete-on-termination - Whether the volume is deleted on instance termination. attachment.device - The device name specified in the block device mapping (for example, /dev/sda1). attachment.instance-id - The ID of the instance the volume is attached to. attachment.status - The attachment state (attaching | attached | detaching). availability-zone - The Availability Zone in which the volume was created. availability-zone-id - The ID of the Availability Zone in which the volume was created. create-time - The time stamp when the volume was created. encrypted - Indicates whether the volume is encrypted (true | false) fast-restored - Indicates whether the volume was created from a snapshot that is enabled for fast snapshot restore (true | false). multi-attach-enabled - Indicates whether the volume is enabled for Multi-Attach (true | false) operator.managed - A Boolean that indicates whether this is a managed volume. operator.principal - The principal that manages the volume. Only valid for managed volumes, where managed is true. size - The size of the volume, in GiB. snapshot-id - The snapshot from which the volume was created. status - The state of the volume (creating | available | in-use | deleting | deleted | error). tag:<key> - The key/value combination of a tag assigned to the resource. Use the tag key in the filter name and the tag value as the filter value. For example, to find all resources that have a tag with the key Owner and the value TeamA, specify tag:Owner for the filter name and TeamA for the filter value. tag-key - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value. volume-id - The volume ID. volume-type - The Amazon EBS volume type (gp2 | gp3 | io1 | io2 | st1 | sc1| standard)
ForcebooleanForces detachment if the previous detachment attempt did not occur cleanly (for example, logging into an instance, unmounting the volume, and detaching normally). This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance won't have an opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures.
IncludeManagedResourcesbooleanIndicates whether to include managed resources in the output. If this parameter is set to true, the output includes resources that are managed by Amazon Web Services services, even if managed resource visibility is set to hidden.
InstanceIdstringThe ID of the instance. If you are detaching a Multi-Attach enabled volume, you must specify an instance ID.
IopsintegerThe target IOPS rate of the volume. This parameter is valid only for gp3, io1, and io2 volumes. The following are the supported values for each volume type: gp3: 3,000 - 80,000 IOPS io1: 100 - 64,000 IOPS io2: 100 - 256,000 IOPS Instances built on the Nitro System can support up to 256,000 IOPS. Other instances can support up to 32,000 IOPS. Default: The existing value is retained if you keep the same volume type. If you change the volume type to io1, io2, or gp3, the default is 3,000.
KmsKeyIdstringThe identifier of the KMS key to use for Amazon EBS encryption. If this parameter is not specified, your KMS key for Amazon EBS is used. If KmsKeyId is specified, the encrypted state must be true. You can specify the KMS key using any of the following: Key ID. For example, 1234abcd-12ab-34cd-56ef-1234567890ab. Key alias. For example, alias/ExampleAlias. Key ARN. For example, arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab. Alias ARN. For example, arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias. Amazon Web Services authenticates the KMS key asynchronously. Therefore, if you specify an ID, alias, or ARN that is not valid, the action can appear to complete, but eventually fails.
MaxResultsintegerThe maximum number of items to return for this request. To get the next page of items, make another request with the token returned in the output. For more information, see Pagination.
MultiAttachEnabledbooleanSpecifies whether to enable Amazon EBS Multi-Attach. If you enable Multi-Attach, you can attach the volume to up to 16 Nitro-based instances in the same Availability Zone. This parameter is supported with io1 and io2 volumes only. For more information, see Amazon EBS Multi-Attach in the Amazon EBS User Guide.
NextTokenstringThe token returned from a previous paginated request. Pagination continues from the end of the items returned by the previous request.
OperatorobjectReserved for internal use.
OutpostArnstringThe Amazon Resource Name (ARN) of the Outpost on which to create the volume. If you intend to use a volume with an instance running on an outpost, then you must create the volume on the same outpost as the instance. You can't use a volume created in an Amazon Web Services Region with an instance on an Amazon Web Services outpost, or the other way around.
SizeintegerThe target size of the volume, in GiB. The target volume size must be greater than or equal to the existing size of the volume. The following are the supported volumes sizes for each volume type: gp2: 1 - 16,384 GiB gp3: 1 - 65,536 GiB io1: 4 - 16,384 GiB io2: 4 - 65,536 GiB st1 and sc1: 125 - 16,384 GiB standard: 1 - 1024 GiB Default: The existing size is retained.
SnapshotIdstringThe snapshot from which to create the volume. You must specify either a snapshot ID or a volume size.
TagSpecificationarrayThe tags to apply to the volume copy during creation.
ThroughputintegerThe target throughput of the volume, in MiB/s. This parameter is valid only for gp3 volumes. The maximum value is 2,000. Default: The existing value is retained if the source and target volume type is gp3. Otherwise, the default value is 125. Valid Range: Minimum value of 125. Maximum value of 2,000.
VolumeIdarrayThe volume IDs. If not specified, then all volumes are included in the response.
VolumeInitializationRateintegerSpecifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation. This parameter is supported only for volumes created from snapshots. Omit this parameter if: You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation. If you specify a snapshot that is enabled for fast snapshot restore and a volume initialization rate, the volume will be initialized at the specified rate instead of fast snapshot restore. You want to create a volume that is initialized at the default rate. For more information, see Initialize Amazon EBS volumes in the Amazon EC2 User Guide. Valid range: 100 - 300 MiB/s
VolumeTypestringThe target EBS volume type of the volume. For more information, see Amazon EBS volume types in the Amazon EBS User Guide. Default: The existing type is retained.

SELECT examples​

Describes the specified EBS volumes or all of your EBS volumes. If you are describing a long list of volumes, we recommend that you paginate the output to make the list more manageable. For more information, see Pagination. For more information about EBS volumes, see Amazon EBS volumes in the Amazon EBS User Guide. We strongly recommend using only paginated requests. Unpaginated requests are susceptible to throttling and timeouts. The order of the elements in the response, including those within nested structures, might vary. Applications should not assume the elements appear in a particular order.

SELECT
attachments,
availability_zone,
availability_zone_id,
create_time,
encrypted,
fast_restored,
iops,
kms_key_id,
multi_attach_enabled,
operator,
outpost_arn,
size,
snapshot_id,
source_volume_id,
sse_type,
state,
tags,
throughput,
volume_id,
volume_initialization_rate,
volume_type
FROM aws.ec2.volumes
WHERE region = '{{ region }}' -- required
AND VolumeId = '{{ VolumeId }}'
AND IncludeManagedResources = '{{ IncludeManagedResources }}'
AND DryRun = '{{ DryRun }}'
AND Filter = '{{ Filter }}'
AND NextToken = '{{ NextToken }}'
AND MaxResults = '{{ MaxResults }}'
;

INSERT examples​

Creates an EBS volume that can be attached to an instance in the same Availability Zone. You can create a new empty volume or restore a volume from an EBS snapshot. Any Amazon Web Services Marketplace product codes from the snapshot are propagated to the volume. You can create encrypted volumes. Encrypted volumes must be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are also automatically encrypted. For more information, see Amazon EBS encryption in the Amazon EBS User Guide. You can tag your volumes during creation. For more information, see Tag your Amazon EC2 resources in the Amazon EC2 User Guide. For more information, see Create an Amazon EBS volume in the Amazon EBS User Guide.

INSERT INTO aws.ec2.volumes (
region,
AvailabilityZone,
AvailabilityZoneId,
Encrypted,
Iops,
KmsKeyId,
OutpostArn,
Size,
SnapshotId,
VolumeType,
TagSpecification,
MultiAttachEnabled,
Throughput,
ClientToken,
VolumeInitializationRate,
Operator,
DryRun
)
SELECT 
'{{ region }}',
'{{ AvailabilityZone }}',
'{{ AvailabilityZoneId }}',
'{{ Encrypted }}',
'{{ Iops }}',
'{{ KmsKeyId }}',
'{{ OutpostArn }}',
'{{ Size }}',
'{{ SnapshotId }}',
'{{ VolumeType }}',
'{{ TagSpecification }}',
'{{ MultiAttachEnabled }}',
'{{ Throughput }}',
'{{ ClientToken }}',
'{{ VolumeInitializationRate }}',
'{{ Operator }}',
'{{ DryRun }}'
RETURNING
attachments,
availability_zone,
availability_zone_id,
create_time,
encrypted,
fast_restored,
iops,
kms_key_id,
multi_attach_enabled,
operator,
outpost_arn,
size,
snapshot_id,
source_volume_id,
sse_type,
state,
tags,
throughput,
volume_id,
volume_initialization_rate,
volume_type
;

UPDATE examples​

Attaches an Amazon EBS volume to a running or stopped instance, and exposes it to the instance with the specified device name. The maximum number of Amazon EBS volumes that you can attach to an instance depends on the instance type. If you exceed the volume attachment limit for an instance type, the attachment request fails with the AttachmentLimitExceeded error. For more information, see Instance volume limits. After you attach an EBS volume, you must make it available for use. For more information, see Make an EBS volume available for use. If a volume has an Amazon Web Services Marketplace product code: The volume can be attached only to a stopped instance. Amazon Web Services Marketplace product codes are copied from the volume to the instance. You must be subscribed to the product. The instance type and operating system of the instance must support the product. For example, you can't detach a volume from a Windows instance and attach it to a Linux instance. For more information, see Attach an Amazon EBS volume to an instance in the Amazon EBS User Guide.

UPDATE aws.ec2.volumes
SET 
-- No updatable properties
WHERE 
InstanceId = '{{ InstanceId }}' --required
AND VolumeId = '{{ VolumeId }}' --required
AND region = '{{ region }}' --required
AND Device = '{{ Device}}'
AND EbsCardIndex = '{{ EbsCardIndex}}'
AND DryRun = {{ DryRun}}
RETURNING
associated_resource,
attach_time,
delete_on_termination,
device,
ebs_card_index,
instance_id,
instance_owning_service,
state,
volume_id;

DELETE examples​

Deletes the specified EBS volume. The volume must be in the available state (not attached to an instance). The volume can remain in the deleting state for several minutes. For more information, see Delete an Amazon EBS volume in the Amazon EBS User Guide.

DELETE FROM aws.ec2.volumes
WHERE VolumeId = '{{ VolumeId }}' --required
AND region = '{{ region }}' --required
AND DryRun = '{{ DryRun }}'
;

Lifecycle Methods​

Creates a crash-consistent, point-in-time copy of an existing Amazon EBS volume within the same Availability Zone. The volume copy can be attached to an Amazon EC2 instance once it reaches the available state. For more information, see Copy an Amazon EBS volume.

EXEC aws.ec2.volumes.copy_volumes 
@SourceVolumeId='{{ SourceVolumeId }}' --required, 
@region='{{ region }}' --required, 
@Iops='{{ Iops }}', 
@Size='{{ Size }}', 
@VolumeType='{{ VolumeType }}', 
@DryRun={{ DryRun }}, 
@TagSpecification='{{ TagSpecification }}', 
@MultiAttachEnabled={{ MultiAttachEnabled }}, 
@Throughput='{{ Throughput }}', 
@ClientToken='{{ ClientToken }}'
;
Last updated on