1package VM::EC2::REST::reserved_instance; 2 3use strict; 4use VM::EC2 ''; # important not to import anything! 5package VM::EC2; # add methods to VM::EC2 6require VM::EC2::ReservedInstance::ParmParser; 7 8VM::EC2::Dispatch->register( 9 CancelReservedInstancesListing => 'fetch_items,reservedInstancesListingsSet,VM::EC2::ReservedInstance::Listing', 10 CreateReservedInstancesListing => 'fetch_items,reservedInstancesListingsSet,VM::EC2::ReservedInstance::Listing', 11 DescribeReservedInstances => 'fetch_items,reservedInstancesSet,VM::EC2::ReservedInstance', 12 DescribeReservedInstancesListings => 'fetch_items,reservedInstancesListingsSet,VM::EC2::ReservedInstance::Listing', 13 DescribeReservedInstancesModifications => 14 'fetch_items,reservedInstancesModificationsSet,VM::EC2::ReservedInstance::Modification', 15 DescribeReservedInstancesOfferings => 'fetch_items,reservedInstancesOfferingsSet,VM::EC2::ReservedInstance::Offering', 16 ModifyReservedInstances => sub { my ($data,$ec2) = @_; 17 return $data->{reservedInstancesModificationId}; }, 18 PurchaseReservedInstancesOffering => sub { my ($data,$ec2) = @_; 19 my $ri_id = $data->{reservedInstancesId} or return; 20 return $ec2->describe_reserved_instances($ri_id); }, 21 ); 22 23my $VEP = 'VM::EC2::ReservedInstance::ParmParser'; 24 25=head1 NAME VM::EC2::REST::reserved_instance 26 27=head1 SYNOPSIS 28 29 use VM::EC2 ':misc' 30 31=head1 METHODS 32 33These methods apply to describing, purchasing and using Reserved Instances. 34 35Implemented: 36 CancelReservedInstancesListing 37 DescribeReservedInstances 38 DescribeReservedInstancesListings 39 DescribeReservedInstancesModifications 40 DescribeReservedInstancesOfferings 41 ModifyReservedInstances 42 PurchaseReservedInstancesOffering 43 CreateReservedInstancesListing 44 45Unimplemented: 46 (none) 47 48=head2 @offerings = $ec2->describe_reserved_instances_offerings(@offering_ids) 49 50=head2 @offerings = $ec2->describe_reserved_instances_offerings(%args) 51 52This method returns a list of the reserved instance offerings 53currently available for purchase. The arguments allow you to filter 54the offerings according to a variety of filters. 55 56All arguments are optional. If no named arguments are used, then the 57arguments are treated as Reserved Instance Offering IDs. 58 59 -reserved_instances_offering_id A scalar or arrayref of reserved 60 instance offering IDs 61 62 -instance_type The instance type on which the 63 reserved instance can be used, 64 e.g. "c1.medium" 65 66 -availability_zone, -zone The availability zone in which the 67 reserved instance can be used. 68 69 -product_description The reserved instance description. 70 Valid values are "Linux/UNIX", 71 "Linux/UNIX (Amazon VPC)", 72 "Windows", and "Windows (Amazon 73 VPC)" 74 75 -instance_tenancy The tenancy of the reserved instance 76 offering, either "default" or 77 "dedicated". (VPC instances only) 78 79 -offering_type The reserved instance offering type, one of 80 "Heavy Utilization", "Medium Utilization", 81 or "Light Utilization". 82 83 -filter A set of filters to apply. 84 85For available filters, see http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeReservedInstancesOfferings.html. 86 87The returned objects are of type L<VM::EC2::ReservedInstance::Offering> 88 89This can be combined with the Offering purchase() method as shown here: 90 91 @offerings = $ec2->describe_reserved_instances_offerings( 92 {'availability-zone' => 'us-east-1a', 93 'instance-type' => 'c1.medium', 94 'product-description' =>'Linux/UNIX', 95 'duration' => 31536000, # this is 1 year 96 }); 97 $offerings[0]->purchase(5) and print "Five reserved instances purchased\n"; 98 99=cut 100 101sub describe_reserved_instances_offerings { 102 my $self = shift; 103 my %args = $VEP->args(-reserved_instances_offering_id,@_); 104 $args{-availability_zone} ||= $args{-zone}; 105 my @param = $VEP->format_parms(\%args, 106 { 107 list_parm => 'ReservedInstancesOfferingId', 108 single_parm => [qw(ProductDescription InstanceType AvailabilityZone 109 InstanceTenancy OfferingType)], 110 filter_parm => 'Filter', 111 }); 112 return $self->call('DescribeReservedInstancesOfferings',@param); 113} 114 115=head $id = $ec2->purchase_reserved_instances_offering($offering_id) 116 117=head $id = $ec2->purchase_reserved_instances_offering(%args) 118 119Purchase one or more reserved instances based on an offering. 120 121Arguments: 122 123 -reserved_instances_offering_id, -id -- The reserved instance offering ID 124 to purchase (required). 125 126 -instance_count, -count -- Number of instances to reserve 127 under this offer (optional, defaults 128 to 1). 129 130 131Returns a Reserved Instances Id on success, undef on failure. Also see the purchase() method of 132L<VM::EC2::ReservedInstance::Offering>. 133 134=cut 135 136sub purchase_reserved_instances_offering { 137 my $self = shift; 138 my %args = $VEP->args(-reserved_instances_offering_id,@_); 139 $args{-reserved_instances_offering_id} ||= $args{-id}; 140 $args{-reserved_instances_offering_id} or 141 croak "purchase_reserved_instances_offering(): the -reserved_instances_offering_id argument is required"; 142 $args{-instance_count} ||= $args{-count}; 143 my @param = $VEP->format_parms(\%args, 144 { 145 single_parm => [qw(ReservedInstancesOfferingId InstanceCount)], 146 }); 147 return $self->call('PurchaseReservedInstancesOffering',@param); 148} 149 150=head2 @res_instances = $ec2->describe_reserved_instances(@res_instance_ids) 151 152=head2 @res_instances = $ec2->describe_reserved_instances(%args) 153 154This method returns a list of the reserved instances that you 155currently own. The information returned includes the type of 156instances that the reservation allows you to launch, the availability 157zone, and the cost per hour to run those reserved instances. 158 159All arguments are optional. If no named arguments are used, then the 160arguments are treated as Reserved Instance IDs. 161 162 -reserved_instances_id -- A scalar or arrayref of reserved 163 instance IDs 164 165 -filter -- A set of filters to apply. 166 167For available filters, see http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeReservedInstances.html. 168 169The returned objects are of type L<VM::EC2::ReservedInstance> 170 171=cut 172 173sub describe_reserved_instances { 174 my $self = shift; 175 my %args = $VEP->args(-reserved_instances_id,@_); 176 my @param = $VEP->format_parms(\%args, 177 { 178 list_parm => 'ReservedInstancesId', 179 filter_parm => 'Filter', 180 }); 181 return $self->call('DescribeReservedInstances',@param); 182} 183 184=head2 $id = $ec2->modify_reserved_instances(%args) 185 186Modifies the Availability Zone, instance count, instance type, or network 187platform (EC2-Classic or EC2-VPC) of your Reserved Instances. The Reserved 188Instances to be modified must be identical, except for Availability Zone, 189network platform, and instance type. 190 191Required arguments: 192 193 -reserved_instances_id -- The IDs of the Reserved Instances to modify 194 Can be scalar or arrayref. 195 196 -target_configuration -- The configuration settings for the Reserved 197 Instances to modify 198 199 Must be a hashref or arrayref of hashes with 200 one or more of the following values: 201 AvailabilityZone, Platform, InstanceType 202 The following is also REQUIRED: 203 InstanceCount 204 205 -id -- Alias for -reserved_instances_id 206 207Returns the reserved instances modification ID string. 208 209=cut 210 211sub modify_reserved_instances { 212 my $self = shift; 213 my %args = @_; 214 $args{-reserved_instances_id} ||= $args{-id}; 215 $args{-reserved_instances_id} or 216 croak "modify_reserved_instances(): -reserved_instances_id argument required"; 217 $args{-target_configuration} or 218 croak "modify_reserved_instances(): -target_configuration argument required"; 219 my @param = $VEP->format_parms(\%args, 220 { 221 list_parm => 'ReservedInstancesId', 222 ri_target_config_parm => 'TargetConfiguration', 223 }); 224 return $self->call('ModifyReservedInstances',@param); 225} 226 227=head2 @mods = $ec2->describe_reserved_instances_modifications(@ids) 228 229=head2 @mods = $ec2->describe_reserved_instances_modifications(%args) 230 231Describes the modifications made to your Reserved Instances. 232 233All arguments are optional. If no named arguments are used, then the 234arguments are treated as Reserved Instance Modification IDs. 235 236 -reserved_instances_modification_id -- A scalar or arrayref of reserved 237 instance modification IDs 238 239 -filter -- A set of filters to apply. 240 241 -id -- Alias for -reserved_instances_modification_id 242 243For available filters, see: 244http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeReservedInstancesModifications.html 245 246The returned objects are of type L<VM::EC2::ReservedInstance::Modification> 247 248=cut 249 250sub describe_reserved_instances_modifications { 251 my $self = shift; 252 my %args = $VEP->args(-reserved_instances_modification_id,@_); 253 $args{-reserved_instances_modification_id} ||= $args{-id}; 254 my @param = $VEP->format_parms(\%args, 255 { 256 list_parm => 'ReservedInstancesModificationId', 257 filter_parm => 'Filter', 258 }); 259 return $self->call('DescribeReservedInstancesModifications',@param); 260} 261 262=head2 @list = $ec2->describe_reserved_instances_listings(%args) 263 264Describes the account's Reserved Instance listings in the Reserved Instance 265Marketplace. 266 267All arguments are optional. If no named arguments are used, then the 268arguments are treated as Reserved Instance Listing IDs. 269 270 -reserved_instances_listing_id -- A scalar or arrayref of reserved 271 instance listing IDs 272 273 -reserved_instances_id -- A scalar or arrayref of reserved 274 instance IDs 275 276 -filter -- A set of filters to apply. 277 278For available filters, see: 279http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeReservedInstancesListings.html 280 281The returned objects are of type L<VM::EC2::ReservedInstance::Listing> 282 283=cut 284 285sub describe_reserved_instances_listings { 286 my $self = shift; 287 my %args = $VEP->args(-reserved_instances_listing_id,@_); 288 my @param = $VEP->format_parms(\%args, 289 { 290 list_parm => [qw(ReservedInstancesListingId ReservedInstancesId)], 291 filter_parm => 'Filter', 292 }); 293 return $self->call('DescribeReservedInstancesListings',@param); 294} 295 296=head2 $listing = $ec2->cancel_reserved_instances_listing(%args) 297 298Cancels the specified Reserved Instance listing in the Reserved Instance 299Marketplace. 300 301Required arguments: 302 303 -reserved_instances_listing_id -- The ID of the Reserved Instance listing 304 to be canceled 305 306Returns an object of type L<VM::EC2::ReservedInstance::Listing> 307 308=cut 309 310sub cancel_reserved_instances_listing { 311 my $self = shift; 312 my %args = $VEP->args(-reserved_instances_listing_id,@_); 313 my @param = $VEP->format_parms(\%args, 314 { 315 single_parm => 'ReservedInstancesListingId', 316 }); 317 return $self->call('CancelReservedInstancesListing',@param); 318} 319 320=head2 $listing = $ec2->create_reserved_instances_listing(%args) 321 322Creates a listing for Amazon EC2 Reserved Instances to be sold in the Reserved 323Instance Marketplace. Only one Reserved Instance listing may be created at a 324time. 325 326Required arguments: 327 328 -reserved_instances_id -- The ID of the active Reserved Instance 329 330 -instance_count -- The number of instances to be listed in the 331 Reserved Instance Marketplace. This number 332 should be less than or equal to the instance count 333 associated with the Reserved Instance ID specified 334 335 -price_schedules -- hashref containing term/price pairs for months 336 the Reserved Instance has remaining in its term 337 338 For example, with a RI with 11 months to go: 339 340 { 11 => 2.5, 341 8 => 2.0, 342 5 => 1.5, 343 3 => 0.7, 344 1 => 0.1 } 345 346 For months 11,10,9 the price is $2.50, 8,7,6 is 347 $2.00, 5,4 is $1.50, 3,2 is $0.70 and the last 348 month is $0.10. 349 350 For more details, see the API docs at: 351http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ApiReference-query-CreateReservedInstancesListing.html 352 353 354 -client_token -- Unique, case-sensitive identifier to ensure 355 idempotency of listings 356 357Returns an object of type L<VM::EC2::ReservedInstance::Listing> 358 359=cut 360 361sub create_reserved_instances_listing { 362 my $self = shift; 363 my %args = $VEP->args(-reserved_instances_listing_id,@_); 364 $args{-reserved_instances_id} or 365 croak "create_reserved_instances_listing(): -reserved_instances_id argument required"; 366 $args{-instance_count} or 367 croak "create_reserved_instances_listing(): -instance_count argument required"; 368 $args{-price_schedules} or 369 croak "create_reserved_instances_listing(): -price_schedules argument required"; 370 $args{-client_token} or 371 croak "create_reserved_instances_listing(): -client_token argument required"; 372 ref $args{-price_schedules} eq 'HASH' or 373 croak "create_reserved_instances_listing(): -price_schedules argument must be hashref"; 374 375 my @param = $VEP->format_parms(\%args, 376 { 377 single_parm => [qw(ReservedInstancesId InstanceCount 378 ClientToken)], 379 ri_price_sched_parm => 'PriceSchedules', 380 }); 381 return $self->call('CreateReservedInstancesListing',@param); 382} 383 384=head1 SEE ALSO 385 386L<VM::EC2> 387 388=head1 AUTHOR 389 390Lincoln Stein E<lt>lincoln.stein@gmail.comE<gt>. 391 392Lance Kinley E<lt>lkinley@loyaltymethods.comE<gt>. 393 394Copyright (c) 2011 Ontario Institute for Cancer Research 395 396Copyright (c) 2014 Loyalty Methods, Inc. 397 398This package and its accompanying libraries is free software; you can 399redistribute it and/or modify it under the terms of the GPL (either 400version 1, or at your option, any later version) or the Artistic 401License 2.0. Refer to LICENSE for the full license text. In addition, 402please see DISCLAIMER.txt for disclaimers of warranty. 403 404=cut 405 4061; 407