.\" 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::instance 3pm" .TH VM::EC2::REST::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::instance \- VM::EC2 methods for controlling instances .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use VM::EC2 \*(Aq:standard\*(Aq; .Ve .SH "METHODS" .IX Header "METHODS" The methods in this section allow you to retrieve information about \&\s-1EC2\s0 instances, launch new instances, control the instance lifecycle (e.g. starting and stopping them), and fetching the console output from instances. .PP Implemented: ConfirmProductInstance DescribeInstanceAttribute DescribeInstances DescribeInstanceStatus ModifyInstanceAttribute RebootInstances ResetInstanceAttribute RunInstances StartInstances StopInstances TerminateInstances .PP Unimplemented: (none) .PP The primary object manipulated by these methods is VM::EC2::Instance. Please see the VM::EC2::Instance manual page for additional methods that allow you to attach and detach volumes, modify an instance's attributes, and convert instances into images. .ie n .SS "@instances = $ec2\->describe_instances(@instance_ids)" .el .SS "\f(CW@instances\fP = \f(CW$ec2\fP\->describe_instances(@instance_ids)" .IX Subsection "@instances = $ec2->describe_instances(@instance_ids)" .ie n .SS "@instances = $ec2\->describe_instances(\e%filters)" .el .SS "\f(CW@instances\fP = \f(CW$ec2\fP\->describe_instances(\e%filters)" .IX Subsection "@instances = $ec2->describe_instances(%filters)" .ie n .SS "@instances = $ec2\->describe_instances(\-instance_id=>\e@ids,\-filter=>\e%filters)" .el .SS "\f(CW@instances\fP = \f(CW$ec2\fP\->describe_instances(\-instance_id=>\e@ids,\-filter=>\e%filters)" .IX Subsection "@instances = $ec2->describe_instances(-instance_id=>@ids,-filter=>%filters)" Return a series of VM::EC2::Instance objects. Optional arguments are: .PP .Vb 2 \& \-instance_id ID of the instance(s) to return information on. \& This can be a string scalar, or an arrayref. \& \& \-filter Tags and other filters to apply. .Ve .PP The filter argument is a hashreference in which the keys are the filter names, and the values are the match strings. Some filters accept wildcards. .PP A typical filter example: .PP .Vb 5 \& $ec2\->describe_instances( \& \-filter => {\*(Aqblock\-device\-mapping.device\-name\*(Aq=>\*(Aq/dev/sdh\*(Aq, \& \*(Aqarchitecture\*(Aq => \*(Aqi386\*(Aq, \& \*(Aqtag:Role\*(Aq => \*(AqServer\*(Aq \& }); .Ve .PP You may omit the \-filter argument name if there are no other arguments: .PP .Vb 3 \& $ec2\->describe_instances({\*(Aqblock\-device\-mapping.device\-name\*(Aq=>\*(Aq/dev/sdh\*(Aq, \& \*(Aqarchitecture\*(Aq => \*(Aqi386\*(Aq, \& \*(Aqtag:Role\*(Aq => \*(AqServer\*(Aq}); .Ve .PP There are a large number of filters, which are listed in full at http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference\-query\-DescribeInstances.html. .PP Here is a alpha-sorted list of filter names: architecture, availability-zone, block\-device\-mapping.attach\-time, block\-device\-mapping.delete\-on\-termination, block\-device\-mapping.device\-name, block\-device\-mapping.status, block\-device\-mapping.volume\-id, client-token, dns-name, group-id, group-name, hypervisor, image-id, instance-id, instance-lifecycle, instance-state-code, instance-state-name, instance-type, instance.group\-id, instance.group\-name, ip-address, kernel-id, key-name, launch-index, launch-time, monitoring-state, owner-id, placement-group-name, platform, private-dns-name, private-ip-address, product-code, ramdisk-id, reason, requester-id, reservation-id, root-device-name, root-device-type, source-dest-check, spot-instance-request-id, state-reason-code, state-reason-message, subnet-id, tag-key, tag-value, tag:key, virtualization-type, vpc-id. .PP Note that the objects returned from this method are the instances themselves, and not a reservation set. The reservation \s-1ID\s0 can be retrieved from each instance by calling its \fIreservationId()\fR method. .ie n .SS "@i = $ec2\->run_instances($ami_id)" .el .SS "\f(CW@i\fP = \f(CW$ec2\fP\->run_instances($ami_id)" .IX Subsection "@i = $ec2->run_instances($ami_id)" .ie n .SS "@i = $ec2\->run_instances(\-image_id=>$id,%other_args)" .el .SS "\f(CW@i\fP = \f(CW$ec2\fP\->run_instances(\-image_id=>$id,%other_args)" .IX Subsection "@i = $ec2->run_instances(-image_id=>$id,%other_args)" This method will provision and launch one or more instances given an \&\s-1AMI ID.\s0 If successful, the method returns a series of VM::EC2::Instance objects. .PP If called with a single argument this will be interpreted as the \s-1AMI\s0 to launch, and all other arguments will take their defaults. Otherwise, the arguments will be taken as a \&\-parameter=>$argument list. .IP "Required arguments:" 4 .IX Item "Required arguments:" .Vb 1 \& \-image_id ID of an AMI to launch .Ve .IP "Optional arguments:" 4 .IX Item "Optional arguments:" .Vb 1 \& \-min_count Minimum number of instances to launch [1] \& \& \-max_count Maximum number of instances to launch [1] \& \& \-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. \& \& \-instance_type Type of the instance to use. See below for a \& list. \& \& \-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_zone Deprecated version of \-availability_zone. \& \& \-placement_group An existing placement group to launch the \& instance into. Applicable to cluster instances \& only. \& \& \-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 below for the syntax of this argument. \& \& \-block_device_mapping Alias for \-block_devices. \& \& \-monitoring Pass a true value to enable detailed monitoring. \& \& \-subnet_id ID of the subnet to launch the instance \& into. Only applicable for VPC instances. \& \& \-termination_protection Pass true to lock the instance so that it \& cannot be terminated using the API. Use \& modify_instance() to unset this if youu wish to \& terminate the instance later. \& \& \-disable_api_termination \-\- Same as above. \& \& \-shutdown_behavior Pass "stop" (the default) to stop the instance \& and save its disk state when "shutdown" is called \& from within the instance. Stopped instances can \& be restarted later. Pass "terminate" to \& instead terminate the instance and discard its \& state completely. \& \& \-instance_initiated_shutdown_behavior \-\- Same as above. \& \& \-private_ip_address Assign the instance to a specific IP address \& from a VPC subnet (VPC only). \& \& \-client_token Unique identifier that you can provide to ensure \& idempotency of the request. You can use \& $ec2\->token() to generate a suitable identifier. \& See http://docs.amazonwebservices.com/AWSEC2/ \& latest/UserGuide/Run_Instance_Idempotency.html \& \& \-network_interfaces A single network interface specification string \& or a list of them as an array reference (VPC only). \& These are described in more detail below. \& \& \-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 Boolean. If true, create an EBS\-optimized instance \& (valid only for certain instance types. .Ve .IP "Instance types" 4 .IX Item "Instance types" The following is the list of instance types currently allowed by Amazon: .Sp .Vb 3 \& m1.small c1.medium m2.xlarge cc1.4xlarge cg1.4xlarge t1.micro \& m1.large c1.xlarge m2.2xlarge \& m1.xlarge m2.4xlarge .Ve .IP "Block device syntax" 4 .IX Item "Block device syntax" The syntax of \-block_devices is identical to what is used by the ec2\-run\-instances command-line tool. Borrowing from the manual page of that tool: .Sp The format is '=', where 'block\-device' can be one of the following: .Sp .Vb 2 \& \- \*(Aqnone\*(Aq: indicates that a block device that would be exposed at the \& specified device should be suppressed. For example: \*(Aq/dev/sdb=none\*(Aq \& \& \- \*(Aqephemeral[0\-3]\*(Aq: indicates that the Amazon EC2 ephemeral store \& (instance local storage) should be exposed at the specified device. \& For example: \*(Aq/dev/sdc=ephemeral0\*(Aq. \& \& \- \*(Aqvol\-12345678\*(Aq: A volume ID will attempt to attach the given volume to the \& instance, contingent on volume state and availability zone. \& \& \- \*(Aqnone\*(Aq: Suppress this block device, even if it is mapped in the AMI. \& \& \- \*(Aq[][:[:[:[:]]]]\*(Aq: \& indicates that an Amazon EBS volume, created from the specified Amazon EBS \& snapshot, should be exposed at the specified device. The following \& combinations are supported: \& \& \- \*(Aq\*(Aq: the ID of an Amazon EBS snapshot, which must \& be owned by or restorable by the caller. May be left out if a \& is specified, creating an empty Amazon EBS volume of \& the specified size. \& \& \- \*(Aq\*(Aq: the size (GiBs) of the Amazon EBS volume to be \& created. If a snapshot was specified, this may not be smaller \& than the size of the snapshot itself. \& \& \- \*(Aq\*(Aq: indicates whether the Amazon EBS \& volume should be deleted on instance termination. If not \& specified, this will default to \*(Aqtrue\*(Aq and the volume will be \& deleted. \& \& \- \*(Aq\*(Aq: The volume type. One of "standard", "gp2" or "io1". \& "gp2" is the new general purpose SSD type. \& \& \- \*(Aq\*(Aq: The number of I/O operations per second (IOPS) that \& the volume supports. A number between 100 to 4000. Only valid \& for volumes of type "io1". \& \& Examples: \-block_devices => \*(Aq/dev/sdb=snap\-7eb96d16\*(Aq \& \-block_devices => \*(Aq/dev/sdc=snap\-7eb96d16:80:false\*(Aq \& \-block_devices => \*(Aq/dev/sdd=:120\*(Aq \& \-block_devices => \*(Aq/dev/sdc=:120:true:io1:500\*(Aq .Ve .Sp To provide multiple mappings, use an array reference. In this example, we launch two 'm1.small' instance in which /dev/sdb is mapped to ephemeral storage and /dev/sdc is mapped to a new 100 G \s-1EBS\s0 volume: .Sp .Vb 5 \& @i=$ec2\->run_instances(\-image_id => \*(Aqami\-12345\*(Aq, \& \-min_count => 2, \& \-block_devices => [\*(Aq/dev/sdb=ephemeral0\*(Aq, \& \*(Aq/dev/sdc=:100:true\*(Aq] \& ) .Ve .IP "Network interface syntax" 4 .IX Item "Network interface syntax" Each instance has a single primary network interface and private \s-1IP\s0 address that is ordinarily automatically assigned by Amazon. When you are running \s-1VPC\s0 instances, however, you can add additional elastic network interfaces (ENIs) to the instance and add secondary private \s-1IP\s0 addresses to one or more of these ENIs. ENIs can exist independently of instances, and be detached and reattached in much the same way as \&\s-1EBS\s0 volumes. This is explained in detail at http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/using\-instance\-addressing.html. .Sp The network configuration can be specified using the \&\-network_interface parameter: .Sp .Vb 2 \& \-network_interfaces => [\*(Aqeth0=10.10.0.12:subnet\-1234567:sg\-1234567:true:My Custom Eth0\*(Aq, \& \*(Aqeth1=10.10.1.12,10.10.1.13:subnet\-999999:sg\-1234567:true:My Custom Eth1\*(Aq] \& \& or \& \& \-network_interfaces => [\*(Aqeth0=10.10.0.12:subnet\-1234567:sg\-1234567:true:My Custom Eth0:true\*(Aq] .Ve .Sp The format is '='. The device is an ethernet interface name such as eth0, eth1, eth2, etc. The specification has up to five fields, each separated by the \*(L":\*(R" character. All fields are optional and can be left blank. If missing, \s-1AWS\s0 will choose a default. .Sp .Vb 1 \& 10.10.1.12,10.10.1.13:subnet\-999999:sg\-1234567:true:My Custom Eth1 .Ve .Sp \&\fB1. \s-1IP\s0 address(es)\fR: A single \s-1IP\s0 address in standard dot form, or a list of \s-1IP\s0 addresses separated by commas. The first address in the list will become the primary private \s-1IP\s0 address for the interface. Subsequent addresses will become secondary private addresses. You may specify \*(L"auto\*(R" or leave the field blank to have \s-1AWS\s0 choose an address automatically from within the subnetwork. To allocate several secondary \s-1IP\s0 addresses and have \s-1AWS\s0 pick the addresses automatically, give the count of secondary addresses you wish to allocate as an integer following the primary \s-1IP\s0 address. For example, \*(L"auto,3\*(R" will allocate an automatic primary \s-1IP\s0 address and three automatic secondary addresses, while \*(L"10.10.1.12,3\*(R" will force the primary address to be 10.10.1.12 and create three automatic secondary addresses. .Sp \&\fB2. Subnetwork \s-1ID\s0\fR: The \s-1ID\s0 of the \s-1VPC\s0 subnetwork in which the \s-1ENI\s0 resides. An instance may have several ENIs associated with it, and each \s-1ENI\s0 may be attached to a different subnetwork. .Sp \&\fB3. Security group IDs\fR: A comma-delimited list of the security group IDs to associate with this \s-1ENI.\s0 .Sp \&\fB4. DeleteOnTerminate\fR: True if this \s-1ENI\s0 should be automatically deleted when the instance terminates. .Sp \&\fB5. Description\fR: A human-readable description of the \s-1ENI.\s0 .Sp \&\fB6. Associate Public Address\fR: Indicates whether to assign a public \&\s-1IP\s0 address to the \s-1ENI\s0 on an instance in a \s-1VPC. \s0 Can only be specified as true when a single network interface of device index 0 is created. Defaults to true when launching in a Default \s-1VPC.\s0 .Sp As an alternative syntax, you may specify the \s-1ID\s0 of an existing \s-1ENI\s0 in lieu of the primary \s-1IP\s0 address and other fields. The \s-1ENI\s0 will be attached to the instance if its permissions allow: .Sp .Vb 1 \& \-network_interfaces => \*(Aqeth0=eni\-123456\*(Aq .Ve .IP "Return value" 4 .IX Item "Return value" On success, this method returns a list of VM::EC2::Instance objects. If called in a scalar context \s-1AND\s0 only one instance was requested, it will return a single instance object (rather than returning a list of size one which is then converted into numeric \*(L"1\*(R", as would be the usual Perl behavior). .Sp Note that this behavior is different from the Amazon \s-1API,\s0 which returns a ReservationSet. In this \s-1API,\s0 ask the instances for the the reservation, owner, requester, and group information using \&\fIreservationId()\fR, \fIownerId()\fR, \fIrequesterId()\fR and \fIgroups()\fR methods. .IP "Tips" 4 .IX Item "Tips" 1. If you have a VM::EC2::Image object returned from \fIDescribe_images()\fR, you may run it using \fIrun_instances()\fR: .Sp .Vb 5 \& my $image = $ec2\->describe_images(\-image_id => \*(Aqami\-12345\*(Aq); \& $image\->run_instances( \-min_count => 10, \& \-block_devices => [\*(Aq/dev/sdb=ephemeral0\*(Aq, \& \*(Aq/dev/sdc=:100:true\*(Aq] \& ) .Ve .Sp 2. It may take a short while for a newly-launched instance to be returned by \fIdescribe_instances()\fR. You may need to sleep for 1\-2 seconds before \fIcurrent_status()\fR returns the correct value. .Sp 3. Each instance object has a \fIcurrent_status()\fR method which will return the current run state of the instance. You may poll this method to wait until the instance is running: .Sp .Vb 5 \& my $instance = $ec2\->run_instances(...); \& sleep 1; \& while ($instance\->current_status ne \*(Aqrunning\*(Aq) { \& sleep 5; \& } .Ve .Sp 4. The utility method \fIwait_for_instances()\fR will wait until all passed instances are in the 'running' or other terminal state. .Sp .Vb 2 \& my @instances = $ec2\->run_instances(...); \& $ec2\->wait_for_instances(@instances); .Ve .ie n .SS "@s = $ec2\->start_instances(@instance_ids)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->start_instances(@instance_ids)" .IX Subsection "@s = $ec2->start_instances(@instance_ids)" .ie n .SS "@s = $ec2\->start_instances(\-instance_id=>\e@instance_ids)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->start_instances(\-instance_id=>\e@instance_ids)" .IX Subsection "@s = $ec2->start_instances(-instance_id=>@instance_ids)" Start the instances named by \f(CW@instance_ids\fR and return one or more VM::EC2::Instance::State::Change objects. .PP To wait for the all the instance ids to reach their final state (\*(L"running\*(R" unless an error occurs), call \fIwait_for_instances()\fR. .PP Example: .PP .Vb 2 \& # find all stopped instances \& @instances = $ec2\->describe_instances(\-filter=>{\*(Aqinstance\-state\-name\*(Aq=>\*(Aqstopped\*(Aq}); \& \& # start them \& $ec2\->start_instances(@instances) \& \& # pause till they are running (or crashed) \& $ec2\->wait_for_instances(@instances) .Ve .PP You can also start an instance by calling the object's \fIstart()\fR method: .PP .Vb 2 \& $instances[0]\->start(\*(Aqwait\*(Aq); # start instance and wait for it to \& # be running .Ve .PP The objects returned by calling \fIstart_instances()\fR indicate the current and previous states of the instance. The previous state is typically \&\*(L"stopped\*(R" and the current state is usually \*(L"pending.\*(R" This information is only current to the time that the \fIstart_instances()\fR method was called. To get the current run state of the instance, call its \fIstatus()\fR method: .PP .Vb 1 \& die "ouch!" unless $instances[0]\->current_status eq \*(Aqrunning\*(Aq; .Ve .ie n .SS "@s = $ec2\->stop_instances(@instance_ids)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->stop_instances(@instance_ids)" .IX Subsection "@s = $ec2->stop_instances(@instance_ids)" .ie n .SS "@s = $ec2\->stop_instances(\-instance_id=>\e@instance_ids,\-force=>1)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->stop_instances(\-instance_id=>\e@instance_ids,\-force=>1)" .IX Subsection "@s = $ec2->stop_instances(-instance_id=>@instance_ids,-force=>1)" Stop the instances named by \f(CW@instance_ids\fR and return one or more VM::EC2::Instance::State::Change objects. In the named parameter version of this method, you may optionally provide a \-force argument, which if true, forces the instance to halt without giving it a chance to run its shutdown procedure (the equivalent of pulling a physical machine's plug). .PP To wait for instances to reach their final state, call \&\fIwait_for_instances()\fR. .PP Example: .PP .Vb 2 \& # find all running instances \& @instances = $ec2\->describe_instances(\-filter=>{\*(Aqinstance\-state\-name\*(Aq=>\*(Aqrunning\*(Aq}); \& \& # stop them immediately and wait for confirmation \& $ec2\->stop_instances(\-instance_id=>\e@instances,\-force=>1); \& $ec2\->wait_for_instances(@instances); .Ve .PP You can also stop an instance by calling the object's \fIstart()\fR method: .PP .Vb 2 \& $instances[0]\->stop(\*(Aqwait\*(Aq); # stop first instance and wait for it to \& # stop completely .Ve .ie n .SS "@s = $ec2\->terminate_instances(@instance_ids)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->terminate_instances(@instance_ids)" .IX Subsection "@s = $ec2->terminate_instances(@instance_ids)" .ie n .SS "@s = $ec2\->terminate_instances(\-instance_id=>\e@instance_ids)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->terminate_instances(\-instance_id=>\e@instance_ids)" .IX Subsection "@s = $ec2->terminate_instances(-instance_id=>@instance_ids)" Terminate the instances named by \f(CW@instance_ids\fR and return one or more VM::EC2::Instance::State::Change objects. This method will fail for any instances whose termination protection field is set. .PP To wait for the all the instances to reach their final state, call \&\fIwait_for_instances()\fR. .PP Example: .PP .Vb 2 \& # find all instances tagged as "Version 0.5" \& @instances = $ec2\->describe_instances({\*(Aqtag:Version\*(Aq=>\*(Aq0.5\*(Aq}); \& \& # terminate them \& $ec2\->terminate_instances(@instances); .Ve .PP You can also terminate an instance by calling its \fIterminate()\fR method: .PP .Vb 1 \& $instances[0]\->terminate; .Ve .ie n .SS "@s = $ec2\->reboot_instances(@instance_ids)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->reboot_instances(@instance_ids)" .IX Subsection "@s = $ec2->reboot_instances(@instance_ids)" .ie n .SS "@s = $ec2\->reboot_instances(\-instance_id=>\e@instance_ids)" .el .SS "\f(CW@s\fP = \f(CW$ec2\fP\->reboot_instances(\-instance_id=>\e@instance_ids)" .IX Subsection "@s = $ec2->reboot_instances(-instance_id=>@instance_ids)" Reboot the instances named by \f(CW@instance_ids\fR and return one or more VM::EC2::Instance::State::Change objects. .PP To wait for the all the instances to reach their final state, call \&\fIwait_for_instances()\fR. .PP You can also reboot an instance by calling its \fIterminate()\fR method: .PP .Vb 1 \& $instances[0]\->reboot; .Ve .ie n .SS "$boolean = $ec2\->confirm_product_instance($instance_id,$product_code,$callback)" .el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->confirm_product_instance($instance_id,$product_code,$callback)" .IX Subsection "$boolean = $ec2->confirm_product_instance($instance_id,$product_code,$callback)" .ie n .SS "$boolean = $ec2\->confirm_product_instance(\-instance_id=>$instance_id,\-product_code=>$product_code,\-cb=>$callback)" .el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->confirm_product_instance(\-instance_id=>$instance_id,\-product_code=>$product_code,\-cb=>$callback)" .IX Subsection "$boolean = $ec2->confirm_product_instance(-instance_id=>$instance_id,-product_code=>$product_code,-cb=>$callback)" Return \*(L"true\*(R" if the instance indicated by \f(CW$instance_id\fR is associated with the given product code. .ie n .SS "$meta = \s-1VM::EC2\-\s0>instance_metadata" .el .SS "\f(CW$meta\fP = \s-1VM::EC2\-\s0>instance_metadata" .IX Subsection "$meta = VM::EC2->instance_metadata" .ie n .SS "$meta = $ec2\->instance_metadata" .el .SS "\f(CW$meta\fP = \f(CW$ec2\fP\->instance_metadata" .IX Subsection "$meta = $ec2->instance_metadata" \&\fBFor use on running \s-1EC2\s0 instances only:\fR This method returns a VM::EC2::Instance::Metadata object that will return information about the currently running instance using the \s-1HTTP://\s0 metadata fields described at http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?instancedata\-data\-categories.html. This is usually fastest way to get runtime information on the current instance. .PP Note that this method can be called as either an instance or a class method. .ie n .SS "@data = $ec2\->describe_instance_attribute($instance_id,$attribute,$callback)" .el .SS "\f(CW@data\fP = \f(CW$ec2\fP\->describe_instance_attribute($instance_id,$attribute,$callback)" .IX Subsection "@data = $ec2->describe_instance_attribute($instance_id,$attribute,$callback)" This method returns instance attributes. Only one attribute can be retrieved at a time. The following is the list of attributes that can be retrieved: .PP .Vb 10 \& instanceType \-\- scalar \& kernel \-\- scalar \& ramdisk \-\- scalar \& userData \-\- scalar \& disableApiTermination \-\- scalar \& instanceInitiatedShutdownBehavior \-\- scalar \& rootDeviceName \-\- scalar \& blockDeviceMapping \-\- list of hashref \& sourceDestCheck \-\- scalar \& groupSet \-\- list of scalar \& productCodes \-\- list of hashref \& ebsOptimized \-\- scalar \& sriovNetSupport \-\- scalar .Ve .PP All of these values can be retrieved more conveniently from the VM::EC2::Instance object returned from \fIdescribe_instances()\fR, so there is no attempt to parse the results of this call into Perl objects. Therefore, some of the attributes, in particular \&'blockDeviceMapping' will be returned as raw hashrefs. .ie n .SS "$boolean = $ec2\->modify_instance_attribute($instance_id,\-$attribute_name=>$value)" .el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->modify_instance_attribute($instance_id,\-$attribute_name=>$value)" .IX Subsection "$boolean = $ec2->modify_instance_attribute($instance_id,-$attribute_name=>$value)" This method changes instance attributes. It can only be applied to stopped instances. The following is the list of attributes that can be set: .PP .Vb 10 \& \-instance_type \-\- type of instance, e.g. "m1.small" \& \-kernel \-\- kernel id \& \-ramdisk \-\- ramdisk id \& \-user_data \-\- user data \& \-termination_protection \-\- true to prevent termination from the console \& \-disable_api_termination \-\- same as the above \& \-shutdown_behavior \-\- "stop" or "terminate" \& \-instance_initiated_shutdown_behavior \-\- same as above \& \-root_device_name \-\- root device name \& \-source_dest_check \-\- enable NAT (VPC only) \& \-group_id \-\- VPC security group \& \-block_devices \-\- Specify block devices to change \& deleteOnTermination flag \& \-block_device_mapping \-\- Alias for \-block_devices \& \-ebs_optimization \-\- EBS Optimization \& \-sriov_net_support \-\- Enhanced networking support .Ve .PP Only one attribute can be changed in a single request. For example: .PP .Vb 1 \& $ec2\->modify_instance_attribute(\*(Aqi\-12345\*(Aq,\-kernel=>\*(Aqaki\-f70657b2\*(Aq); .Ve .PP The result code is true if the attribute was successfully modified, false otherwise. In the latter case, \f(CW$ec2\fR\->\fIerror()\fR will provide the error message. .PP The ability to change the deleteOnTermination flag for attached block devices is not documented in the official Amazon \s-1API\s0 documentation, but appears to work. The syntax is: .PP # turn on deleteOnTermination \f(CW$ec2\fR\->modify_instance_attribute(\-block_devices=>'/dev/sdf=v\-12345') # turn off deleteOnTermination \f(CW$ec2\fR\->modify_instance_attribute(\-block_devices=>'/dev/sdf=v\-12345') .PP The syntax is slightly different from what is used by \-block_devices in \fIrun_instances()\fR, and is \*(L"device=volumeId:boolean\*(R". Multiple block devices can be specified using an arrayref. .ie n .SS "$boolean = $ec2\->reset_instance_attribute($instance_id,$attribute [,$callback])" .el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->reset_instance_attribute($instance_id,$attribute [,$callback])" .IX Subsection "$boolean = $ec2->reset_instance_attribute($instance_id,$attribute [,$callback])" This method resets an attribute of the given instance to its default value. Valid attributes are \*(L"kernel\*(R", \*(L"ramdisk\*(R" and \&\*(L"sourceDestCheck\*(R". The result code is true if the reset was successful. .ie n .SS "@status_list = $ec2\->describe_instance_status(@instance_ids);" .el .SS "\f(CW@status_list\fP = \f(CW$ec2\fP\->describe_instance_status(@instance_ids);" .IX Subsection "@status_list = $ec2->describe_instance_status(@instance_ids);" .ie n .SS "@status_list = $ec2\->describe_instance_status(\-instance_id=>\e@ids,\-filter=>\e%filters,%other_args);" .el .SS "\f(CW@status_list\fP = \f(CW$ec2\fP\->describe_instance_status(\-instance_id=>\e@ids,\-filter=>\e%filters,%other_args);" .IX Subsection "@status_list = $ec2->describe_instance_status(-instance_id=>@ids,-filter=>%filters,%other_args);" .ie n .SS "@status_list = $ec2\->describe_instance_status(\e%filters);" .el .SS "\f(CW@status_list\fP = \f(CW$ec2\fP\->describe_instance_status(\e%filters);" .IX Subsection "@status_list = $ec2->describe_instance_status(%filters);" This method returns a list of VM::EC2::Instance::Status objects corresponding to status checks and scheduled maintenance events on the instances of interest. You may provide a list of instances to return information on, a set of filters, or both. .PP The filters are described at http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference\-query\-DescribeInstanceStatus.html. The brief list is: .PP availability-zone, event.code, event.description, event.not\-after, event.not\-before, instance-state-name, instance-state-code, system\-status.status, system\-status.reachability, instance\-status.status, instance\-status.reachability. .PP Request arguments are: .PP .Vb 2 \& \-instance_id Scalar or array ref containing the instance ID(s) to return \& information about (optional). \& \& \-filter Filters to apply (optional). \& \& \-include_all_instances If true, include all instances, including those that are \& stopped, pending and shutting down. Otherwise, returns \& the status of running instances only. \& \& \-max_results An integer corresponding to the number of instance items \& per response (must be greater than 5). .Ve .PP If \-max_results is specified, then the call will return at most the number of instances you requested. You may see whether there are additional results by calling \fImore_instance_status()\fR, and then retrieve the next set of results with additional call(s) to \fIdescribe_instance_status()\fR: .PP .Vb 6 \& my @results = $ec2\->describe_instance_status(\-max_results => 10); \& do_something(\e@results); \& while ($ec2\->more_instance_status) { \& @results = $ec2\->describe_instance_status; \& do_something(\e@results); \& } .Ve .PP \&\s-1NOTE:\s0 As of 29 July 2012, passing \-include_all_instances causes an \s-1EC2 \&\s0\*(L"unknown parameter\*(R" error, indicating some mismatch between the documented \s-1API\s0 and the actual one. .ie n .SS "$t = $ec2\->token" .el .SS "\f(CW$t\fP = \f(CW$ec2\fP\->token" .IX Subsection "$t = $ec2->token" Return a client token for use with \fIstart_instances()\fR. .ie n .SS "$ec2\->wait_for_instances(@instances)" .el .SS "\f(CW$ec2\fP\->wait_for_instances(@instances)" .IX Subsection "$ec2->wait_for_instances(@instances)" Wait for all members of the provided list of instances to reach some terminal state (\*(L"running\*(R", \*(L"stopped\*(R" or \*(L"terminated\*(R"), and then return a hash reference that maps each instance \s-1ID\s0 to its final state. .PP Typical usage: .PP .Vb 8 \& my @instances = $image\->run_instances(\-key_name =>\*(AqMy_key\*(Aq, \& \-security_group=>\*(Aqdefault\*(Aq, \& \-min_count =>2, \& \-instance_type => \*(Aqt1.micro\*(Aq) \& or die $ec2\->error_str; \& my $status = $ec2\->wait_for_instances(@instances); \& my @failed = grep {$status\->{$_} ne \*(Aqrunning\*(Aq} @instances; \& print "The following failed: @failed\en"; .Ve .PP If no terminal state is reached within a set timeout, then this method returns undef and sets \f(CW$ec2\fR\->\fIerror_str()\fR to a suitable message. The timeout, which defaults to 10 minutes (600 seconds), can be get or set with \f(CW$ec2\fR\->\fIwait_for_timeout()\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1VM::EC2\s0 .SH "AUTHOR" .IX Header "AUTHOR" Lincoln Stein . .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.