1VM::EC2::Instance(3pm)User Contributed Perl DocumentationVM::EC2::Instance(3pm)
2
6 VM::EC2::Instance - Object describing an Amazon EC2 instance
7
9 use VM::EC2;
10 $ec2 = VM::EC2->new(...);
12 $instance = $ec2->describe_instances(-instance_id=>'i-12345');
13 $instanceId = $instance->instanceId;
15 $ownerId = $instance->ownerId;
16 $reservationId = $instance->reservationId;
17 $imageId = $instance->imageId;
18 $state = $instance->instanceState;
19 @groups = $instance->groups;
20 $private_ip = $instance->privateIpAddress;
21 $public_ip = $instance->ipAddress;
22 $private_dns = $instance->privateDnsName;
23 $public_dns = $instance->dnsName;
24 $time = $instance->launchTime;
25 $status = $instance->current_status;
26 $tags = $instance->tags;
27 $stateChange = $instance->start();
29 $stateChange = $instance->stop();
30 $stateChange = $instance->reboot();
31 $stateChange = $instance->terminate();
32 $seconds = $instance->up_time;
34
36 This object represents an Amazon EC2 instance, and is returned by
37 VM::EC2->describe_instances(). In addition to methods to query the
38 instance's attributes, there are methods that allow you to manage the
39 instance's lifecycle, including start, stopping, and terminating it.
40 Note that the information about security groups and reservations that
42 is returned by describe_instances() is copied into each instance before
43 returning it, so there is no concept of a "reservation set" in this
44 interface.
45
47 These object methods are supported:
48 instanceId -- ID of this instance.
50 imageId -- ID of the image used to launch this instance.
52 instanceState -- The current state of the instance at the time
54 that describe_instances() was called, as a
55 VM::EC2::Instance::State object. Also
56 see the status() method, which re-queries EC2 for
57 the current state of the instance. States are
58 represented in strings as "terminated", "running",
59 "stopped", "stopping",and "shutting-down".
60 privateDnsName -- The private DNS name assigned to the instance within
62 Amazon's EC2 network. This element is defined only
63 for running instances.
64 dnsName -- The public DNS name assigned to the instance, defined
66 only for running instances.
67 reason -- Reason for the most recent state transition,
69 if applicable.
70 keyName -- Name of the associated key pair, if applicable.
72 keyPair -- The VM::EC2::KeyPair object, derived from the keyName
74 amiLaunchIndex -- The AMI launch index, which can be used to find
76 this instance within the launch group.
77 productCodes -- A list of product codes that apply to this instance.
79 instanceType -- The instance type, such as "t1.micro". CHANGEABLE.
81 launchTime -- The time the instance launched.
83 placement -- The placement of the instance. Returns a
85 VM::EC2::Instance::Placement object, which when used
86 as a string is equal to the instance's
87 availability zone.
88 availabilityZone -- Same as placement.
90 kernelId -- ID of the instance's kernel. CHANGEABLE.
92 ramdiskId -- ID of the instance's RAM disk. CHANGEABLE.
94 platform -- Platform of the instance, either "windows" or empty.
96 monitoring -- State of monitoring for the instance. One of
98 "disabled", "enabled", or "pending". CHANGEABLE:
99 pass true or "enabled" to turn on monitoring. Pass
100 false or "disabled" to turn it off.
101 subnetId -- The Amazon VPC subnet ID in which the instance is
103 running, for Virtual Private Cloud instances only.
104 vpcId -- The Virtual Private Cloud ID for VPC instances.
106 privateIpAddress -- The private (internal Amazon) IP address assigned
108 to the instance.
109 ipAddress -- The public IP address of the instance.
111 sourceDestCheck -- Whether source destination checking is enabled on
113 this instance. This returns a Perl boolean rather than
114 the string "true". This method is used in conjunction
115 with VPC NAT functionality. See the Amazon VPC User
116 Guide for details. CHANGEABLE.
117 networkInterfaceSet -- Return list of VM::EC2::ElasticNetworkInterface objects
119 attached to this instance.
120 iamInstanceProfile -- The IAM instance profile (IIP) associated with this instance.
122 ebsOptimized -- True if instance is optimized for EBS I/O.
124 groupSet -- List of VM::EC2::Group objects indicating the VPC
126 security groups in which this instance resides. Not to be
127 confused with groups(), which returns the security groups
128 of non-VPC instances.
129 stateReason -- A VM::EC2::Instance::State::Reason object which
131 indicates the reason for the instance's most recent
132 state change. See http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-ItemType-StateReasonType.html
133 architecture -- The architecture of the image. Either "i386" or "x86_64".
135 rootDeviceType -- The type of the root device used by the instance. One of "ebs"
137 or "instance-store".
138 rootDeviceName -- The name of the the device used by the instance, such as /dev/sda1.
140 CHANGEABLE.
141 blockDeviceMapping -- The block device mappings for the instance, represented
143 as a list of L<VM::EC2::BlockDevice::Mapping> objects.
144 instanceLifeCycle -- "spot" if this instance is a spot instance, otherwise empty.
146 spotInstanceRequestId -- The ID of the spot instance request, if applicable.
148 virtualizationType -- Either "paravirtual" or "hvm".
150 clientToken -- The idempotency token provided at the time of the AMI launch,
152 if any.
153 hypervisor -- The instance's hypervisor type, either "ovm" or "xen".
155 userData -- User data passed to instance at launch. CHANGEABLE.
157 disableApiTermination -- True if the instance is protected from termination
159 via the console or command-line APIs. CHANGEABLE.
160 instanceInitiatedShutdownBehavior -- Action to take when the instance calls
162 shutdown or halt. One of "stop" or "terminate". CHANGEABLE.
163 sriovNetSupport -- Specifies whether enhanced networking is enabled. "simple" if so.
165 tagSet -- Tags for the instance as a hashref. CHANGEABLE via add_tags()
167 and delete_tags().
168 The object also supports the tags() method described in
170 VM::EC2::Generic:
171 print "ready for production\n" if $image->tags->{Released};
173 All methods return read-only values except for those marked CHANGEABLE
175 in the list above. For these, you can change the instance attribute on
176 stopped instances by invoking the method with an appropriate new value.
177 For example, to change the instance type from "t1.micro" to "m1.small",
178 you can do this:
179 my @tiny_instances = $ec2->describe_instances(-filter=>{'instance-type'=>'t1.micro'});
181 for my $i (@tiny_instances) {
182 next unless $i->instanceState eq 'stopped';
183 $i->instanceType('m1.small') or die $ec2->error;
184 }
185 When you attempt to change an attribute of an instance, the method will
187 return true on success, false on failure. On failure, the detailed
188 error messages can be recovered from the VM::EC2 object's error()
189 method.
190
192 In addition, the following convenience functions are provided
193 $state = $instance->current_status
195 This method queries AWS for the instance's current state and returns it
196 as a VM::EC2::Instance::State object. This enables you to poll the
197 instance until it is in the desired state:
198 while ($instance->current_status eq 'pending') { sleep 5 }
200 $state = $instance->current_state
202 An alias for current_status().
203 $state_change = $instance->start([$wait])
205 This method will start the current instance and returns a
206 VM::EC2::Instance::State::Change object that can be used to monitor the
207 status of the instance. By default the method returns immediately, but
208 you can pass a true value as an argument in order to pause execution
209 until the instance is in the "running" state.
210 Here's a polling example:
212 $state = $instance->start;
214 while ($state->status eq 'pending') { sleep 5 }
215 Here's an example that will pause until the instance is running:
217 $instance->start(1);
219 Attempting to start an already running instance, or one that is in
221 transition, will throw a fatal error.
222 $state_change = $instance->stop([$wait])
224 This method is similar to start(), except that it can be used to stop a
225 running instance.
226 $state_change = $instance->terminate([$wait])
228 This method is similar to start(), except that it can be used to
229 terminate an instance. It can only be called on instances that are
230 either "running" or "stopped".
231 $state_change = $instance->reboot()
233 Reboot the instance. Rebooting doesn't occur immediately; instead the
234 request is queued by the Amazon system and may be satisfied several
235 minutes later. For this reason, there is no "wait" argument.
236 $seconds = $instance->up_time()
238 Return the number of seconds since the instance was launched. Note that
239 this includes time that the instance was either in the "running" or
240 "stopped" state.
241 $result = $instance->associate_address($elastic_address)
243 Associate an elastic address with this instance. If you are associating
244 a VPC elastic IP address with the instance, the result code will
245 indicate the associationId. Otherwise it will be a simple perl truth
246 value ("1") if successful, undef if false.
247 In the case of an ordinary EC2 Elastic IP address, the first argument
249 may either be an ordinary string (xx.xx.xx.xx format) or a
250 VM::EC2::ElasticAddress object. However, if it is a VPC elastic IP
251 address, then the argument must be a VM::EC2::ElasticAddress as
252 returned by describe_addresses(). The reason for this is that the
253 allocationId must be retrieved from the object in order to use in the
254 call.
255 $bool = $instance->disassociate_address
257 Disassociate an elastic IP address from this instance. if any. The
258 result will be true if disassociation was successful. Note that for a
259 short period of time (up to a few minutes) after disassociation, the
260 instance will have no public IP address and will be unreachable from
261 the internet.
262 @list = $instance->network_interfaces
264 Return the network interfaces attached to this instance as a set of
265 VM::EC2::NetworkInterface objects (VPC only).
266 $instance->refresh
268 This method will refresh the object from AWS, updating all values to
269 their current ones. You can call it after starting an instance in order
270 to get its IP address. Note that refresh() is called automatically for
271 you if you call start(), stop() or terminate() with a true $wait
272 argument.
273 $text = $instance->console_output
275 Return the console output of the instance as a VM::EC2::ConsoleOutput
276 object. This object can be treated as a string, or as an object with
277 methods
278
280 The create_image() method provides a handy way of creating and
281 registering an AMI based on the current state of the instance. All
282 currently-associated block devices will be snapshotted and associated
283 with the image.
284 Note that this operation can take a long time to complete. You may
286 follow its progress by calling the returned image object's
287 current_status() method.
288 $imageId = $instance->create_image($name [,$description])
290 $imageId =
291 $instance->create_image(-name=>$name,-description=>$description,-no_reboot=>$boolean)
292 Create an image from this instance and return a VM::EC2::Image object.
293 The instance must be in the "stopped" or "running" state. In the latter
294 case, Amazon will stop the instance, create the image, and then restart
295 it unless the -no_reboot argument is provided.
296 Arguments:
298 -name Name for the image that will be created. (required)
300 -description Description of the new image.
301 -no_reboot If true, don't reboot the instance.
302 In the unnamed argument version you can provide the name and optionally
304 the description of the resulting image.
305 $boolean = $instance->confirm_product_code($product_code)
307 Return true if this instance is associated with the given product code.
308
310 $attachment = $instance->attach_volume($volume_id,$device)
311 $attachment =
312 $instance->attach_volume(-volume_id=>$volume_id,-device=>$device)
313 Attach volume $volume_id to this instance using virtual device $device.
314 Both arguments are required. The result is a
315 VM::EC2::BlockDevice::Attachment object which you can monitor by
316 calling current_status():
317 my $a = $instance->attach_volume('vol-12345'=>'/dev/sdg');
319 while ($a->current_status ne 'attached') {
320 sleep 2;
321 }
322 print "volume is ready to go\n";
323 $attachment = $instance->detach_volume($vol_or_device)
325 $attachment = $instance->detach_volume(-volume_id => $volume_id -device
326 => $device, -force => $force);
327 Detaches the specified volume. In the single-argument form, you may
328 provide either a volume or a device name. In the named-argument form,
329 you may provide both the volume and the device as a check that you are
330 detaching exactly the volume you think you are.
331 Optional arguments:
333 -volume_id -- ID of the instance to detach from.
335 -device -- How the device is exposed to the instance.
336 -force -- Force detachment, even if previous attempts were
337 unsuccessful.
338 The result is a VM::EC2::BlockDevice::Attachment object which you can
340 monitor by calling current_status():
341 my $a = $instance->detach_volume('/dev/sdg');
343 while ($a->current_status ne 'detached') {
344 sleep 2;
345 }
346 print "volume is ready to go\n";
347
349 $attachment_id = $instance->attach_network_interface($interface_id =>
350 $device)
351 $attachment_id =
352 $instance->attach_network_interface(-network_interface_id=>$id,
353 -device_index => $device)
354 This method attaches a network interface to the current instance using
355 the indicated device index. You can use either an elastic network
356 interface ID, or a VM::EC2::NetworkInterface object. You may use an
357 integer for -device_index, or use the strings "eth0", "eth1" etc.
358 Required arguments:
360 -network_interface_id ID of the network interface to attach.
362 -device_index Network device number to use (e.g. 0 for eth0).
363 On success, this method returns the attachmentId of the new attachment
365 (not a VM::EC2::NetworkInterface::Attachment object, due to an AWS API
366 inconsistency).
367 $boolean = $instance->detach_network_interface($interface_id [,$force])
369 This method detaches a network interface from the current instance. If
370 a true second argument is provided, then the detachment will be forced,
371 even if the interface is in use.
372 On success, this method returns a true value.
374
376 $meta = $instance->metadata
377 For use on running EC2 instances only: This method returns a
378 VM::EC2::Instance::Metadata object that will return information about
379 the currently running instance using the HTTP:// metadata fields
380 described at
381 http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?instancedata-data-categories.html.
382 This is usually fastest way to get runtime information on the current
383 instance.
384
386 When used in a string context, this object will interpolate the
387 instanceId.
388
390 VM::EC2 VM::EC2::Generic VM::EC2::BlockDevice VM::EC2::Instance::State
391 VM::EC2::Instance::State::Reason VM::EC2::Instance::Metadata
392 VM::EC2::Instance::Placement VM::EC2::Tag
393
395 Lincoln Stein <lincoln.stein@gmail.com>.
396 Copyright (c) 2011 Ontario Institute for Cancer Research
398 This package and its accompanying libraries is free software; you can
400 redistribute it and/or modify it under the terms of the GPL (either
401 version 1, or at your option, any later version) or the Artistic
402 License 2.0. Refer to LICENSE for the full license text. In addition,
403 please see DISCLAIMER.txt for disclaimers of warranty.
404perl v5.38.0 2023-07-21 VM::EC2::Instance(3pm)