Amazon Elastic Compute Cloud
CLI Reference (API Version 2011-12-15)
AWS Documentation » Amazon EC2 » Command Line Reference » API Tools Reference » ec2-describe-reserved-instances
Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

ec2-describe-reserved-instances

Description

Describes Reserved Instances that you purchased.

Starting with the 2011-11-01 API version, AWS expanded its offering for Amazon EC2 Reserved Instances to address a range of projected instance use. There are three types of Reserved Instances based on customer utilization levels: Heavy Utilization, Medium Utilization, and Light Utilization. The Medium Utilization offering type is equivalent to the Reserved Instance offering available before API version 2011-11-01. If you are using tools that predate the 2011-11-01 API version, you only have access to the Medium Utilization Reserved Instance offering type.

For more information about Reserved Instances, see Reserved Instances in the Amazon Elastic Compute Cloud User Guide.

You can filter the results to return information about Reserved Instances that matches criteria you specify. For example, you could get information about Reserved Instances in a particular Availability Zone. Or you can specify multiple values for a filter. A Reserved Instance must match at least one of the specified values for it to be included in the results.

You can specify multiple filters as well. For example, you could specify that your Reserved Instance must be in a particular Availability Zone and must be tagged with a particular value. The result includes information for a particular instance only if it matches all of your filters. If there's no match, no special message is returned; the response is simply empty.

You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.

The following table shows the available filters.

Filter Name Description

availability-zone

Availability Zone where the Reserved Instance can be used.

Type: String

duration

Duration of the Reserved Instance (one year or three years), in seconds.

Type: xs:long

Valid Values: 31536000 | 94608000

fixed-price

Purchase price of the Reserved Instance (e.g., 9800.0)

Type: xs:double

instance-type

Instance type on which the Reserved Instance can be used.

Type: String

product-description

Reserved Instance description.

Type: String

Valid Values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC)

reserved-instances-id

Reserved Instance's ID.

Type: String

start

Time the Reserved Instance purchase request was placed, e.g., 2010-08-07T11:54:42.000Z.

Type: xsd:dateTime

state

State of the Reserved Instance.

Type: String

Valid Values: pending-payment | active | payment-failed | retired

tag-key

Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table.

For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide.

Type: String

tag-value

Value of a tag assigned to the resource. This filter is independent of the tag-key filter.

Type: String

tag:key

Filters the results based on a specific tag/value combination.

Example: To list just the resources assigned tag Purpose=X, then specify:

--filter tag:Purpose=X

Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify:

--filter tag:Purpose=X --filter tag:Purpose=Y

usage-price

Usage price of the Reserved Instance, per hour (e.g., 0.84)

Type: xs:double

The short version of this command is ec2dri.

Syntax

ec2-describe-reserved-instances [reservation_id ...] [[--filter name=value] ...]

Options

NameDescriptionRequired

reservation_id

IDs of the Reserved Instance to describe.

Type: String

Default: Describes all your Reserved Instances, or only those otherwise specified.

Example: 4b2293b4-5813-4cc8-9ce3-1957fc1dcfc8

No

-F, --filter name=value

A filter for limiting the results. See the preceding table for a list of allowed filter names and values. If you're using the command line tools on a Windows system, you might need to use quotation marks (i.e., "name=value").

Type: String

Default: Describes all Reserved Instances you own, or only those otherwise specified.

Example: --filter "tag-key=Production"

No

Common Options

OptionDescription

--region REGION

Overrides the Region specified in the EC2_URL environment variable and the URL specified by the -U option.

Default: The EC2_URL environment variable, or us-east-1 if the environment variable is not set.

Example: --region eu-west-1

-U, --url URL

URL is the uniform resource locator of the Amazon EC2 web service entry point.

Default: The EC2_URL environment variable, or https://ec2.amazonaws.com if the environment variable is not set.

Example: -U https://ec2.amazonaws.com

-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-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.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-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

--connection-timeout TIMEOUT

Specifies a connection timeout (in seconds).

Example: --connection-timeout 30

--request-timeout TIMEOUT

Specifies a request timeout (in seconds).

Example: --request-timeout 45

-v, --verbose

Displays verbose output by showing the SOAP request and response on the command line. This is particularly useful if you are building tools to talk directly to our SOAP API.

-H, --headers

Displays column headers in the output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Do not display tags for tagged resources.

--debug

Prints internal debugging information. This is useful to assist us when troubleshooting problems.

-?, --help, -h

Displays Help.

-

If - is specified as an argument to one of the parameters, a list of arguments is read from standard input. This is useful for piping the output of one command into the input of another.

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

Output

The command returns a table that contains the following information:

  • RESERVEDINSTANCES identifier

  • ID of the Reserved Instance

  • The Availability Zone in which the Reserved Instance can be used

  • The instance type

  • The Reserved Instance description (Linux/UNIX, Windows, Linux/UNIX (Amazon VPC), or Windows (Amazon VPC))

  • The duration of the Reserved Instance

  • The usage price of the Reserved Instance, per hour

  • The purchase price of the Reserved Instance

  • The number of Reserved Instances purchased

  • The state of the Reserved Instance purchase (payment-pending, active, payment-failed)

  • Any tags assigned to the Reserved Instance

  • The tenancy of the reserved instance purchased. An instance with a tenancy of dedicated runs on single-tenant hardware.

  • The instance offering type

  • The currency of the Reserved Instance purchased. It's specified using ISO 4217 standard code (e.g., USD, JPY).

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example describes Reserved Instances owned by your account.

PROMPT> ec2-describe-reserved-instances
RESERVEDINSTANCES    1ba8e2e3-2538-4a35-b749-1f4442d50744    us-east-1a    m1.small    Linux/UNIX    3y     0.03    350.0    1    2009-03-13T16:01:39+0000    payment-pending
RESERVEDINSTANCES    af9f760e-c1c1-449b-8128-1342d3a6927d    us-east-1d    m1.xlarge    Linux/UNIX    1y     0.24    1820.0    1    2009-03-13T16:01:39+0000    active

Example Request

This example filters the results to display only one-year, m1.small Linux/UNIX Reserved Instances. If you want Linux/UNIX Reserved Instances specifically for use with Amazon VPC, set the product descripton to Linux/UNIX (Amazon VPC).

PROMPT> ec2-describe-reserved-instances --filter "duration=31536000" --filter "instance-type=m1.small" --filter "product-description=Linux/UNIX"
Document Conventions
Terms of Use		Did this page help you?  Yes  No   Tell us about it...