.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VM::EC2::REST::spot_instance 3pm"
.TH VM::EC2::REST::spot_instance 3pm "2016-06-04" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME VM::EC2::REST::spot_instance \- Request spot instances and manipulate spot data feed subscriptions"
.IX Header "NAME VM::EC2::REST::spot_instance - Request spot instances and manipulate spot data feed subscriptions"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use VM::EC2 \*(Aq:misc\*(Aq;
.Ve
.SH "METHODS"
.IX Header "METHODS"
These methods allow you to request spot instances and manipulate spot
data feed subscriptions.
.PP
Implemented:
 CancelSpotInstanceRequests
 CreateSpotDatafeedSubscription
 DeleteSpotDatafeedSubscription
 DescribeSpotDatafeedSubscription
 DescribeSpotInstanceRequests
 DescribeSpotPriceHistory
 RequestSpotInstances
.PP
Unimplemented:
 (none)
.ie n .SS "$subscription = $ec2\->create_spot_datafeed_subscription($bucket,$prefix)"
.el .SS "\f(CW$subscription\fP = \f(CW$ec2\fP\->create_spot_datafeed_subscription($bucket,$prefix)"
.IX Subsection "$subscription = $ec2->create_spot_datafeed_subscription($bucket,$prefix)"
This method creates a spot datafeed subscription. Provide the method with the
name of an S3 bucket associated with your account, and a prefix to be appended
to the files written by the datafeed. Spot instance usage logs will be written 
into the requested bucket, and prefixed with the desired prefix.
.PP
If no prefix is specified, it defaults to \*(L"\s-1SPOT_DATAFEED_\*(R"\s0;
.PP
On success, a VM::EC2::Spot::DatafeedSubscription object is returned;
.PP
Only one datafeed is allowed per account;
.ie n .SS "$boolean = $ec2\->\fIdelete_spot_datafeed_subscription()\fP"
.el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->\fIdelete_spot_datafeed_subscription()\fP"
.IX Subsection "$boolean = $ec2->delete_spot_datafeed_subscription()"
This method delete's the current account's spot datafeed
subscription, if any. It takes no arguments.
.PP
On success, it returns true.
.ie n .SS "$subscription = $ec2\->\fIdescribe_spot_datafeed_subscription()\fP"
.el .SS "\f(CW$subscription\fP = \f(CW$ec2\fP\->\fIdescribe_spot_datafeed_subscription()\fP"
.IX Subsection "$subscription = $ec2->describe_spot_datafeed_subscription()"
This method describes the current account's spot datafeed
subscription, if any. It takes no arguments.
.PP
On success, a VM::EC2::Spot::DatafeedSubscription object is returned;
.ie n .SS "@spot_price_history = $ec2\->describe_spot_price_history(@filters)"
.el .SS "\f(CW@spot_price_history\fP = \f(CW$ec2\fP\->describe_spot_price_history(@filters)"
.IX Subsection "@spot_price_history = $ec2->describe_spot_price_history(@filters)"
This method applies the specified filters to spot instances and
returns a list of instances, timestamps and their price at the
indicated time. Each spot price history point is represented as a
VM::EC2::Spot::PriceHistory object.
.PP
Option arguments are:
.PP
.Vb 4
\& \-start_time      Start date and time of the desired history
\&                  data, in the form yyyy\-mm\-ddThh:mm:ss (GMT).
\&                  The Perl DateTime module provides a convenient
\&                  way to create times in this format.
\&
\& \-end_time        End date and time of the desired history
\&                  data.
\&
\& \-instance_type   The instance type, e.g. "m1.small", can be
\&                  a scalar value or an arrayref.
\&
\& \-product_description  The product description. One of "Linux/UNIX",
\&                  "SUSE Linux"  or "Windows". Can be a scalar value
\&                  or an arrayref.
\&
\& \-availability_zone A single availability zone, such as "us\-east\-1a".
\&
\& \-max_results     Maximum number of rows to return in a single
\&                  call.
\&
\& \-next_token      Specifies the next set of results to return; used
\&                  internally.
\&
\& \-filter          Hashref containing additional filters to apply,
.Ve
.PP
The following filters are recognized: \*(L"instance-type\*(R",
\&\*(L"product-description\*(R", \*(L"spot-price\*(R", \*(L"timestamp\*(R",
\&\*(L"availability-zone\*(R". The '*' and '?' wildcards can be used in filter
values, but numeric comparison operations are not supported by the
Amazon \s-1API.\s0 Note that wildcards are not generally allowed in the
standard options. Hence if you wish to get spot price history in all
availability zones in us-east, this will work:
.PP
.Vb 1
\& $ec2\->describe_spot_price_history(\-filter=>{\*(Aqavailability\-zone\*(Aq=>\*(Aqus\-east*\*(Aq})
.Ve
.PP
but this will return an invalid parameter error:
.PP
.Vb 1
\& $ec2\->describe_spot_price_history(\-availability_zone=>\*(Aqus\-east*\*(Aq)
.Ve
.PP
If you specify \-max_results, then the list of history objects returned
may not represent the complete result set. In this case, the method
\&\fImore_spot_prices()\fR will return true. You can then call
\&\fIdescribe_spot_price_history()\fR repeatedly with no arguments in order to
retrieve the remainder of the results. When there are no more results,
\&\fImore_spot_prices()\fR will return false.
.PP
.Vb 9
\& my @results = $ec2\->describe_spot_price_history(\-max_results       => 20,
\&                                                 \-instance_type     => \*(Aqm1.small\*(Aq,
\&                                                 \-availability_zone => \*(Aqus\-east*\*(Aq,
\&                                                 \-product_description=>\*(AqLinux/UNIX\*(Aq);
\& print_history(\e@results);
\& while ($ec2\->more_spot_prices) {
\&    @results = $ec2\->describe_spot_price_history
\&    print_history(\e@results);
\& }
.Ve
.ie n .SS "@requests = $ec2\->request_spot_instances(%args)"
.el .SS "\f(CW@requests\fP = \f(CW$ec2\fP\->request_spot_instances(%args)"
.IX Subsection "@requests = $ec2->request_spot_instances(%args)"
This method will request one or more spot instances to be launched
when the current spot instance run-hour price drops below a preset
value and terminated when the spot instance run-hour price exceeds the
value.
.PP
On success, will return a series of VM::EC2::Spot::InstanceRequest
objects, one for each instance specified in \-instance_count.
.IP "Required arguments:" 4
.IX Item "Required arguments:"
.Vb 1
\&  \-spot_price        The desired spot price, in USD.
\&
\&  \-image_id          ID of an AMI to launch
\&
\&  \-instance_type     Type of the instance(s) to launch, such as "m1.small"
.Ve
.IP "Optional arguments:" 4
.IX Item "Optional arguments:"
.Vb 1
\&  \-instance_count    Maximum number of instances to launch (default 1)
\&
\&  \-type              Spot instance request type; one of "one\-time" or "persistent"
\&
\&  \-valid_from        Date/time the request becomes effective, in format
\&                       yyyy\-mm\-ddThh:mm:ss. Default is immediately.
\&
\&  \-valid_until       Date/time the request expires, in format 
\&                       yyyy\-mm\-ddThh:mm:ss. Default is to remain in
\&                       effect indefinitely.
\&
\&  \-launch_group      Name of the launch group. Instances in the same
\&                       launch group are started and terminated together.
\&                       Default is to launch instances independently.
\&
\&  \-availability_zone_group  If specified, all instances that are given
\&                       the same zone group name will be launched into the 
\&                       same availability zone. This is independent of
\&                       the \-availability_zone argument, which specifies
\&                       a particular availability zone.
\&
\&  \-key_name          Name of the keypair to use
\&
\&  \-security_group_id Security group ID to use for this instance.
\&                     Use an arrayref for multiple group IDs
\&
\&  \-security_group    Security group name to use for this instance.
\&                     Use an arrayref for multiple values.
\&
\&  \-user_data         User data to pass to the instances. Do NOT base64
\&                     encode this. It will be done for you.
\&
\&  \-availability_zone The availability zone you want to launch the
\&                     instance into. Call $ec2\->regions for a list.
\&  \-zone              Short version of \-availability_aone.
\&
\&  \-placement_group   An existing placement group to launch the
\&                     instance into. Applicable to cluster instances
\&                     only.
\&  \-placement_tenancy Specify \*(Aqdedicated\*(Aq to launch the instance on a
\&                     dedicated server. Only applicable for VPC
\&                     instances.
\&
\&  \-kernel_id         ID of the kernel to use for the instances,
\&                     overriding the kernel specified in the image.
\&
\&  \-ramdisk_id        ID of the ramdisk to use for the instances,
\&                     overriding the ramdisk specified in the image.
\&
\&  \-block_devices     Specify block devices to map onto the instances,
\&                     overriding the values specified in the image.
\&                     See run_instances() for the syntax of this argument.
\&
\&  \-block_device_mapping  Alias for \-block_devices.
\&
\&  \-network_interfaces  Same as the \-network_interfaces option in run_instances().
\&
\&  \-monitoring        Pass a true value to enable detailed monitoring.
\&
\&  \-subnet            The ID of the Amazon VPC subnet in which to launch the
\&                      spot instance (VPC only).
\&
\&  \-subnet_id         deprecated
\&
\&  \-addressing_type   Deprecated and undocumented, but present in the
\&                       current EC2 API documentation.
\&
\&  \-iam_arn           The Amazon resource name (ARN) of the IAM Instance Profile (IIP)
\&                       to associate with the instances.
\&
\&  \-iam_name          The name of the IAM instance profile (IIP) to associate with the
\&                       instances.
\&
\&  \-ebs_optimized     If true, request an EBS\-optimized instance (certain
\&                       instance types only).
.Ve
.ie n .SS "@requests = $ec2\->cancel_spot_instance_requests(@request_ids)"
.el .SS "\f(CW@requests\fP = \f(CW$ec2\fP\->cancel_spot_instance_requests(@request_ids)"
.IX Subsection "@requests = $ec2->cancel_spot_instance_requests(@request_ids)"
This method cancels the pending requests. It does not terminate any
instances that are already running as a result of the requests. It
returns a list of VM::EC2::Spot::InstanceRequest objects, whose fields
will be unpopulated except for spotInstanceRequestId and state.
.ie n .SS "@requests = $ec2\->describe_spot_instance_requests(@spot_instance_request_ids)"
.el .SS "\f(CW@requests\fP = \f(CW$ec2\fP\->describe_spot_instance_requests(@spot_instance_request_ids)"
.IX Subsection "@requests = $ec2->describe_spot_instance_requests(@spot_instance_request_ids)"
.ie n .SS "@requests = $ec2\->describe_spot_instance_requests(\e%filters)"
.el .SS "\f(CW@requests\fP = \f(CW$ec2\fP\->describe_spot_instance_requests(\e%filters)"
.IX Subsection "@requests = $ec2->describe_spot_instance_requests(%filters)"
.ie n .SS "@requests = $ec2\->describe_spot_instance_requests(\-spot_instance_request_id=>\e@ids,\-filter=>\e%filters)"
.el .SS "\f(CW@requests\fP = \f(CW$ec2\fP\->describe_spot_instance_requests(\-spot_instance_request_id=>\e@ids,\-filter=>\e%filters)"
.IX Subsection "@requests = $ec2->describe_spot_instance_requests(-spot_instance_request_id=>@ids,-filter=>%filters)"
This method will return information about current spot instance
requests as a list of VM::EC2::Spot::InstanceRequest objects.
.PP
Optional arguments:
.PP
.Vb 1
\& \-spot_instance_request_id   \-\- Scalar or arrayref of request Ids.
\&
\& \-filter                     \-\- Tags and other filters to apply.
.Ve
.PP
There are many filters available, described fully at
http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/index.html?ApiReference\-ItemType\-SpotInstanceRequestSetItemType.html:
.PP
.Vb 10
\&    availability\-zone\-group
\&    create\-time
\&    fault\-code
\&    fault\-message
\&    instance\-id
\&    launch\-group
\&    launch.block\-device\-mapping.delete\-on\-termination
\&    launch.block\-device\-mapping.device\-name
\&    launch.block\-device\-mapping.snapshot\-id
\&    launch.block\-device\-mapping.volume\-size
\&    launch.block\-device\-mapping.volume\-type
\&    launch.group\-id
\&    launch.image\-id
\&    launch.instance\-type
\&    launch.kernel\-id
\&    launch.key\-name
\&    launch.monitoring\-enabled
\&    launch.ramdisk\-id
\&    launch.network\-interface.network\-interface\-id
\&    launch.network\-interface.device\-index
\&    launch.network\-interface.subnet\-id
\&    launch.network\-interface.description
\&    launch.network\-interface.private\-ip\-address
\&    launch.network\-interface.delete\-on\-termination
\&    launch.network\-interface.group\-id
\&    launch.network\-interface.group\-name
\&    launch.network\-interface.addresses.primary
\&    product\-description
\&    spot\-instance\-request\-id
\&    spot\-price
\&    state
\&    status\-code
\&    status\-message
\&    tag\-key
\&    tag\-value
\&    tag:<key>
\&    type
\&    launched\-availability\-zone
\&    valid\-from
\&    valid\-until
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lincoln.stein@gmail.com>.
.PP
Copyright (c) 2011 Ontario Institute for Cancer Research
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL \s0(either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.