Amazon Elastic Compute Cloud
CLI Reference (API Version 2014-09-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

ec2-create-volume

Description

Creates an Amazon EBS volume that can be attached to any instance in the same Availability Zone.

You can create encrypted volumes with the --encrypted option. Encrypted volumes may only be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are also automatically encrypted. There is no way to create an encrypted volume from an unencrypted snapshot or vice versa. For more information, see Amazon EBS encryption in the Amazon EC2 User Guide for Linux Instances.

Any AWS Marketplace product codes from the snapshot are propagated to the volume.

For more information, see Amazon Elastic Block Store in the Amazon EC2 User Guide for Linux Instances.

The short version of this command is ec2addvol.

Tip

If you are using the AWS CLI, see create-volume instead.

Syntax

ec2-create-volume [--size size | --snapshot snapshot_id [--size size]] --availability-zone zone [--type type [--iops iops]] [--encrypted]

Options

NameDescription

-s, --size size

The size of the volume, in GiBs.

Type: String

Valid values: 1-1024

Constraints: If the volume type is io1, the minimum size of the volume is 10 GiB.

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

Required: Conditional

Condition: Required unless you're creating the volume from a snapshot.

Example: --size 80

--snapshot snapshot_id

The snapshot from which to create the volume. Volumes that are created from encrypted snapshots are automatically encrypted. There is no way to directly create an unencrypted volume from an encrypted snapshot or vice versa.

Type: String

Default: None

Required: Conditional

Condition: Required if you are creating a volume from a snapshot.

Example: --snapshot snap-78a54011

-z, --availability-zone zone

The Availability Zone in which to create the volume. Use ec2-describe-availability-zones to list the Availability Zones that are currently available to you.

Type: String

Default: None

Required: Yes

Example: --availability-zone us-east-1a

-t, --type type

The volume type. For more information, see Amazon EBS Volume Types in the Amazon EC2 User Guide for Linux Instances.

Type: String

Valid values: gp2 for General Purpose (SSD) volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic volumes.

Default: standard

Required: No

Example: --type io1

-i, --iops iops

Only valid for Provisioned IOPS (SSD) volumes. The number of I/O operations per second (IOPS) to provision for the volume.

Type: Integer

Valid values: Range is 100 to 4,000.

Default: None

Required: Conditional

Condition: Required when the volume type is io1; not used with standard or gp2 volumes.

Example: --iops 500

--encrypted

Indicates whether the volume will be encrypted. Encrypted Amazon EBS volumes may only be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are automatically encrypted. There is no way to create an encrypted volume from an unencrypted snapshot or vice versa.

Default: No

Required: No

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. For more information, see Tell the Tools Who You Are.

Default: The value of the AWS_ACCESS_KEY environment variable. If AWS_ACCESS_KEY isn't set, you must specify this option.

Example: -O AKIAIOSFODNN7EXAMPLE

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

Default: The value of the AWS_SECRET_KEY environment variable. If AWS_SECRET_KEY isn't set, you must specify this option.

Example: -W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-T, --security-token delegation_token

The delegation token to pass along to the AWS request. This is only required when you are using temporary security credentials. For more information, see Using Temporary Security Credentials.

Default: The value of the AWS_DELEGATION_TOKEN environment variable (if set).

Example: -t AQoDYXdzEJr...<remainder of security token>

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

-H, --headers

Includes column headers in the command output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Omits tags for tagged resources.

--debug

Displays internal debugging information. This can assist us when helping you troubleshooting problems.

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-v, --verbose

Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to the Query API.

-

Reads arguments from standard input. This is useful when piping the output from one command to the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-K, --private-key ec2_private_key

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert ec2_cert

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns a table that contains the following information:

  • The VOLUME identifier

  • The ID of the volume

  • The size of the volume, in GiBs

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

  • The Availability Zone in which the volume was created

  • The volume state (creating, available, in-use, deleting, deleted, error)

  • The time stamp when volume creation was initiated

  • The Amazon EBS volume type

  • 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 have been 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 on General Purpose (SSD) baseline performance, I/O credits, and bursting, see Amazon EBS Volume Types in the Amazon EC2 User Guide for Linux Instances.

  • The encryption status of the volume (Encrypted for encrypted and Not Encrypted for unencrypted)

Amazon EC2 command line tools display errors on stderr.

Examples

Example

This example command creates a 60 GiB General Purpose (SSD) volume in the Availability Zone us-east-1b.

PROMPT> ec2-create-volume  --size 60 --region us-east-1 --availability-zone us-east-1b --type gp2
VOLUME	vol-1a2b3c4d	60		us-east-1b	creating	YYYY-MM-DDTHH:MM:SS+0000	gp2	180	Not Encrypted

Example

This example command creates an encrypted 20 GiB Magnetic volume in the Availability Zone us-east-1a.

PROMPT> ec2-create-volume  --size 20 --availability-zone us-east-1a --encrypted
VOLUME	vol-1a2b3c4d	20		us-east-1a	creating	YYYY-MM-DDTHH:MM:SS+0000	standard	Encrypted

Example

This example command creates a new Provisioned IOPS (SSD) volume with 1,000 provisioned IOPS from a snapshot in the Availability Zone us-east-1a.

PROMPT> ec2-create-volume --snapshot snap-5178cf30 --type io1 --iops 1000 --availability-zone us-east-1a
VOLUME	vol-1a2b3c4d	500	snap-5178cf30	us-east-1a	creating	YYYY-MM-DDTHH:MM:SS+0000	io1	1000	Not Encrypted