ec2-describe-reserved-instances-offerings

Description

Describes Reserved Instance offerings that are available for purchase. With Amazon EC2 Reserved Instances, you purchase the right to launch Amazon EC2 instances for a period of time. During that time period you will not receive insufficient capacity errors, and you will pay a lower usage rate than the rate charged for On-Demand instances for the actual time used.

Starting with the 2011-11-01 API version, AWS expanded its offering of Amazon EC2 Reserved Instances to address a range of projected instance usage. There are three types of Reserved Instances based on customer utilization levels: Heavy Utilization, Medium Utilization, and Light Utilization. You determine the type of the Reserved Instance offerings by including the optional offeringType parameter when calling ec2-describe-reserved-instances-offerings. 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, ec2-describe-reserved-instances-offerings will only list information about the Medium Utilization Reserved Instance offering type.

For information about Reserved Instances Pricing Tiers, go to Understanding Reserved Instance Pricing Tiers in the Amazon Elastic Compute Cloud User Guide. For more information about Reserved Instances, go to Reserved Instances also in the Amazon Elastic Compute Cloud User Guide.

Starting with the 2012-08-15 API version, AWS offers the Reserved Instance Marketplace, where you can buy and sell Reserved Instances. The Reserved Instance Marketplace makes it easy to buy and sell Amazon EC2 Reserved Instances by matching sellers who own capacity that they no longer need with buyers who are looking to purchase additional capacity. Reserved Instances bought and sold through the Reserved Instance Marketplace work like any other Reserved Instances.

By default, with the 2012-08-15 API version, ec2-describe-reserved-instances-offerings returns information about Amazon EC2 Reserved Instances available directly from AWS, plus instance offerings available from third-party sellers, on the Reserved Instance Marketplace. If you are using tools that predate the 2012-08-15 API version, ec2-describe-reserved-instances-offerings will only list information about Amazon EC2 Reserved Instances available directly from AWS.

For more information about the Reserved Instance Marketplace, go to Reserved Instance Marketplace in the Amazon Elastic Compute Cloud User Guide.

The short version of this command is ec2drio.

Syntax

ec2-describe-reserved-instances-offerings [offering_id ...] [--type instance_type ...] [--offering-type offering] [--availability-zone zone ...] [--description description ...] [[--filter "name=value"] ...] [--tenancy tenancy] [--exclude-marketplace] [--min-duration MIN-DURATION] [--max-duration MAX-DURATION]

Options

Name	Description
`offering_id`	The ID of a Reserved Instance offering. Type: String Default: None Required: No Example: 438012d3-4967-4ba9-aa40-cbb1dexample
`-t, --type` `instance_type`	The instance type on which the Reserved Instance can be used. Type: String Default: None Required: No Example: -t m1.small
`--offering-type` `offering-type`	The Reserved Instance offering type. Type: String Default: None Valid Values: `"Heavy Utilization"` \| `"Medium Utilization"` \| `"Light Utilization"` Required: No Example: --offering-type "Medium Utilization"
`-z, --availability-zone` `zone`	The Availability Zone in which the Reserved Instance can be used. Type: String Default: None Required: No Example: -z us-east-1a
`-d, --description` `description`	The Reserved Instance description. Instances that include `(Amazon VPC)` in the description are for use with Amazon VPC. Type: String Default: None Valid Values: `Linux/UNIX` \| `Linux/UNIX (Amazon VPC)` \| `SUSE Linux` \| `SUSE Linux (Amazon VPC)` \| `Red Hat Enterprise Linux` \| `Red Hat Enterprise Linux (Amazon VPC)` \| `Windows` \| `Windows (Amazon VPC)` \| `Windows with SQL Server Standard` \| `Windows with SQL Server Standard (Amazon VPC)` \| `Windows with SQL Server Web` \| `Windows with SQL Server Web (Amazon VPC)` Required: No Example: -d Linux/UNIX
`-F, --filter FILTER` `name`=`value`	A filter for limiting the results. See the Supported Filters section for a list of supported filters. Use quotation marks if the value string has a space ("name=value example"). On a Windows system, use quotation marks even without a space in the value string ("name=value"). Type: String Default: Describes all your Reserved Instances offerings, or those you specified by ID. Required: No Example: --filter "instance-type=m1.small"
`--tenancy` `TENANCY`	Specifies the tenancy of the Reserved Instance offering. A Reserved Instance with tenancy of dedicated will run on single-tenant hardware and can only be launched within a VPC. Type: String Default: default Valid Values: default \| dedicated Required: No
`--exclude-marketplace`	Excludes the Reserved Instance Marketplace offerings in the response. Type: Boolean Default: false Valid Values: `true` \| `false` Required: No
`--min-duration` `MIN-DURATION`	Specifies that only offerings that have a duration of at least `MIN-DURATION` months should be returned. Type: String Default: None Valid Values: Required: No
`--max-duration` `MAX-DURATION`	Specifies that only offerings that have a duration of at most `MAX-DURATION` months should be returned. Type: String Default: None Required: No

Supported Filters

Our policy is to provide filters for all ec2-describe calls so that you can limit the response to your specified criteria. Therefore, you can use filters to limit the response when describing Reserved Instances offerings, even though you can use other options instead.

For example, you could use an option or a filter to get the offerings for a specific instance type. You can specify multiple options or filters (for example, limit the response to the m2.xlarge instance type, and only for Windows instances). The response includes information for an offering only if it matches all options or filters. If there's no match, no special message is returned, the response is simply empty.

You can use wildcards in a filter value. An asterisk (*) matches zero or more characters, and a question mark (?) 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 are the available filters.

availability-zone

The Availability Zone where the Reserved Instance can be used.

Type: String

duration

The duration of the Reserved Instance (for example, one year or three years), in seconds.

Type: Long

Valid values: 31536000 | 94608000

fixed-price

The purchase price of the Reserved Instance (for example, 9800.0)

Type: Double

instance-type

The Amazon EC2 instance type on which the Reserved Instance can be used.

Type: String

marketplace

Set to true to show only Reserved Instance Marketplace offerings. When this filter is not used, which is the default behavior, all offerings from AWS and Reserved Instance Marketplace are listed.

Type: Boolean

product-description

The description of the Reserved Instance.

Type: String

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

reserved-instances-offering-id

The Reserved Instances offering ID.

Type: String

usage-price

The usage price of the Reserved Instance, per hour (for example, 0.84)

Type: Double

Common Options

