1VM::EC2(3) User Contributed Perl Documentation VM::EC2(3)
2
6 VM::EC2 - Perl interface to Amazon EC2, Virtual Private Cloud, Elastic
7 Load Balancing, Autoscaling, and Relational Database services
8
10 NOTE: For information on AWS's VPC, load balancing, autoscaling and
11 relational databases services, see VM::EC2::VPC, VM::EC2::ELB,
12 VM::EC2::REST::autoscaling, and
13 VM::EC2::REST::relational_database_service
14 # set environment variables EC2_ACCESS_KEY, EC2_SECRET_KEY and/or EC2_URL
16 # to fill in arguments automatically
17 ## IMAGE AND INSTANCE MANAGEMENT
19 # get new EC2 object
20 my $ec2 = VM::EC2->new(-access_key => 'access key id',
21 -secret_key => 'aws_secret_key',
22 -endpoint => 'http://ec2.amazonaws.com');
23 # fetch an image by its ID
25 my $image = $ec2->describe_images('ami-12345');
26 # get some information about the image
28 my $architecture = $image->architecture;
29 my $description = $image->description;
30 my @devices = $image->blockDeviceMapping;
31 for my $d (@devices) {
32 print $d->deviceName,"\n";
33 print $d->snapshotId,"\n";
34 print $d->volumeSize,"\n";
35 }
36 # run two instances
38 my @instances = $image->run_instances(-key_name =>'My_key',
39 -security_group=>'default',
40 -min_count =>2,
41 -instance_type => 't1.micro')
42 or die $ec2->error_str;
43 # wait for both instances to reach "running" or other terminal state
45 $ec2->wait_for_instances(@instances);
46 # print out both instance's current state and DNS name
48 for my $i (@instances) {
49 my $status = $i->current_status;
50 my $dns = $i->dnsName;
51 print "$i: [$status] $dns\n";
52 }
53 # tag both instances with Role "server"
55 foreach (@instances) {$_->add_tag(Role=>'server');
56 # stop both instances
58 foreach (@instances) {$_->stop}
59 # find instances tagged with Role=Server that are
61 # stopped, change the user data and restart.
62 @instances = $ec2->describe_instances({'tag:Role' => 'Server',
63 'instance-state-name' => 'stopped'});
64 for my $i (@instances) {
65 $i->userData('Secure-mode: off');
66 $i->start or warn "Couldn't start $i: ",$i->error_str;
67 }
68 # create an image from both instance, tag them, and make
70 # them public
71 for my $i (@instances) {
72 my $img = $i->create_image("Autoimage from $i","Test image");
73 $img->add_tags(Name => "Autoimage from $i",
74 Role => 'Server',
75 Status=> 'Production');
76 $img->make_public(1);
77 }
78 ## KEY MANAGEMENT
80 # retrieve the name and fingerprint of the first instance's
82 # key pair
83 my $kp = $instances[0]->keyPair;
84 print $instances[0], ": keypair $kp=",$kp->fingerprint,"\n";
85 # create a new key pair
87 $kp = $ec2->create_key_pair('My Key');
88 # get the private key from this key pair and write it to a disk file
90 # in ssh-compatible format
91 my $private_key = $kp->private_key;
92 open (my $f,'>MyKeypair.rsa') or die $!;
93 print $f $private_key;
94 close $f;
95 # Import a preexisting SSH key
97 my $public_key = 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC8o...';
98 $key = $ec2->import_key_pair('NewKey',$public_key);
99 ## SECURITY GROUPS AND FIREWALL RULES
101 # Create a new security group
102 my $group = $ec2->create_security_group(-name => 'NewGroup',
103 -description => 'example');
104 # Add a firewall rule
106 $group->authorize_incoming(-protocol => 'tcp',
107 -port => 80,
108 -source_ip => ['192.168.2.0/24','192.168.2.1/24'});
109 # Write rules back to Amazon
111 $group->update;
112 # Print current firewall rules
114 print join ("\n",$group->ipPermissions),"\n";
115 ## VOLUME && SNAPSHOT MANAGEMENT
117 # find existing volumes that are available
119 my @volumes = $ec2->describe_volumes({status=>'available'});
120 # back 'em all up to snapshots
122 foreach (@volumes) {$_->snapshot('Backup on '.localtime)}
123 # find a stopped instance in first volume's availability zone and
125 # attach the volume to the instance using /dev/sdg
126 my $vol = $volumes[0];
127 my $zone = $vol->availabilityZone;
128 @instances = $ec2->describe_instances({'availability-zone'=> $zone,
129 'run-state-name' => $stopped);
130 $instances[0]->attach_volume($vol=>'/dev/sdg') if @instances;
131 # create a new 20 gig volume
133 $vol = $ec2->create_volume(-availability_zone=> 'us-east-1a',
134 -size => 20);
135 $ec2->wait_for_volumes($vol);
136 print "Volume $vol is ready!\n" if $vol->current_status eq 'available';
137 # create a new elastic address and associate it with an instance
139 my $address = $ec2->allocate_address();
140 $instances[0]->associate_address($address);
141
143 This is an interface to the 2014-05-01 version of the Amazon AWS API
144 (http://aws.amazon.com/ec2). It was written provide access to the new
145 tag and metadata interface that is not currently supported by
146 Net::Amazon::EC2, as well as to provide developers with an extension
147 mechanism for the API. This library will also support the Open Stack
148 open source cloud (http://www.openstack.org/).
149 The main interface is the VM::EC2 object, which provides methods for
151 interrogating the Amazon EC2, launching instances, and managing
152 instance lifecycle. These methods return the following major object
153 classes which act as specialized interfaces to AWS:
154 VM::EC2::BlockDevice -- A block device
156 VM::EC2::BlockDevice::Attachment -- Attachment of a block device to an EC2 instance
157 VM::EC2::BlockDevice::EBS -- An elastic block device
158 VM::EC2::BlockDevice::Mapping -- Mapping of a virtual storage device to a block device
159 VM::EC2::BlockDevice::Mapping::EBS -- Mapping of a virtual storage device to an EBS block device
160 VM::EC2::Group -- Security groups
161 VM::EC2::Image -- Amazon Machine Images (AMIs)
162 VM::EC2::Instance -- Virtual machine instances
163 VM::EC2::Instance::Metadata -- Access to runtime metadata from running instances
164 VM::EC2::Region -- Availability regions
165 VM::EC2::Snapshot -- EBS snapshots
166 VM::EC2::Tag -- Metadata tags
167 In addition, there is a high level interface for interacting with EC2
169 servers and volumes, including file transfer and remote shell
170 facilities:
171 VM::EC2::Staging::Manager -- Manage a set of servers and volumes.
173 VM::EC2::Staging::Server -- A staging server, with remote shell and file transfer
174 facilities.
175 VM::EC2::Staging::Volume -- A staging volume with the ability to copy itself between
176 availability zones and regions.
177 and a few specialty classes:
179 VM::EC2::Security::Token -- Temporary security tokens for granting EC2 access to
181 non-AWS account holders.
182 VM::EC2::Security::Credentials -- Credentials for use by temporary account holders.
183 VM::EC2::Security::Policy -- Policies that restrict what temporary account holders
184 can do with EC2 resources.
185 VM::EC2::Security::FederatedUser -- Account name information for temporary account holders.
186 Lastly, there are several utility classes:
188 VM::EC2::Generic -- Base class for all AWS objects
190 VM::EC2::Error -- Error messages
191 VM::EC2::Dispatch -- Maps AWS XML responses onto perl object classes
192 VM::EC2::ReservationSet -- Hidden class used for describe_instances() request;
193 The reservation Ids are copied into the Instance
194 object.
195 There is also a high-level API called "VM::EC2::Staging::Manager" for
197 managing groups of staging servers and volumes which greatly simplifies
198 the task of creating and updating instances that mount multiple
199 volumes. The API also provides a one-line command for migrating EBS-
200 backed AMIs from one zone to another. See VM::EC2::Staging::Manager.
201 The interface provided by these modules is based on that described at
203 http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/. The
204 following caveats apply:
205 1) Not all of the Amazon API is currently implemented. Specifically,
207 a handful calls dealing with cluster management and VM importing
208 are missing. See L</MISSING METHODS> for a list of all the
209 unimplemented API calls. Volunteers to fill in these gaps are
210 most welcome!
211 2) For consistency with common Perl coding practices, method calls
213 are lowercase and words in long method names are separated by
214 underscores. The Amazon API prefers mixed case. So in the Amazon
215 API the call to fetch instance information is "DescribeInstances",
216 while in VM::EC2, the method is "describe_instances". To avoid
217 annoyance, if you use the mixed case form for a method name, the
218 Perl autoloader will automatically translate it to underscores for
219 you, and vice-versa; this means you can call either
220 $ec2->describe_instances() or $ec2->DescribeInstances().
221 3) Named arguments passed to methods are all lowercase, use
223 underscores to separate words and start with hyphens.
224 In other words, if the AWS API calls for an argument named
225 "InstanceId" to be passed to the "DescribeInstances" call, then
226 the corresponding Perl function will look like:
227 $instance = $ec2->describe_instances(-instance_id=>'i-12345')
229 In most cases automatic case translation will be performed for you
231 on arguments. So in the previous example, you could use
232 -InstanceId as well as -instance_id. The exception
233 is when an absurdly long argument name was replaced with an
234 abbreviated one as described below. In this case, you must use
235 the documented argument name.
236 In a small number of cases, when the parameter name was absurdly
238 long, it has been abbreviated. For example, the
239 "Placement.AvailabilityZone" parameter has been represented as
240 -placement_zone and not -placement_availability_zone. See the
241 documentation for these cases.
242 4) For each of the describe_foo() methods (where "foo" is a type of
244 resource such as "instance"), you can fetch the resource by using
245 their IDs either with the long form:
246 $ec2->describe_foo(-foo_id=>['a','b','c']),
248 or a shortcut form:
250 $ec2->describe_foo('a','b','c');
252 Both forms are listed in the headings in the documentation.
254 5) When the API calls for a list of arguments named Arg.1, Arg.2,
256 then the Perl interface allows you to use an anonymous array for
257 the consecutive values. For example to call describe_instances()
258 with multiple instance IDs, use:
259 @i = $ec2->describe_instances(-instance_id=>['i-12345','i-87654'])
261 6) All Filter arguments are represented as a -filter argument whose value is
263 an anonymous hash:
264 @i = $ec2->describe_instances(-filter=>{architecture=>'i386',
266 'tag:Name' =>'WebServer'})
267 If there are no other arguments you wish to pass, you can omit the
269 -filter argument and just pass a hashref:
270 @i = $ec2->describe_instances({architecture=>'i386',
272 'tag:Name' =>'WebServer'})
273 For any filter, you may represent multiple OR arguments as an arrayref:
275 @i = $ec2->describe-instances({'instance-state-name'=>['stopped','terminated']})
277 When adding or removing tags, the -tag argument uses the same syntax.
279 7) The tagnames of each XML object returned from AWS are converted into methods
281 with the same name and typography. So the <privateIpAddress> tag in a
282 DescribeInstancesResponse, becomes:
283 $instance->privateIpAddress
285 You can also use the more Perlish form -- this is equivalent:
287 $instance->private_ip_address
289 Methods that correspond to complex objects in the XML hierarchy
291 return the appropriate Perl object. For example, an instance's
292 blockDeviceMapping() method returns an object of type
293 VM::EC2::BlockDevice::Mapping.
294 All objects have a fields() method that will return the XML
296 tagnames listed in the AWS specifications.
297 @fields = sort $instance->fields;
299 # 'amiLaunchIndex', 'architecture', 'blockDeviceMapping', ...
300 8) Whenever an object has a unique ID, string overloading is used so that
302 the object interpolates the ID into the string. For example, when you
303 print a VM::EC2::Volume object, or use it in another string context,
304 then it will appear as the string "vol-123456". Nevertheless, it will
305 continue to be usable for method calls.
306 ($v) = $ec2->describe_volumes();
308 print $v,"\n"; # prints as "vol-123456"
309 $zone = $v->availabilityZone; # acts like an object
310 9) Many objects have convenience methods that invoke the AWS API on your
312 behalf. For example, instance objects have a current_status() method that returns
313 the run status of the object, as well as start(), stop() and terminate()
314 methods that control the instance's lifecycle.
315 if ($instance->current_status eq 'running') {
317 $instance->stop;
318 }
319 10) Calls to AWS that have failed for one reason or another (invalid
321 arguments, communications problems, service interruptions) will
322 return undef and set the VM::EC2->is_error() method to true. The
323 error message and its code can then be recovered by calling
324 VM::EC2->error.
325 $i = $ec2->describe_instance('i-123456');
327 unless ($i) {
328 warn 'Got no instance. Message was: ',$ec2->error;
329 }
330 You may also elect to raise an exception when an error occurs.
332 See the new() method for details.
333
335 As of version 1.24, VM::EC2 supports asynchronous calls to AWS using
336 AnyEvent::HTTP. This allows you to make multiple calls in parallel for
337 a significant improvement in performance.
338 In asynchronous mode, VM::EC2 calls that ordinarily wait for AWS to
340 respond and then return objects corresponding to EC2 instances,
341 volumes, images, and so forth, will instead immediately return an
342 AnyEvent condition variable. You can retrieve the result of the call by
343 calling the condition variable's recv() method, or by setting a
344 callback to be executed when the call is complete.
345 To make an asynchronous call, you can set the global variable
347 $VM::EC2::ASYNC to a true value
348 Here is an example of a normal synchronous call:
350 my @instances = $ec2->describe_instances();
352 Here is the asynchronous version initiated after setting
354 $VM::EC2::ASYNC (using a local block to limit its effects).
355 {
357 local $VM::EC2::ASYNC=1;
358 my $cv = $ec2->describe_instances(); # returns immediately
359 my @instances = $cv->recv;
360 }
361 In case of an error recv() will return undef and the error object can
363 be recovered using the condition variable's error() method (this is an
364 enhancement over AnyEvent's standard condition variable class):
365 my @instances = $cv->recv
367 or die "No instances found! error = ",$cv->error();
368 You may attach a callback CODE reference to the condition variable
370 using its cb() method, in which case the callback will be invoked when
371 the APi call is complete. The callback will be invoked with a single
372 argument consisting of the condition variable. Ordinarily you will call
373 recv() on the variable and then do something with the result:
374 {
376 local $VM::EC2::ASYNC=1;
377 my $cv = $ec2->describe_instances();
378 $cv->cb(sub {my $v = shift;
379 my @i = $v->recv;
380 print "instances = @i\n";
381 });
382 }
383 For callbacks to be invoked, someone must be run an event loop using
385 one of the event frameworks that AnyEvent supports (e.g. Coro, Tk or
386 Gtk). Alternately, you may simply run:
387 AnyEvent->condvar->recv();
389 If $VM::EC2::ASYNC is false, you can issue a single asynchronous call
391 by appending "_async" to the name of the method call. Similarly, if
392 $VM::EC2::ASYNC is true, you can make a single normal synchrous call by
393 appending "_sync" to the method name.
394 For example, this is equivalent to the above:
396 my $cv = $ec2->describe_instances_async(); # returns immediately
398 my @instances = $cv->recv;
399 You may stack multiple asynchronous calls on top of one another. When
401 you call recv() on any of the returned condition variables, they will
402 all run in parallel. Hence the three calls will take no longer than the
403 longest individual one:
404 my $cv1 = $ec2->describe_instances_async({'instance-state-name'=>'running'});
406 my $cv2 = $ec2->describe_instances_async({'instance-state-name'=>'stopped'});
407 my @running = $cv1->recv;
408 my @stopped = $cv2->recv;
409 Same thing with callbacks:
411 my (@running,@stopped);
413 my $cv1 = $ec2->describe_instances_async({'instance-state-name'=>'running'});
414 $cv1->cb(sub {@running = shift->recv});
415 my $cv2 = $ec2->describe_instances_async({'instance-state-name'=>'stopped'});
417 $cv1->cb(sub {@stopped = shift->recv});
418 AnyEvent->condvar->recv;
420 And here it is using a group conditional variable to block until all
422 pending describe_instances() requests have completed:
423 my %instances;
425 my $group = AnyEvent->condvar;
426 $group->begin;
427 for my $state (qw(pending running stopping stopped)) {
428 $group->begin;
429 my $cv = $ec2->describe_instances_async({'instance-state-name'=>$state});
430 $cv->cb(sub {my @i = shift->recv;
431 $instances{$state}=\@i;
432 $group->end});
433 }
434 $group->recv;
435 # when we get here %instances will be populated by all instances,
436 # sorted by their state.
437 If this looks mysterious, please consult AnyEvent for full
439 documentation and examples.
440 Lastly, be advised that some of the objects returned by calls to
442 VM::EC2, such as the VM::EC2::Instance object, will make their own
443 calls into VM::EC2 for certain methods. Some of these methods will
444 block (be synchronous) of necessity, even if you have set
445 $VM::EC2::ASYNC. For example, the instance object's current_status()
446 method must block in order to update the object and return the current
447 status. Other object methods may behave unpredictably in async mode.
448 Caveat emptor!
449
451 The extensive (and growing) Amazon API has many calls that you may
452 never need. To avoid the performance overhead of loading the interfaces
453 to all these calls, you may use Perl's import mechanism to load only
454 those modules you care about. By default, all methods are loaded.
455 Loading is controlled by the "use" import list, and follows the
457 conventions described in the Exporter module:
458 use VM::EC2; # load all methods!
460 use VM::EC2 'key','elastic_ip'; # load Key Pair and Elastic IP
462 # methods only
463 use VM::EC2 ':standard'; # load all the standard methods
465 use VM::EC2 ':standard','!key'; # load standard methods but not Key Pair
467 Related API calls are grouped together using the scheme described at
469 http://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query.html.
470 The modules that define the API calls can be found in VM/EC2/REST/; you
471 can read their documentation by running perldoc VM::EC2::REST::"name of
472 module":
473 perldoc VM::EC2::REST::elastic_ip
475 The groups that you can import are as follows:
477 :standard => ami, ebs, elastic_ip, instance, keys, general,
479 monitoring, tag, security_group, security_token, zone
480 :vpc => customer_gateway, dhcp, elastic_network_interface,
482 private_ip, internet_gateway, network_acl, route_table,
483 vpc, vpn, vpn_gateway
484 :misc => devpay, monitoring, reserved_instance,
486 spot_instance, vm_export, vm_import, windows
487 :scaling => elastic_load_balancer,autoscaling
489 :hpc => placement_group
491 :all => :standard, :vpn, :misc
493 :DEFAULT => :all
495 The individual modules are:
497 ami -- Control Amazon Machine Images
499 autoscaling -- Control autoscaling
500 customer_gateway -- VPC/VPN gateways
501 devpay -- DevPay API
502 dhcp -- VPC DHCP options
503 ebs -- Elastic Block Store volumes & snapshots
504 elastic_ip -- Elastic IP addresses
505 elastic_load_balancer -- The Elastic Load Balancer service
506 elastic_network_interface -- VPC Elastic Network Interfaces
507 general -- Get console output and account attributes
508 instance -- Control EC2 instances
509 internet_gateway -- VPC connections to the internet
510 keys -- Manage SSH keypairs
511 monitoring -- Control instance monitoring
512 network_acl -- Control VPC network access control lists
513 placement_group -- Control the placement of HPC instances
514 private_ip -- VPC private IP addresses
515 reserved_instance -- Reserve instances and view reservations
516 route_table -- VPC network routing
517 security_group -- Security groups for VPCs and normal instances
518 security_token -- Temporary credentials for use with IAM roles
519 spot_instance -- Request and manage spot instances
520 subnet -- VPC subnets
521 tag -- Create and interrogate resource tags.
522 vm_export -- Export VMs
523 vm_import -- Import VMs
524 vpc -- Create and manipulate virtual private clouds
525 vpn_gateway -- Create and manipulate VPN gateways within VPCs
526 vpn -- Create and manipulate VPNs within VPCs
527 windows -- Windows operating system-specific API calls.
528 zone -- Interrogate availability zones
529
531 The script sync_to_snapshot.pl, distributed with this module,
532 illustrates a relatively complex set of steps on EC2 that does
533 something useful. Given a list of directories or files on the local
534 filesystem it copies the files into an EBS snapshot with the desired
535 name by executing the following steps:
536 1. Provisions a new EBS volume on EC2 large enough to hold the data.
538 2. Spins up a staging instance to manage the network transfer of data
540 from the local machine to the staging volume.
541 3. Creates a temporary ssh keypair and a security group that allows an
543 rsync-over-ssh.
544 4. Formats and mounts the volume if necessary.
546 5. Initiates an rsync-over-ssh for the designated files and
548 directories.
549 6. Unmounts and snapshots the volume.
551 7. Cleans up.
553 If a snapshot of the same name already exists, then it is used to
555 create the staging volume, enabling network-efficient synchronization
556 of the files. A snapshot tag named "Version" is incremented each time
557 you synchronize.
558
560 This section describes the VM::EC2 constructor, accessor methods, and
561 methods relevant to error handling.
562 $ec2 = VM::EC2->new(-access_key=>$id,-secret_key=>$key,-endpoint=>$url)
564 Create a new Amazon access object. Required arguments are:
565 -access_key Access ID for an authorized user
567 -secret_key Secret key corresponding to the Access ID
569 -security_token Temporary security token obtained through a call to the
571 AWS Security Token Service
572 -endpoint The URL for making API requests
574 -region The region to receive the API requests
576 -raise_error If true, throw an exception.
578 -print_error If true, print errors to STDERR.
580 One or more of -access_key or -secret_key can be omitted if the
582 environment variables EC2_ACCESS_KEY and EC2_SECRET_KEY are defined. If
583 no endpoint is specified, then the environment variable EC2_URL is
584 consulted; otherwise the generic endpoint http://ec2.amazonaws.com/ is
585 used. You can also select the endpoint by specifying one of the Amazon
586 regions, such as "us-west-2", with the -region argument. The endpoint
587 specified by -region will override -endpoint.
588 -security_token is used in conjunction with temporary security tokens
590 returned by $ec2->get_federation_token() and $ec2->get_session_token()
591 to grant restricted, time-limited access to some or all your EC2
592 resources to users who do not have access to your account. If you pass
593 either a VM::EC2::Security::Token object, or the
594 VM::EC2::Security::Credentials object contained within the token
595 object, then new() does not need the -access_key or -secret_key
596 arguments. You may also pass a session token string scalar to
597 -security_token, in which case you must also pass the access key ID and
598 secret keys generated at the same time the session token was created.
599 See
600 http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/UsingIAM.html
601 and "AWS SECURITY TOKENS".
602 To use an Open Stack cloud, please provide the appropriate endpoint
604 URL.
605 By default, when the Amazon API reports an error, such as attempting to
607 perform an invalid operation on an instance, the corresponding method
608 will return empty and the error message can be recovered from
609 $ec2->error(). However, if you pass -raise_error=>1 to new(), the
610 module will instead raise a fatal error, which you can trap with eval{}
611 and report with $@:
612 eval {
614 $ec2->some_dangerous_operation();
615 $ec2->another_dangerous_operation();
616 };
617 print STDERR "something bad happened: $@" if $@;
618 The error object can be retrieved with $ec2->error() as before.
620 $access_key = $ec2->access_key([$new_access_key])
622 Get or set the ACCESS KEY. In this and all similar get/set methods,
623 call the method with no arguments to get the current value, and with a
624 single argument to change the value:
625 $current_key = $ec2->access_key;
627 $ec2->access_key('XYZZY');
628 In the case of setting the value, these methods will return the old
630 value as their result:
631 $old_key = $ec2->access_key($new_key);
633 $secret = $ec2->secret([$new_secret])
635 Get or set the SECRET KEY
636 $secret = $ec2->security_token([$new_token])
638 Get or set the temporary security token. See "AWS SECURITY TOKENS".
639 $endpoint = $ec2->endpoint([$new_endpoint])
641 Get or set the ENDPOINT URL.
642 $region = $ec2->region([$new_region])
644 Get or set the EC2 region manipulated by this module. This has the side
645 effect of changing the endpoint.
646 $ec2->raise_error($boolean)
648 Change the handling of error conditions. Pass a true value to cause
649 Amazon API errors to raise a fatal error. Pass false to make methods
650 return undef. In either case, you can detect the error condition by
651 calling is_error() and fetch the error message using error(). This
652 method will also return the current state of the raise error flag.
653 $ec2->print_error($boolean)
655 Change the handling of error conditions. Pass a true value to cause
656 Amazon API errors to print error messages to STDERR. Pass false to
657 cancel this behavior.
658 $boolean = $ec2->is_error
660 If a method fails, it will return undef. However, some methods, such as
661 describe_images(), will also return undef if no resources matches your
662 search criteria. Call is_error() to distinguish the two eventualities:
663 @images = $ec2->describe_images(-owner=>'29731912785');
665 unless (@images) {
666 die "Error: ",$ec2->error if $ec2->is_error;
667 print "No appropriate images found\n";
668 }
669 $err = $ec2->error
671 If the most recently-executed method failed, $ec2->error() will return
672 the error code and other descriptive information. This method will
673 return undef if the most recently executed method was successful.
674 The returned object is actually an AWS::Error object, which has two
676 methods named code() and message(). If used in a string context, its
677 operator overloading returns the composite string "$message [$code]".
678 $err = $ec2->error_str
680 Same as error() except it returns the string representation, not the
681 object. This works better in debuggers and exception handlers.
682 $account_id = $ec2->account_id
684 Looks up the account ID corresponding to the credentials provided when
685 the VM::EC2 instance was created. The way this is done is to fetch the
686 "default" security group, which is guaranteed to exist, and then return
687 its groupId field. The result is cached so that subsequent accesses are
688 fast.
689 $account_id = $ec2->userId
691 Same as above, for convenience.
692 $new_ec2 = $ec2->clone
694 This method creates an identical copy of the EC2 object. It is used
695 occasionally internally for creating an EC2 object in a different AWS
696 region:
697 $singapore = $ec2->clone;
699 $singapore->region('ap-souteast-1');
700
702 Load the 'instances' module to bring in methods for interrogating,
703 launching and manipulating EC2 instances. This module is part of the
704 ':standard' API group. The methods are described in detail in
705 VM::EC2::REST::instance. Briefly:
706 @i = $ec2->describe_instances(-instance_id=>\@ids,-filter=>\%filters)
708 @i = $ec2->run_instances(-image_id=>$id,%other_args)
709 @s = $ec2->start_instances(-instance_id=>\@instance_ids)
710 @s = $ec2->stop_instances(-instance_id=>\@instance_ids,-force=>1)
711 @s = $ec2->reboot_instances(-instance_id=>\@instance_ids)
712 $b = $ec2->confirm_product_instance($instance_id,$product_code)
713 $m = $ec2->instance_metadata
714 @d = $ec2->describe_instance_attribute($instance_id,$attribute)
715 $b = $ec2->modify_instance_attribute($instance_id,-$attribute_name=>$value)
716 $b = $ec2->reset_instance_attribute($instance_id,$attribute)
717 @s = $ec2->describe_instance_status(-instance_id=>\@ids,-filter=>\%filters,%other_args);
718
720 Load the 'ebs' module to bring in methods specific for elastic block
721 storage volumes and snapshots. This module is part of the ':standard'
722 API group. The methods are described in detail in VM::EC2::REST::ebs.
723 Briefly:
724 @v = $ec2->describe_volumes(-volume_id=>\@ids,-filter=>\%filters)
726 $v = $ec2->create_volume(%args)
727 $b = $ec2->delete_volume($volume_id)
728 $a = $ec2->attach_volume($volume_id,$instance_id,$device)
729 $a = $ec2->detach_volume($volume_id)
730 $ec2->wait_for_attachments(@attachment)
731 @v = $ec2->describe_volume_status(-volume_id=>\@ids,-filter=>\%filters)
732 $ec2->wait_for_volumes(@volumes)
733 @d = $ec2->describe_volume_attribute($volume_id,$attribute)
734 $b = $ec2->enable_volume_io(-volume_id=>$volume_id)
735 @s = $ec2->describe_snapshots(-snapshot_id=>\@ids,%other_args)
736 @d = $ec2->describe_snapshot_attribute($snapshot_id,$attribute)
737 $b = $ec2->modify_snapshot_attribute($snapshot_id,-$argument=>$value)
738 $b = $ec2->reset_snapshot_attribute($snapshot_id,$attribute)
739 $s = $ec2->create_snapshot(-volume_id=>$vol,-description=>$desc)
740 $b = $ec2->delete_snapshot($snapshot_id)
741 $s = $ec2->copy_snapshot(-source_region=>$region,-source_snapshot_id=>$id,-description=>$desc)
742 $ec2->wait_for_snapshots(@snapshots)
743
745 Load the 'ami' module to bring in methods for creating and manipulating
746 Amazon Machine Images. This module is part of the ':standard" group.
747 Full details are in VM::EC2::REST::ami. Briefly:
748 @i = $ec2->describe_images(@image_ids)
750 $i = $ec2->create_image(-instance_id=>$id,-name=>$name,%other_args)
751 $i = $ec2->register_image(-name=>$name,%other_args)
752 $r = $ec2->deregister_image($image_id)
753 @d = $ec2->describe_image_attribute($image_id,$attribute)
754 $b = $ec2->modify_image_attribute($image_id,-$attribute_name=>$value)
755 $b = $ec2->reset_image_attribute($image_id,$attribute_name)
756
758 Load the 'keys' module to bring in methods for creating and
759 manipulating SSH keypairs. This module is loaded with the ':standard'
760 group and documented in VM::EC2::REST::keys.
761 @k = $ec2->describe_key_pairs(@names);
763 $k = $ec2->create_key_pair($name)
764 $k = $ec2->import_key_pair($name,$public_key)
765 $b = $ec2->delete_key_pair($name)
766
768 The methods in this module (loaded with ':standard') allow you to
769 create, delete and fetch resource tags. You may find that you rarely
770 need to use these methods directly because every object produced by
771 VM::EC2 supports a simple tag interface:
772 $object = $ec2->describe_volumes(-volume_id=>'vol-12345'); # e.g.
774 $tags = $object->tags();
775 $name = $tags->{Name};
776 $object->add_tags(Role => 'Web Server', Status=>'development);
777 $object->delete_tags(Name=>undef);
778 See VM::EC2::Generic for a full description of the uniform object
780 tagging interface, and VM::EC2::REST::tag for methods that allow you to
781 manipulate the tags on multiple objects simultaneously. The methods
782 defined by this module are:
783 @t = $ec2->describe_tags(-filter=>\%filters);
785 $b = $ec2->create_tags(-resource_id=>\@ids,-tag=>{key1=>value1...})
786 $b = $ec2->delete_tags(-resource_id=>$id1,-tag=>{key1=>value1...})
787
789 EC2 virtual private clouds (VPCs) provide facilities for creating
790 tiered applications combining public and private subnetworks, and for
791 extending your home/corporate network into the cloud. VPC-related
792 methods are defined in the customer_gateway, dhcp,
793 elastic_network_interface, private_ip, internet_gateway, network_acl,
794 route_table, vpc, vpn, and vpn_gateway modules, and are loaded by
795 importing ':vpc'. See VM::EC2::REST::vpc for an introduction.
796 The VM::EC2::VPC and VM::EC2::VPC::Subnet modules define convenience
798 methods that simplify working with VPC objects. This allows for steps
799 that typically follow each other, such as creating a route table and
800 associating it with a subnet, happen automatically. For example, this
801 series of calls creates a VPC with a single subnet, creates an Internet
802 gateway attached to the VPC, associates a new route table with the
803 subnet and then creates a default route from the subnet to the Internet
804 gateway:
805 $vpc = $ec2->create_vpc('10.0.0.0/16') or die $ec2->error_str;
807 $subnet1 = $vpc->create_subnet('10.0.0.0/24') or die $vpc->error_str;
808 $gateway = $vpc->create_internet_gateway or die $vpc->error_str;
809 $routeTbl = $subnet->create_route_table or die $vpc->error_str;
810 $routeTbl->create_route('0.0.0.0/0' => $gateway) or die $vpc->error_str;
811
813 The methods in the 'elastic_load_balancer' and 'autoscaling' modules
814 allow you to retrieve information about Elastic Load Balancers, create
815 new ELBs, and change the properties of the ELBs, as well as define
816 autoscaling groups and their launch configurations. These modules are
817 both imported by the ':scaling' import group. See
818 VM::EC2::REST::elastic_load_balancer and VM::EC2::REST::autoscaling for
819 descriptions of the facilities enabled by this module.
820
822 The VM::EC2::Security::Policy module provides a simple Identity and
823 Access Management (IAM) policy statement generator geared for use with
824 AWS security tokens (see next section). Its facilities are defined in
825 VM::EC2::Security::Token.
826
828 AWS security tokens provide a way to grant temporary access to
829 resources in your EC2 space without giving them permanent accounts.
830 They also provide the foundation for mobile services and multifactor
831 authentication devices (MFA). These methods are defined in
832 'security_token', which is part of the ':standard' group. See
833 VM::EC2::REST::security_token for details. Here is a quick example:
834 Here is an example:
836 # on your side of the connection
838 $ec2 = VM::EC2->new(...); # as usual
839 my $policy = VM::EC2::Security::Policy->new;
840 $policy->allow('DescribeImages','RunInstances');
841 my $token = $ec2->get_federation_token(-name => 'TemporaryUser',
842 -duration => 60*60*3, # 3 hrs, as seconds
843 -policy => $policy);
844 my $serialized = $token->credentials->serialize;
845 send_data_to_user_somehow($serialized);
846 # on the temporary user's side of the connection
848 my $serialized = get_data_somehow();
849 my $token = VM::EC2::Security::Credentials->new_from_serialized($serialized);
850 my $ec2 = VM::EC2->new(-security_token => $token);
851 print $ec2->describe_images(-owner=>'self');
852
854 The 'spot_instance' and 'reserved_instance' modules allow you to create
855 and manipulate spot and reserved instances. They are both part of the
856 ':misc' import group. See VM::EC2::REST::spot_instance and
857 VM::EC2::REST::reserved_instance. For example:
858 @offerings = $ec2->describe_reserved_instances_offerings(
860 {'availability-zone' => 'us-east-1a',
861 'instance-type' => 'c1.medium',
862 'product-description' =>'Linux/UNIX',
863 'duration' => 31536000, # this is 1 year
864 });
865 $offerings[0]->purchase(5) and print "Five reserved instances purchased\n";
866
868 VM::EC2 provides a series of methods that allow your script to wait in
869 an efficient manner for desired state changes in instances, volumes and
870 other objects. They are described in detail the individual modules to
871 which they apply, but in each case the method will block until each
872 member of a list of objects transitions to a terminal state (e.g.
873 "completed" in the case of a snapshot). Briefly:
874 $ec2->wait_for_instances(@instances)
876 $ec2->wait_for_snapshots(@snapshots)
877 $ec2->wait_for_volumes(@volumes)
878 $ec2->wait_for_attachments(@attachment)
879 There is also a generic version of this defined in the VM::EC2 core:
881 $ec2->wait_for_terminal_state(\@objects,['list','of','states'] [,$timeout])
883 Generic version of the last four methods. Wait for all members of the
884 provided list of Amazon objects instances to reach some terminal state
885 listed in the second argument, and then return a hash reference that
886 maps each object ID to its final state.
887 If a timeout is provided, in seconds, then the method will abort after
889 waiting the indicated time and return undef.
890 $timeout = $ec2->wait_for_timeout([$new_timeout]);
892 Get or change the timeout for wait_for_instances(),
893 wait_for_attachments(), and wait_for_volumes(). The timeout is given in
894 seconds, and defaults to 600 (10 minutes). You can set this to 0 to
895 wait forever.
896
898 These methods are used internally and are listed here without
899 documentation (yet).
900 $underscore_name = $ec2->canonicalize($mixedCaseName)
902 $instance_id = $ec2->instance_parm(@args)
903 @arguments = $ec2->value_parm(ParameterName => \%args)
904 @arguments = $ec2->single_parm(ParameterName => \%args)
905 @parameters = $ec2->prefix_parm($prefix, ParameterName => \%args)
906 @arguments = $ec2->member_hash_parms(ParameterName => \%args)
907 Create a parameter list from a hashref or arrayref of hashes
908 Created specifically for the RDS ModifyDBParameterGroup parameter
910 'Parameters', but may be useful for other calls in the future.
911 ie:
913 The argument would be in the form:
915 [
917 {
918 ParameterName=>'max_user_connections',
919 ParameterValue=>24,
920 ApplyMethod=>'pending-reboot'
921 },
922 {
923 ParameterName=>'max_allowed_packet',
924 ParameterValue=>1024,
925 ApplyMethod=>'immediate'
926 },
927 ];
928 The resulting output would be if the argname is '-parameters':
930 Parameters.member.1.ParameterName => max_user_connections
932 Parameters.member.1.ParameterValue => 24
933 Parameters.member.1.ApplyMethod => pending-reboot
934 Parameters.member.2.ParameterName => max_allowed_packet
935 Parameters.member.2.ParameterValue => 1024
936 Parameters.member.2.ApplyMethod => immediate
937 @arguments = $ec2->list_parm(ParameterName => \%args)
939 @parameters = $ec2->member_list_parm(ParameterName => \%args)
940 @arguments = $ec2->filter_parm(\%args)
941 @arguments =
942 $ec2->key_value_parameters($param_name,$keyname,$valuename,\%args,$skip_undef_values)
943 @arguments =
944 $ec2->member_key_value_parameters($param_name,$keyname,$valuename,\%args,$skip_undef_values)
945 @arguments = $ec2->launch_perm_parm($prefix,$suffix,$value)
946 @arguments = $ec2->iam_parm($args)
947 @arguments = $ec2->block_device_parm($block_device_mapping_string)
948 $version = $ec2->version()
949 Returns the API version to be sent to the endpoint. Calls
950 guess_version_from_endpoint() to determine this.
951 $version = $ec2->guess_version_from_endpoint()
953 This method attempts to guess what version string to use when
954 communicating with various endpoints. When talking to endpoints that
955 contain the string "Eucalyptus" uses the old EC2 API "2009-04-04". When
956 talking to other endpoints, uses the latest EC2 version string.
957 $ts = $ec2->timestamp
959 @obj = $ec2->call($action,@param);
960 Make a call to Amazon using $action and the passed arguments, and
961 return a list of objects.
962 if $VM::EC2::ASYNC is set to true, then will return a AnyEvent::CondVar
964 object instead of a list of objects. You may retrieve the objects by
965 calling recv() or setting a callback:
966 $VM::EC2::ASYNC = 1;
968 my $cv = $ec2->call('DescribeInstances');
969 my @obj = $cv->recv;
970 or
972 $VM::EC2::ASYNC = 1;
974 my $cv = $ec2->call('DescribeInstances');
975 $cv->cb(sub { my @objs = shift->recv;
976 do_something(@objs);
977 });
978 $url = $ec2->login_url(-credentials => $credentials, -issuer =>
980 $issuer_url, -destination => $console_url);
981 Returns an HTTP::Request object that points to the URL to login a user
982 with STS credentials
983 -credentials => $fed_token->credentials - Credentials from an $ec2->get_federation_token call
985 -token => $token - a SigninToken from $ec2->get_signin_token call
986 -issuer => $issuer_url
987 -destination => $console_url - URL of the AWS console. Defaults to https://console.aws.amazon.com/console/home
988 -auto_scaling_group_names List of auto scaling groups to describe
989 -names Alias of -auto_scaling_group_names
990 -credentials or -token are required for this method to work
992 Usage can be:
994 my $fed_token = $ec2->get_federation_token(...);
996 my $token = $ec2->get_signin_token(-credentials => $fed_token->credentials);
997 my $url = $ec2->login_url(-token => $token->{SigninToken}, -issuer => $issuer_url, -destination => $console_url);
998 Or:
1000 my $fed_token = $ec2->get_federation_token(...);
1002 my $url = $ec2->login_url(-credentials => $fed_token->credentials, -issuer => $issuer_url, -destination => $console_url);
1003 $request = $ec2->_sign(@args)
1005 Create and sign an HTTP::Request.
1006 @param = $ec2->args(ParamName=>@_)
1008 Set up calls that take either method(-resource_id=>'foo') or
1009 method('foo').
1010
1012 This section contains technical information that may be of interest to
1013 developers.
1014 Signing and authentication protocol
1016 This module uses Amazon AWS signing protocol version 2, as described at
1017 http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?using-query-api.html.
1018 It uses the HmacSHA256 signature method, which is the most secure
1019 method currently available. For additional security, use "https" for
1020 the communications endpoint:
1021 $ec2 = VM::EC2->new(-endpoint=>'https://ec2.amazonaws.com');
1023 Subclassing VM::EC2 objects
1025 To subclass VM::EC2 objects (or implement your own from scratch) you
1026 will need to override the object dispatch mechanism. Fortunately this
1027 is very easy. After "use VM::EC2" call VM::EC2::Dispatch->register()
1028 one or more times:
1029 VM::EC2::Dispatch->register($call_name => $dispatch).
1031 The first argument, $call_name, is name of the Amazon API call, such as
1033 "DescribeImages".
1034 The second argument, $dispatch, instructs VM::EC2::Dispatch how to
1036 create objects from the parsed XML. There are three possible syntaxes:
1037 1) A CODE references, such as an anonymous subroutine.
1039 In this case the code reference will be invoked to handle the
1041 parsed XML returned from the request. The code will receive
1042 two arguments consisting of the parsed
1043 content of the response, and the VM::EC2 object used to generate the
1044 request.
1045 2) A VM::EC2::Dispatch method name, optionally followed by its arguments
1047 delimited by commas. Example:
1048 "fetch_items,securityGroupInfo,VM::EC2::SecurityGroup"
1050 This tells Dispatch to invoke its fetch_items() method with
1052 the following arguments:
1053 $dispatch->fetch_items($parsed_xml,$ec2,'securityGroupInfo','VM::EC2::SecurityGroup')
1055 The fetch_items() method is used for responses in which a
1057 list of objects is embedded within a series of <item> tags.
1058 See L<VM::EC2::Dispatch> for more information.
1059 Other commonly-used methods are "fetch_one", and "boolean".
1061 3) A class name, such as 'MyVolume'
1063 In this case, class MyVolume is loaded and then its new() method
1065 is called with the four arguments ($parsed_xml,$ec2,$xmlns,$requestid),
1066 where $parsed_xml is the parsed XML response, $ec2 is the VM::EC2
1067 object that generated the request, $xmlns is the XML namespace
1068 of the XML response, and $requestid is the AWS-generated ID for the
1069 request. Only the first two arguments are really useful.
1070 I suggest you inherit from VM::EC2::Generic and use the inherited new()
1072 method to store the parsed XML object and other arguments.
1073 Dispatch tries each of (1), (2) and (3), in order. This means that
1075 class names cannot collide with method names.
1076 The parsed content is the result of passing the raw XML through a
1078 XML::Simple object created with:
1079 XML::Simple->new(ForceArray => ['item'],
1081 KeyAttr => ['key'],
1082 SuppressEmpty => undef);
1083 In general, this will give you a hash of hashes. Any tag named 'item'
1085 will be forced to point to an array reference, and any tag named "key"
1086 will be flattened as described in the XML::Simple documentation.
1087 A simple way to examine the raw parsed XML is to invoke any
1089 VM::EC2::Generic's as_string() method:
1090 my ($i) = $ec2->describe_instances;
1092 print $i->as_string;
1093 This will give you a Data::Dumper representation of the XML after it
1095 has been parsed.
1096 The suggested way to override the dispatch table is from within a
1098 subclass of VM::EC2:
1099 package 'VM::EC2New';
1101 use base 'VM::EC2';
1102 sub new {
1103 my $self=shift;
1104 VM::EC2::Dispatch->register('call_name_1'=>\&subroutine1).
1105 VM::EC2::Dispatch->register('call_name_2'=>\&subroutine2).
1106 $self->SUPER::new(@_);
1107 }
1108 See VM::EC2::Dispatch for a working example of subclassing VM::EC2 and
1110 one of its object classes.
1111
1113 The git source for this library can be found at
1114 https://github.com/lstein/LibVM-EC2-Perl, To contribute to development,
1115 please obtain a github account and then either:
1116 1) Fork a copy of the repository, make your changes against this repository,
1118 and send a pull request to me to incorporate your changes.
1119 2) Contact me by email and ask for push privileges on the repository.
1121 See http://help.github.com/ for help getting started.
1123
1125 Net::Amazon::EC2 VM::EC2::Dispatch VM::EC2::Generic
1126 VM::EC2::BlockDevice VM::EC2::BlockDevice::Attachment
1127 VM::EC2::BlockDevice::EBS VM::EC2::BlockDevice::Mapping
1128 VM::EC2::BlockDevice::Mapping::EBS VM::EC2::Error VM::EC2::Generic
1129 VM::EC2::Group VM::EC2::Image VM::EC2::Instance
1130 VM::EC2::Instance::ConsoleOutput VM::EC2::Instance::Metadata
1131 VM::EC2::Instance::MonitoringState VM::EC2::Instance::PasswordData
1132 VM::EC2::Instance::Set VM::EC2::Instance::State
1133 VM::EC2::Instance::State::Change VM::EC2::Instance::State::Reason
1134 VM::EC2::KeyPair VM::EC2::Region VM::EC2::ReservationSet
1135 VM::EC2::ReservedInstance VM::EC2::ReservedInstance::Offering
1136 VM::EC2::SecurityGroup VM::EC2::Snapshot VM::EC2::Staging::Manager
1137 VM::EC2::Tag VM::EC2::Volume
1138
1140 Lincoln Stein <lincoln.stein@gmail.com>.
1141 Copyright (c) 2011 Ontario Institute for Cancer Research
1143 This package and its accompanying libraries is free software; you can
1145 redistribute it and/or modify it under the terms of the GPL (either
1146 version 1, or at your option, any later version) or the Artistic
1147 License 2.0. Refer to LICENSE for the full license text. In addition,
1148 please see DISCLAIMER.txt for disclaimers of warranty.
1149
1151 Hey! The above document had some coding errors, which are explained
1152 below:
1153 Around line 1057:
1155 Unterminated L<...> sequence
1156perl v5.36.0 2023-01-20 VM::EC2(3)