Amazon Elastic Compute Cloud
API Reference (API Version 2016-11-15)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

CreateVolume

Creates an EBS volume that can be attached to an instance in the same Availability Zone. The volume is created in the regional endpoint that you send the HTTP request to. For more information see Regions and Endpoints.

You can create a new empty volume or restore a volume from an EBS snapshot. Any AWS 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 Elastic Compute Cloud User Guide.

You can tag your volumes during creation. For more information, see Tagging Your Amazon EC2 Resources in the Amazon Elastic Compute Cloud User Guide.

For more information, see Creating an Amazon EBS Volume in the Amazon Elastic Compute Cloud User Guide.

Request Parameters

The following parameters are for this specific action. For more information about required and optional parameters that are common to all actions, see Common Query Parameters.

AvailabilityZone

The Availability Zone in which to create the volume.

Type: String

Required: Yes

DryRun

Checks 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.

Type: Boolean

Required: No

Encrypted

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.

Type: Boolean

Required: No

Iops

The number of I/O operations per second (IOPS) to provision for the volume, with a maximum ratio of 50 IOPS/GiB. Range is 100 to 64,000 IOPS for volumes in most Regions. Maximum IOPS of 64,000 is guaranteed only on Nitro-based instances. Other instance families guarantee performance up to 32,000 IOPS. For more information, see Amazon EBS Volume Types in the Amazon Elastic Compute Cloud User Guide.

This parameter is valid only for Provisioned IOPS SSD (io1) volumes.

Type: Integer

Required: No

KmsKeyId

The identifier of the AWS Key Management Service (AWS KMS) customer master key (CMK) to use for Amazon EBS encryption. If this parameter is not specified, your AWS managed CMK for EBS is used. If KmsKeyId is specified, the encrypted state must be true.

You can specify the CMK using any of the following:

  • Key ID. For example, key/1234abcd-12ab-34cd-56ef-1234567890ab.

  • Key alias. For example, alias/ExampleAlias.

  • Key ARN. For example, arn:aws:kms:us-east-1:012345678910:key/abcd1234-a123-456a-a12b-a123b4cd56ef.

  • Alias ARN. For example, arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias.

AWS authenticates the CMK asynchronously. Therefore, if you specify an ID, alias, or ARN that is not valid, the action can appear to complete, but eventually fails.

Type: String

Required: No

Size

The size of the volume, in GiBs.

Constraints: 1-16,384 for gp2, 4-16,384 for io1, 500-16,384 for st1, 500-16,384 for sc1, and 1-1,024 for standard. If you specify a snapshot, the volume size must be equal to or larger than the snapshot size.

Default: If you're creating the volume from a snapshot and don't specify a volume size, the default is the snapshot size.

Note

At least one of Size or SnapshotId is required.

Type: Integer

Required: No

SnapshotId

The snapshot from which to create the volume.

Note

At least one of Size or SnapshotId are required.

Type: String

Required: No

TagSpecification.N

The tags to apply to the volume during creation.

Type: Array of TagSpecification objects

Required: No

VolumeType

The volume type. This can be gp2 for General Purpose SSD, io1 for Provisioned IOPS SSD, st1 for Throughput Optimized HDD, sc1 for Cold HDD, or standard for Magnetic volumes.

Default: gp2

Type: String

Valid Values: standard | io1 | gp2 | sc1 | st1

Required: No

Response Elements

The following elements are returned by the service.

attachmentSet

Information about the volume attachments.

Type: Array of VolumeAttachment objects

availabilityZone

The Availability Zone for the volume.

Type: String

createTime

The time stamp when volume creation was initiated.

Type: Timestamp

encrypted

Indicates whether the volume is encrypted.

Type: Boolean

iops

The number of I/O operations per second (IOPS) that the volume supports. For Provisioned IOPS SSD volumes, this represents the number of IOPS that are provisioned for the volume. For General Purpose SSD volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting. For more information, see Amazon EBS Volume Types in the Amazon Elastic Compute Cloud User Guide.

Constraints: Range is 100-16,000 IOPS for gp2 volumes and 100 to 64,000IOPS for io1 volumes, in most Regions. The maximum IOPS for io1 of 64,000 is guaranteed only on Nitro-based instances. Other instance families guarantee performance up to 32,000 IOPS.

Condition: This parameter is required for requests to create io1 volumes; it is not used in requests to create gp2, st1, sc1, or standard volumes.

Type: Integer

kmsKeyId

The Amazon Resource Name (ARN) of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to protect the volume encryption key for the volume.

Type: String

requestId

The ID of the request.

Type: String

size

The size of the volume, in GiBs.

Type: Integer

snapshotId

The snapshot from which the volume was created, if applicable.

Type: String

status

The volume state.

Type: String

Valid Values: creating | available | in-use | deleting | deleted | error

tagSet

Any tags assigned to the volume.

Type: Array of Tag objects

volumeId

The ID of the volume.

Type: String

volumeType

The volume type. This can be gp2 for General Purpose SSD, io1 for Provisioned IOPS SSD, st1 for Throughput Optimized HDD, sc1 for Cold HDD, or standard for Magnetic volumes.

Type: String

Valid Values: standard | io1 | gp2 | sc1 | st1

Errors

For information about the errors that are common to all actions, see Common Client Errors.

Examples

Example 1

This example request creates an 80 GiB encrypted volume in the Availability Zone us-east-1a.

Sample Request

https://ec2.amazonaws.com/?Action=CreateVolume &Size=80 &AvailabilityZone=us-east-1a &Encrypted=1 &AUTHPARAMS

Sample Response

<CreateVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <volumeId>vol-1234567890abcdef0</volumeId> <size>80</size> <snapshotId/> <availabilityZone>us-east-1a</availabilityZone> <status>creating</status> <createTime>YYYY-MM-DDTHH:MM:SS.000Z</createTime> <volumeType>standard</volumeType> <encrypted>true</encrypted> </CreateVolumeResponse>

Example 2

This example request creates a volume and applies a tag with a key of stack and a value of production.

Sample Request

https://ec2.amazonaws.com/?Action=CreateVolume &Size=80 &AvailabilityZone=us-east-1a &TagSpecification.1.ResourceType=volume &TagSpecification.1.Tag.1.Key=stack &TagSpecification.1.Tag.1.Value=production &AUTHPARAMS

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: