reserved_instances

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

Overview

Name	reserved_instances
Type	Resource
Id	aws.ec2.reserved_instances

Fields

The following fields are returned by SELECT queries:

describe_reserved_instances

Name	Datatype	Description
availability_zone	string	The Availability Zone in which the Reserved Instance can be used.
availability_zone_id	string	The ID of the Availability Zone.
currency_code	string	The currency of the Reserved Instance. It's specified using ISO 4217 standard currency codes. At this time, the only supported currency is USD.
duration	integer	The duration of the Reserved Instance, in seconds.
end	string	The time when the Reserved Instance expires.
fixed_price	number	The purchase price of the Reserved Instance.
instance_count	integer	The number of reservations purchased.
instance_tenancy	string	The tenancy of the instance.
instance_type	string	The instance type on which the Reserved Instance can be used.
offering_class	string	The offering class of the Reserved Instance.
offering_type	string	The Reserved Instance offering type.
product_description	string	The Reserved Instance product platform description.
recurring_charges	string	The recurring charge tag assigned to the resource.
reserved_instances_id	string	The ID of the Reserved Instance.
scope	string	The scope of the Reserved Instance.
start	string	The date and time the Reserved Instance started.
state	string	The state of the Reserved Instance purchase.
tags	string	Any tags assigned to the resource.
usage_price	number	The usage price of the Reserved Instance, per hour.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_reserved_instances	select	region	OfferingClass, ReservedInstancesId, DryRun, Filter, OfferingType	Describes one or more of the Reserved Instances that you purchased. For more information about Reserved Instances, see Reserved Instances in the Amazon EC2 User Guide. 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.
modify_reserved_instances	update	ReservedInstancesId, ReservedInstancesConfigurationSetItemType, region	ClientToken	Modifies the configuration of your Reserved Instances, such as the Availability Zone, instance count, or instance type. The Reserved Instances to be modified must be identical, except for Availability Zone, network platform, and instance type. For more information, see Modify Reserved Instances in the Amazon EC2 User Guide.
delete_queued_reserved_instances	delete	ReservedInstancesId, region	DryRun	Deletes the queued purchases for the specified Reserved Instances.
accept_reserved_instances_exchange_quote	exec	ReservedInstanceId, region	DryRun, TargetConfiguration	Accepts the Convertible Reserved Instance exchange quote described in the GetReservedInstancesExchangeQuote call.
cancel_reserved_instances_listing	exec	ReservedInstancesListingId, region		Cancels the specified Reserved Instance listing in the Reserved Instance Marketplace. For more information, see Sell in the Reserved Instance Marketplace in the Amazon EC2 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.

Name	Datatype	Description
ReservedInstanceId	array	The IDs of the Convertible Reserved Instances to exchange for another Convertible Reserved Instance of the same or higher value.
ReservedInstancesConfigurationSetItemType	array	The configuration settings for the Reserved Instances to modify.
ReservedInstancesId	array	The IDs of the Reserved Instances.
ReservedInstancesListingId	string	The ID of the Reserved Instance listing.
region	string	AWS region (default: us-east-1)
ClientToken	string	A unique, case-sensitive token you provide to ensure idempotency of your modification request. For more information, see Ensuring Idempotency.
DryRun	boolean	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.
Filter	array	One or more filters. availability-zone - The Availability Zone where the Reserved Instance can be used. availability-zone-id - The ID of the Availability Zone where the Reserved Instance can be used. duration - The duration of the Reserved Instance (one year or three years), in seconds (31536000 | 94608000). end - The time when the Reserved Instance expires (for example, 2015-08-07T11:54:42.000Z). fixed-price - The purchase price of the Reserved Instance (for example, 9800.0). instance-type - The instance type that is covered by the reservation. scope - The scope of the Reserved Instance (Region or Availability Zone). product-description - The Reserved Instance product platform description (Linux/UNIX | Linux with SQL Server Standard | Linux with SQL Server Web | Linux with SQL Server Enterprise | SUSE Linux | Red Hat Enterprise Linux | Red Hat Enterprise Linux with HA | Windows | Windows with SQL Server Standard | Windows with SQL Server Web | Windows with SQL Server Enterprise). reserved-instances-id - The ID of the Reserved Instance. start - The time at which the Reserved Instance purchase request was placed (for example, 2014-08-07T11:54:42.000Z). state - The state of the Reserved Instance (payment-pending | active | payment-failed | retired). 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. usage-price - The usage price of the Reserved Instance, per hour (for example, 0.84).
OfferingClass	string	Describes whether the Reserved Instance is Standard or Convertible.
OfferingType	string	The Reserved Instance offering type. 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.
ReservedInstancesId	array	One or more Reserved Instance IDs. Default: Describes all your Reserved Instances, or only those otherwise specified.
TargetConfiguration	array	The configuration of the target Convertible Reserved Instance to exchange for your current Convertible Reserved Instances.

SELECT examples

describe_reserved_instances

Describes one or more of the Reserved Instances that you purchased. For more information about Reserved Instances, see Reserved Instances in the Amazon EC2 User Guide. 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
availability_zone,
availability_zone_id,
currency_code,
duration,
end,
fixed_price,
instance_count,
instance_tenancy,
instance_type,
offering_class,
offering_type,
product_description,
recurring_charges,
reserved_instances_id,
scope,
start,
state,
tags,
usage_price
FROM aws.ec2.reserved_instances
WHERE region = '{{ region }}' -- required
AND OfferingClass = '{{ OfferingClass }}'
AND ReservedInstancesId = '{{ ReservedInstancesId }}'
AND DryRun = '{{ DryRun }}'
AND Filter = '{{ Filter }}'
AND OfferingType = '{{ OfferingType }}'
;

UPDATE examples

modify_reserved_instances

Modifies the configuration of your Reserved Instances, such as the Availability Zone, instance count, or instance type. The Reserved Instances to be modified must be identical, except for Availability Zone, network platform, and instance type. For more information, see Modify Reserved Instances in the Amazon EC2 User Guide.

UPDATE aws.ec2.reserved_instances
SET 
-- No updatable properties
WHERE 
ReservedInstancesId = '{{ ReservedInstancesId }}' --required
AND ReservedInstancesConfigurationSetItemType = '{{ ReservedInstancesConfigurationSetItemType }}' --required
AND region = '{{ region }}' --required
AND ClientToken = '{{ ClientToken}}'
RETURNING
reserved_instances_modification_id;

DELETE examples

delete_queued_reserved_instances

Deletes the queued purchases for the specified Reserved Instances.

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

Lifecycle Methods

accept_reserved_instances_exchange_quote

Accepts the Convertible Reserved Instance exchange quote described in the GetReservedInstancesExchangeQuote call.

EXEC aws.ec2.reserved_instances.accept_reserved_instances_exchange_quote 
@ReservedInstanceId='{{ ReservedInstanceId }}' --required, 
@region='{{ region }}' --required, 
@DryRun={{ DryRun }}, 
@TargetConfiguration='{{ TargetConfiguration }}'
;

cancel_reserved_instances_listing

Cancels the specified Reserved Instance listing in the Reserved Instance Marketplace. For more information, see Sell in the Reserved Instance Marketplace in the Amazon EC2 User Guide.

EXEC aws.ec2.reserved_instances.cancel_reserved_instances_listing 
@ReservedInstancesListingId='{{ ReservedInstancesListingId }}' --required, 
@region='{{ region }}' --required
;