Option	Description
`--region` `REGION`	Overrides the region specified by the `EC2_URL` environment variable and the URL specified by the `-U` option. Default: The value of the `EC2_URL` environment variable, or `us-east-1` if `EC2_URL` isn't set. Example: `--region eu-west-1`
`-U, --url` `URL`	The uniform resource locator (URL) of the Amazon EC2 web service entry point. Default: The value of the `EC2_URL` environment variable, or https://ec2.amazonaws.com if `EC2_URL` isn't set. Example: `-U https://ec2.amazonaws.com`
`-K, --private-key` `EC2-PRIVATE-KEY`	The private key that identifies you to Amazon EC2. For more information, see Tell the Tools Who You Are. Default: The value of the `EC2_PRIVATE_KEY` environment variable. If `EC2_PRIVATE_KEY` isn't set, you must specify this option. Example: `-K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-C, --cert` `EC2-CERT`	The X.509 certificate that identifies you to Amazon EC2. Default: The value of the `EC2_CERT` environment variable. If `EC2_CERT` isn't set, you must specify this option. Example: `-C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-O, --aws-access-key` `AWS_ACCESS_KEY`	The access key ID associated with your AWS account. 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` Note For more information, see the following section, Deprecated Options.
`-W, --aws-secret-key` `AWS_SECRET_KEY`	The secret access key associated with your AWS account. 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` Note For more information, see the following section, Deprecated Options.
`-T, --security-token TOKEN` `AWS_DELEGATION_TOKEN`	The AWS delegation token. Default: The value of the environment variable (if set).
`--connection-timeout` `TIMEOUT`	The connection timeout, in seconds. Example: `--connection-timeout 30`
`--request-timeout` `TIMEOUT`	The request timeout, in seconds. Example: `--request-timeout 45`
`-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 our Query API.
`-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.
`-?, --help, -h`	Displays usage information for the command.
`-`	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 -`

Deprecated Options

For a limited time, you can still use the private key and X.509 certificate instead of your access key ID and secret access key. However, we recommend that you start using your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) now, as the private key (-K, --private-key) and X.509 certificate (-C, --cert) won't be supported after the transition period elapses. For more information, see Tell the Tools Who You Are.

Option Description

Option	Description
`-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`

-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

The command returns a table that contains the following information:

The offering information

The OFFERING identifier
The source of the offering (AWS or 3rd Party)
The offering ID
The Availability Zone in which the Reserved Instance can be used
The instance type
The duration of the Reserved Instance
The purchase price of the Reserved Instance. This may be contained in one or more subsequent PRICING_DETAIL rows
The usage price of the Reserved Instance, per hour. This may be contained in one or more subsequent RECURRING-CHARGE rows
The Reserved Instance description
The currency of the Reserved Instance. It's specified using ISO 4217 standard (for example, USD). At this time, the only supported currency is USD.
The tenancy of the Reserved Instance.
The instance offering type ("Heavy Utilization" | "Medium Utilization" | "Light Utilization")

One or more rows that contain the recurring charge information, if any

The RECURRING-CHARGE identifier
The recurring charge frequency
The recurring charge amount

One or more rows that contain the purchase price detail information, if any

The PRICING_DETAIL identifier
The number of times the purchase price must be paid
The purchase price of the Reserved Instance

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

Check to see what m1.small Reserved Instances are available in a specific region.

PROMPT> ec2-describe-reserved-instances-offerings -t m1.small -z sa-east-1b -d Linux/UNIX --headers

Amazon EC2 returns output similar to the following example:

PROMPT> ec2-describe-reserved-instances-offerings
Type	Source	ReservedInstancesOfferingId	AvailabilityZone	InstanceType	Duration	FixedPrice	UsagePrice	ProductDescription	Currency	InstanceTenancy	OfferingType
OFFERING	AWS	4b2293b4-3236-49f5-978d-a74c3example	sa-east-1b	m1.small	3y 	574.0	0.0	Linux/UNIX	USD	default	Heavy Utilization
Type	Frequency	Amount
RECURRING-CHARGE	Hourly	0.021
OFFERING	AWS	3a98bf7d-07e1-4b33-8e11-e5314example	sa-east-1b	m1.small	3y 	473.0	0.031	Linux/UNIX	USD	default	Medium Utilization
OFFERING	AWS	438012d3-5fc5-4e49-a88e-273edexample	sa-east-1b	m1.small	3y 	203.0	0.055	Linux/UNIX	USD	default	Light Utilization
OFFERING	AWS	d586503b-bb92-41fa-9065-e5b90example	sa-east-1b	m1.small	1y 	372.94	0.0	Linux/UNIX	USD	default	Heavy Utilization
Type	Frequency	Amount
RECURRING-CHARGE	Hourly	0.03
OFFERING	AWS	ceb6a579-b235-41e2-9aad-15a23example	sa-east-1b	m1.small	1y 	307.13	0.04	Linux/UNIX	USD	default	Medium Utilization
OFFERING	AWS	649fd0c8-4ffb-443d-824d-eae3fexample	sa-east-1b	m1.small	1y 	131.63	0.07	Linux/UNIX	USD	default	Light Utilization
OFFERING	3rd Party	b6121943-9faf-4350-8047-bc6d4example	sa-east-1b	m1.small	10m 	-	0.032	Linux/UNIX	USD	default	Medium Utilization
Type	Count	Price
PRICING_DETAIL	2	$1.2
OFFERING	3rd Party	08edcff2-8143-4c1d-b23c-e4c11example	sa-east-1b	m1.small	5m 	-	0.032	Linux/UNIX	USD	default	Medium Utilization
Type	Count	Price
PRICING_DETAIL	19	$1.2
PRICING_DETAIL	4	$1.23

The preceding output shows a part of the overall offerings that are available.

Tip

You can filter this list to return only certain types of Reserved Instances offerings of interest to you.

Example Request

This example filters the response to include only one-year, m1.small or m1.large Linux/UNIX Reserved Instances. If you want Linux/UNIX Reserved Instances specifically for use with a VPC, set the product description to Linux/UNIX (Amazon VPC).

PROMPT> ec2-describe-reserved-instances-offerings --filter "duration=31536000" --filter "instance-type=m1.small" --filter "instance-type=m1.large" --filter "product-description=Linux/UNIX" -H
Type	ReservedInstancesOfferingId	AvailabilityZone	InstanceType	Duration	FixedPrice	UsagePrice	ProductDescription	Currency	InstanceTenancy	OfferingType
OFFERING	649fd0c8-7d25-4e81-959e-0e1bcexample	us-east-1c	m1.large	1y 	910.0	0.12	Linux/UNIX	USD	default	Medium Utilization
OFFERING	438012d3-278f-4ad6-9cb9-e2318example	us-east-1b	m1.large	1y 	910.0	0.12	Linux/UNIX	USD	default	Medium Utilization
OFFERING	4b2293b4-20f5-4b3d-9969-46341example	us-east-1d	m1.large	1y 	910.0	0.12	Linux/UNIX	USD	default	Medium Utilization
OFFERING	3a98bf7d-abc6-47a0-870e-e2459example	us-east-1a	m1.large	1y 	910.0	0.12	Linux/UNIX	USD	default	Medium Utilization
OFFERING	ceb6a579-757c-474b-b09b-52c84example	us-east-1c	m1.small	1y 	227.5	0.03	Linux/UNIX	USD	default	Medium Utilization
OFFERING	60dcfab3-06bb-4b68-9503-53bf8example	us-east-1b	m1.small	1y 	227.5	0.03	Linux/UNIX	USD	default	Medium Utilization
OFFERING	438012d3-80c7-42c6-9396-a209cexample	us-east-1d	m1.small	1y 	227.5	0.03	Linux/UNIX	USD	default	Medium Utilization
OFFERING	649fd0c8-5d76-4881-a522-fe522example	us-east-1a	m1.small	1y 	227.5	0.03	Linux/UNIX	USD	default	Medium Utilization
...

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...

AWS Documentation » Amazon EC2 » Command Line Reference » Commands (CLI Tools) » ec2-describe-reserved-instances-offerings	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Description

Syntax

Options

Supported Filters

Common Options

Deprecated Options

Output

Examples

Example Request

Example Request

Related Operations