1Net::Amazon::EC2(3)   User Contributed Perl Documentation  Net::Amazon::EC2(3)
2
3
4

NAME

6       Net::Amazon::EC2 - Perl interface to the Amazon Elastic Compute Cloud
7       (EC2) environment.
8

VERSION

10       EC2 Query API version: '2014-06-15'
11

SYNOPSIS

13        use Net::Amazon::EC2;
14
15        my $ec2 = Net::Amazon::EC2->new(
16               AWSAccessKeyId    => 'PUBLIC_KEY_HERE',
17               SecretAccessKey   => 'SECRET_KEY_HERE',
18               signature_version => 4,
19        );
20
21        # Start 1 new instance from AMI: ami-XXXXXXXX
22        my $instance = $ec2->run_instances(ImageId => 'ami-XXXXXXXX', MinCount => 1, MaxCount => 1);
23
24        my $running_instances = $ec2->describe_instances;
25
26        foreach my $reservation (@$running_instances) {
27               foreach my $instance ($reservation->instances_set) {
28                       print $instance->instance_id . "\n";
29               }
30        }
31
32        my $instance_id = $instance->instances_set->[0]->instance_id;
33
34        print "$instance_id\n";
35
36        # Terminate instance
37
38        my $result = $ec2->terminate_instances(InstanceId => $instance_id);
39
40       If an error occurs while communicating with EC2, these methods will
41       throw a Net::Amazon::EC2::Errors exception.
42

DESCRIPTION

44       This module is a Perl interface to Amazon's Elastic Compute Cloud. It
45       uses the Query API to communicate with Amazon's Web Services framework.
46

CLASS METHODS

48   new(%params)
49       This is the constructor, it will return you a Net::Amazon::EC2 object
50       to work with.  It takes these parameters:
51
52       AWSAccessKeyId (required, unless an IAM role is present)
53           Your AWS access key.  For information on IAM roles, see
54           <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#UsingIAMrolesWithAmazonEC2Instances>
55
56       SecretAccessKey (required, unless an IAM role is present)
57           Your secret key, WARNING! don't give this out or someone will be
58           able to use your account and incur charges on your behalf.
59
60       SecurityToken (optional)
61           When using temporary credentials from STS the Security Token must
62           be passed in along with the temporary AWSAccessKeyId and
63           SecretAccessKey.  The most common case is when using IAM
64           credentials with the addition of MFA (multi-factor authentication).
65           See <http://docs.aws.amazon.com/STS/latest/UsingSTS/Welcome.html>
66
67       region (optional)
68           The region to run the API requests through. Defaults to us-east-1.
69
70       ssl (optional)
71           If set to a true value, the base_url will use https:// instead of
72           http://. Setting base_url explicitly will override this. Defaults
73           to true as of 0.22.
74
75       debug (optional)
76           A flag to turn on debugging. Among other useful things, it will
77           make the failing api calls print a stack trace. It is turned off by
78           default.
79
80       return_errors (optional)
81           Previously, Net::Amazon::EC2 would return a
82           Net::Amazon::EC2::Errors object when it encountered an error
83           condition. As of 0.19, this object is thrown as an exception using
84           croak or confess depending on if the debug flag is set.
85
86           If you want/need the old behavior, set this attribute to a true
87           value.
88

OBJECT METHODS

90   allocate_address()
91       Acquires an elastic IP address which can be associated with an
92       EC2-classic instance to create a movable static IP. Takes no arguments.
93
94       Returns the IP address obtained.
95
96   allocate_vpc_address()
97       Acquires an elastic IP address which can be associated with a VPC
98       instance to create a movable static IP. Takes no arguments.
99
100       Returns the allocationId of the allocated address.
101
102   associate_address(%params)
103       Associates an elastic IP address with an instance. It takes the
104       following arguments:
105
106       InstanceId (required)
107           The instance id you wish to associate the IP address with
108
109       PublicIp (optional)
110           The IP address. Used for allocating addresses to EC2-classic
111           instances.
112
113       AllocationId (optional)
114           The allocation ID.  Used for allocating address to VPC instances.
115
116       Returns true if the association succeeded.
117
118   attach_volume(%params)
119       Attach a volume to an instance.
120
121       VolumeId (required)
122           The volume id you wish to attach.
123
124       InstanceId (required)
125           The instance id you wish to attach the volume to.
126
127       Device (required)
128           The device id you want the volume attached as.
129
130       Returns a Net::Amazon::EC2::Attachment object containing the resulting
131       volume status.
132
133   authorize_security_group_ingress(%params)
134       This method adds permissions to a security group.  It takes the
135       following parameters:
136
137       GroupName (required)
138           The name of the group to add security rules to.
139
140       SourceSecurityGroupName (required when authorizing a user and group
141       together)
142           Name of the group to add access for.
143
144       SourceSecurityGroupOwnerId (required when authorizing a user and group
145       together)
146           Owner of the group to add access for.
147
148       IpProtocol (required when adding access for a CIDR)
149           IP Protocol of the rule you are adding access for (TCP, UDP, or
150           ICMP)
151
152       FromPort (required when adding access for a CIDR)
153           Beginning of port range to add access for.
154
155       ToPort (required when adding access for a CIDR)
156           End of port range to add access for.
157
158       CidrIp (required when adding access for a CIDR)
159           The CIDR IP space we are adding access for.
160
161       Adding a rule can be done in two ways: adding a source group name +
162       source group owner id, or, CIDR IP range. Both methods allow IP
163       protocol, from port and to port specifications.
164
165       Returns 1 if rule is added successfully.
166
167   bundle_instance(%params)
168       Bundles the Windows instance. This procedure is not applicable for
169       Linux and UNIX instances.
170
171       NOTE NOTE NOTE This is not well tested as I don't run windows instances
172
173       InstanceId (required)
174           The ID of the instance to bundle.
175
176       Storage.S3.Bucket (required)
177           The bucket in which to store the AMI. You can specify a bucket that
178           you already own or a new bucket that Amazon EC2 creates on your
179           behalf. If you specify a bucket that belongs to someone else,
180           Amazon EC2 returns an error.
181
182       Storage.S3.Prefix (required)
183           Specifies the beginning of the file name of the AMI.
184
185       Storage.S3.AWSAccessKeyId (required)
186           The Access Key ID of the owner of the Amazon S3 bucket.
187
188       Storage.S3.UploadPolicy (required)
189           An Amazon S3 upload policy that gives Amazon EC2 permission to
190           upload items into Amazon S3 on the user's behalf.
191
192       Storage.S3.UploadPolicySignature (required)
193           The signature of the Base64 encoded JSON document.
194
195           JSON Parameters: (all are required)
196
197           expiration - The expiration of the policy. Amazon recommends 12
198           hours or longer.  conditions - A list of restrictions on what can
199           be uploaded to Amazon S3. Must contain the bucket and ACL
200           conditions in this table.  bucket - The bucket to store the AMI.
201           acl - This must be set to ec2-bundle-read.
202
203       Returns a Net::Amazon::EC2::BundleInstanceResponse object
204
205   cancel_bundle_task(%params)
206       Cancels the bundle task. This procedure is not applicable for Linux and
207       UNIX instances.
208
209       BundleId (required)
210           The ID of the bundle task to cancel.
211
212       Returns a Net::Amazon::EC2::BundleInstanceResponse object
213
214   confirm_product_instance(%params)
215       Checks to see if the product code passed in is attached to the instance
216       id, taking the following parameter:
217
218       ProductCode (required)
219           The Product Code to check
220
221       InstanceId (required)
222           The Instance Id to check
223
224       Returns a Net::Amazon::EC2::ConfirmProductInstanceResponse object
225
226   create_image(%params)
227       Creates an AMI that uses an Amazon EBS root device from a "running" or
228       "stopped" instance.
229
230       AMIs that use an Amazon EBS root device boot faster than AMIs that use
231       instance stores.  They can be up to 1 TiB in size, use storage that
232       persists on instance failure, and can be stopped and started.
233
234       InstanceId (required)
235           The ID of the instance.
236
237       Name (required)
238           The name of the AMI that was provided during image creation.
239
240           Note that the image name has the following constraints:
241
242           3-128 alphanumeric characters, parenthesis, commas, slashes,
243           dashes, or underscores.
244
245       Description (optional)
246           The description of the AMI that was provided during image creation.
247
248       NoReboot (optional)
249           By default this property is set to false, which means Amazon EC2
250           attempts to cleanly shut down the instance before image creation
251           and reboots the instance afterwards. When set to true, Amazon EC2
252           does not shut down the instance before creating the image. When
253           this option is used, file system integrity on the created image
254           cannot be guaranteed.
255
256       BlockDeviceMapping (optional)
257           Array ref of the device names exposed to the instance.
258
259           You can specify device names as '<device>=<block_device>' similar
260           to ec2-create-image command.
261           (<http://docs.aws.amazon.com/AWSEC2/latest/CommandLineReference/ApiReference-cmd-CreateImage.html>)
262
263             BlockDeviceMapping => [
264                   '/dev/sda=:256:true:standard',
265                   '/dev/sdb=none',
266                   '/dev/sdc=ephemeral0',
267                   '/dev/sdd=ephemeral1',
268             ],
269
270       Returns the ID of the AMI created.
271
272   create_key_pair(%params)
273       Creates a new 2048 bit key pair, taking the following parameter:
274
275       KeyName (required)
276           A name for this key. Should be unique.
277
278       Returns a Net::Amazon::EC2::KeyPair object
279
280   create_security_group(%params)
281       This method creates a new security group.  It takes the following
282       parameters:
283
284       GroupName (required)
285           The name of the new group to create.
286
287       GroupDescription (required)
288           A short description of the new group.
289
290       Returns 1 if the group creation succeeds.
291
292   create_snapshot(%params)
293       Create a snapshot of a volume. It takes the following arguments:
294
295       VolumeId (required)
296           The volume id of the volume you want to take a snapshot of.
297
298       Description (optional)
299           Description of the Amazon EBS snapshot.
300
301       Returns a Net::Amazon::EC2::Snapshot object of the newly created
302       snapshot.
303
304   create_tags(%params)
305       Creates tags.
306
307       ResourceId (required)
308           The ID of the resource to create tags. Can be a scalar or arrayref
309
310       Tags (required)
311           Hashref where keys and values will be set on all resources given in
312           the first element.
313
314       Returns true if the tag creation succeeded.
315
316   create_volume(%params)
317       Creates a volume.
318
319       Size (required)
320           The size in GiB ( 1024^3 ) of the volume you want to create.
321
322       SnapshotId (optional)
323           The optional snapshot id to create the volume from. The volume must
324           be equal or larger than the snapshot it was created from.
325
326       AvailabilityZone (required)
327           The availability zone to create the volume in.
328
329       VolumeType (optional)
330           The volume type: 'standard', 'gp2', or 'io1'.  Defaults to
331           'standard'.
332
333       Iops (required if VolumeType is 'io1')
334           The number of I/O operations per second (IOPS) that the volume
335           supports. This is limited to 30 times the volume size with an
336           absolute maximum of 4000. It's likely these numbers will change in
337           the future.
338
339           Required when the volume type is io1; not used otherwise.
340
341       Encrypted (optional)
342           Encrypt the volume. EBS encrypted volumes are encrypted on the host
343           using AWS managed keys. Only some instance types support encrypted
344           volumes. At the time of writing encrypted volumes are not supported
345           for boot volumes.
346
347       Returns a Net::Amazon::EC2::Volume object containing the resulting
348       volume status
349
350   delete_key_pair(%params)
351       This method deletes a keypair.  Takes the following parameter:
352
353       KeyName (required)
354           The name of the key to delete.
355
356       Returns 1 if the key was successfully deleted.
357
358   delete_security_group(%params)
359       This method deletes a security group.  It takes the following
360       parameter:
361
362       GroupName (required)
363           The name of the security group to delete.
364
365       Returns 1 if the delete succeeded.
366
367   delete_snapshot(%params)
368       Deletes the snapshots passed in. It takes the following arguments:
369
370       SnapshotId (required)
371           A snapshot id can be passed in. Will delete the corresponding
372           snapshot.
373
374       Returns true if the deleting succeeded.
375
376   delete_volume(%params)
377       Delete a volume.
378
379       VolumeId (required)
380           The volume id you wish to delete.
381
382       Returns true if the deleting succeeded.
383
384   delete_tags(%params)
385       Delete tags.
386
387       ResourceId (required)
388           The ID of the resource to delete tags
389
390       Tag.Key (required)
391           Key for a tag, may pass in a scalar or arrayref.
392
393       Tag.Value (required)
394           Value for a tag, may pass in a scalar or arrayref.
395
396       Returns true if the releasing succeeded.
397
398   deregister_image(%params)
399       This method will deregister an AMI. It takes the following parameter:
400
401       ImageId (required)
402           The image id of the AMI you want to deregister.
403
404       Returns 1 if the deregistering succeeded
405
406   describe_addresses(%params)
407       This method describes the elastic addresses currently allocated and any
408       instances associated with them. It takes the following arguments:
409
410       PublicIp (optional)
411           The IP address to describe. Can be either a scalar or an array ref.
412
413       Returns an array ref of Net::Amazon::EC2::DescribeAddress objects
414
415   describe_availability_zones(%params)
416       This method describes the availability zones currently available to
417       choose from. It takes the following arguments:
418
419       ZoneName (optional)
420           The zone name to describe. Can be either a scalar or an array ref.
421
422       Returns an array ref of Net::Amazon::EC2::AvailabilityZone objects
423
424   describe_bundle_tasks(%params)
425       Describes current bundling tasks. This procedure is not applicable for
426       Linux and UNIX instances.
427
428       BundleId (optional)
429           The optional ID of the bundle task to describe.
430
431       Returns a array ref of Net::Amazon::EC2::BundleInstanceResponse objects
432
433   describe_image_attributes(%params)
434       This method pulls a list of attributes for the image id specified
435
436       ImageId (required)
437           A scalar containing the image you want to get the list of
438           attributes for.
439
440       Attribute (required)
441           A scalar containing the attribute to describe.
442
443           Valid attributes are:
444
445           launchPermission - The AMIs launch permissions.
446           ImageId - ID of the AMI for which an attribute will be described.
447           productCodes - The product code attached to the AMI.
448           kernel - Describes the ID of the kernel associated with the AMI.
449           ramdisk - Describes the ID of RAM disk associated with the AMI.
450           blockDeviceMapping - Defines native device names to use when
451           exposing virtual devices.
452           platform - Describes the operating system platform.
453
454       Returns a Net::Amazon::EC2::DescribeImageAttribute object
455
456       * NOTE: There is currently a bug in Amazon's SOAP and Query API for
457       when you try and describe the attributes: kernel, ramdisk,
458       blockDeviceMapping, or platform AWS returns an invalid response. No
459       response yet from Amazon on an ETA for getting that bug fixed.
460
461   describe_images(%params)
462       This method pulls a list of the AMIs which can be run.  The list can be
463       modified by passing in some of the following parameters:
464
465       ImageId (optional)
466           Either a scalar or an array ref can be passed in, will cause just
467           these AMIs to be 'described'
468
469       Owner (optional)
470           Either a scalar or an array ref can be passed in, will cause AMIs
471           owned by the Owner's provided will be 'described'. Pass either
472           account ids, or 'amazon' for all amazon-owned AMIs, or 'self' for
473           your own AMIs.
474
475       ExecutableBy (optional)
476           Either a scalar or an array ref can be passed in, will cause AMIs
477           executable by the account id's specified.  Or 'self' for your own
478           AMIs.
479
480       Returns an array ref of Net::Amazon::EC2::DescribeImagesResponse
481       objects
482
483   describe_instances(%params)
484       This method pulls a list of the instances which are running or were
485       just running.  The list can be modified by passing in some of the
486       following parameters:
487
488       InstanceId (optional)
489           Either a scalar or an array ref can be passed in, will cause just
490           these instances to be 'described'
491
492       Filter (optional)
493           The filters for only the matching instances to be 'described'.  A
494           filter tuple is an arrayref constsing one key and one or more
495           values.  The option takes one filter tuple, or an arrayref of
496           multiple filter tuples.
497
498       Returns an array ref of Net::Amazon::EC2::ReservationInfo objects
499
500   describe_instance_status(%params)
501       This method pulls a list of the instances based on some status filter.
502       The list can be modified by passing in some of the following
503       parameters:
504
505       InstanceId (optional)
506           Either a scalar or an array ref can be passed in, will cause just
507           these instances to be 'described'
508
509       Filter (optional)
510           The filters for only the matching instances to be 'described'.  A
511           filter tuple is an arrayref constsing one key and one or more
512           values.  The option takes one filter tuple, or an arrayref of
513           multiple filter tuples.
514
515       Returns an array ref of Net::Amazon::EC2::InstanceStatuses objects
516
517   _create_describe_instance_status(%instanceElement)
518       Returns a blessed object. Used internally for wrapping
519       describe_instance_status nextToken calls
520
521       InstanceStatusElement (required)
522           The instance status element we want to build out and return
523
524       Returns a Net::Amazon::EC2::InstanceStatuses object
525
526   describe_instance_attribute(%params)
527       Returns information about an attribute of an instance. Only one
528       attribute can be specified per call.
529
530       InstanceId (required)
531           The instance id we want to describe the attributes of.
532
533       Attribute (required)
534           The attribute we want to describe. Valid values are:
535
536           •   instanceType
537
538           •   kernel
539
540           •   ramdisk
541
542           •   userData
543
544           •   disableApiTermination
545
546           •   ebsOptimized
547
548           •   instanceInitiatedShutdownBehavior
549
550           •   rootDeviceName
551
552           •   sourceDestCheck
553
554           •   blockDeviceMapping
555
556       Returns a Net::Amazon::EC2::DescribeInstanceAttributeResponse object
557
558   describe_key_pairs(%params)
559       This method describes the keypairs available on this account. It takes
560       the following parameter:
561
562       KeyName (optional)
563           The name of the key to be described. Can be either a scalar or an
564           array ref.
565
566       Returns an array ref of Net::Amazon::EC2::DescribeKeyPairsResponse
567       objects
568
569   describe_regions(%params)
570       Describes EC2 regions that are currently available to launch instances
571       in for this account.
572
573       RegionName (optional)
574           The name of the region(s) to be described. Can be either a scalar
575           or an array ref.
576
577       Returns an array ref of Net::Amazon::EC2::Region objects
578
579   describe_reserved_instances(%params)
580       Describes Reserved Instances that you purchased.
581
582       ReservedInstancesId (optional)
583           The reserved instance id(s) to be described. Can be either a scalar
584           or an array ref.
585
586       Returns an array ref of Net::Amazon::EC2::ReservedInstance objects
587
588   describe_reserved_instances_offerings(%params)
589       Describes Reserved Instance offerings that are available for purchase.
590       With Amazon EC2 Reserved Instances, you purchase the right to launch
591       Amazon EC2 instances for a period of time (without getting insufficient
592       capacity errors) and pay a lower usage rate for the actual time used.
593
594       ReservedInstancesOfferingId (optional)
595           ID of the Reserved Instances to describe.
596
597       InstanceType (optional)
598           The instance type. The default is m1.small. Amazon frequently
599           updates their instance types.
600
601           See http://aws.amazon.com/ec2/instance-types
602
603       AvailabilityZone (optional)
604           The Availability Zone in which the Reserved Instance can be used.
605
606       ProductDescription (optional)
607           The Reserved Instance description.
608
609       Returns an array ref of Net::Amazon::EC2::ReservedInstanceOffering
610       objects
611
612   describe_security_groups(%params)
613       This method describes the security groups available to this account. It
614       takes the following parameter:
615
616       GroupName (optional)
617           The name of the security group(s) to be described. Can be either a
618           scalar or an array ref.
619
620       GroupId (optional)
621           The id of the security group(s) to be described. Can be either a
622           scalar or an array ref.
623
624       Returns an array ref of Net::Amazon::EC2::SecurityGroup objects
625
626   describe_snapshot_attribute(%params)
627       Describes the snapshots attributes related to the snapshot in question.
628       It takes the following arguments:
629
630       SnapshotId (optional)
631           Either a scalar or array ref of snapshot id's can be passed in. If
632           this isn't passed in it will describe the attributes of all the
633           current snapshots.
634
635       Attribute (required)
636           The attribute to describe, currently, the only valid attribute is
637           createVolumePermission.
638
639       Returns a Net::Amazon::EC2::SnapshotAttribute object.
640
641   describe_snapshots(%params)
642       Describes the snapshots available to the user. It takes the following
643       arguments:
644
645       SnapshotId (optional)
646           Either a scalar or array ref of snapshot id's can be passed in. If
647           this isn't passed in it will describe all the current snapshots.
648
649       Owner (optional)
650           The owner of the snapshot.
651
652       RestorableBy (optional)
653           A user who can create volumes from the snapshot.
654
655       Filter (optional)
656           The filters for only the matching snapshots to be 'described'.  A
657           filter tuple is an arrayref constsing one key and one or more
658           values.  The option takes one filter tuple, or an arrayref of
659           multiple filter tuples.
660
661       Returns an array ref of Net::Amazon::EC2::Snapshot objects.
662
663   describe_volumes(%params)
664       Describes the volumes currently created. It takes the following
665       arguments:
666
667       VolumeId (optional)
668           Either a scalar or array ref of volume id's can be passed in. If
669           this isn't passed in it will describe all the current volumes.
670
671       Returns an array ref of Net::Amazon::EC2::Volume objects.
672
673   describe_subnets(%params)
674       This method describes the subnets on this account. It takes the
675       following parameters:
676
677       SubnetId (optional)
678           The id of a subnet to be described.  Can either be a scalar or an
679           array ref.
680
681       Filter.Name (optional)
682           The name of the Filter.Name to be described. Can be either a scalar
683           or an array ref.  See
684           http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeSubnets.html
685           for available filters.
686
687       Filter.Value (optional)
688           The name of the Filter.Value to be described. Can be either a
689           scalar or an array ref.
690
691       Returns an array ref of Net::Amazon::EC2::DescribeSubnetResponse
692       objects
693
694   describe_tags(%params)
695       This method describes the tags available on this account. It takes the
696       following parameter:
697
698       Filter.Name (optional)
699           The name of the Filter.Name to be described. Can be either a scalar
700           or an array ref.
701
702       Filter.Value (optional)
703           The name of the Filter.Value to be described. Can be either a
704           scalar or an array ref.
705
706       Returns an array ref of Net::Amazon::EC2::DescribeTags objects
707
708   detach_volume(%params)
709       Detach a volume from an instance.
710
711       VolumeId (required)
712           The volume id you wish to detach.
713
714       InstanceId (optional)
715           The instance id you wish to detach from.
716
717       Device (optional)
718           The device the volume was attached as.
719
720       Force (optional)
721           A boolean for if to forcibly detach the volume from the instance.
722           WARNING: This can lead to data loss or a corrupted file system.
723                   Use this option only as a last resort to detach a volume
724                   from a failed instance.  The instance will not have an
725                   opportunity to flush file system caches nor file system
726                   meta data.
727
728       Returns a Net::Amazon::EC2::Attachment object containing the resulting
729       volume status.
730
731   disassociate_address(%params)
732       Disassociates an elastic IP address with an instance. It takes the
733       following arguments:
734
735       PublicIp (conditional)
736           The IP address to disassociate, mandatory to remove an IP from a
737           EC2-classic instance.
738
739       AssociationId (conditional)
740           The Association ID of an IP address, mandatory to remove an IP from
741           a VPC instance.
742
743       Returns true if the disassociation succeeded.
744
745   get_console_output(%params)
746       This method gets the output from the virtual console for an instance.
747       It takes the following parameters:
748
749       InstanceId (required)
750           A scalar containing a instance id.
751
752       Returns a Net::Amazon::EC2::ConsoleOutput object or "undef" if there is
753       no new output. (This can happen in cases where the console output has
754       not changed since the last call.)
755
756   get_password_data(%params)
757       Retrieves the encrypted administrator password for the instances
758       running Windows. This procedure is not applicable for Linux and UNIX
759       instances.
760
761       InstanceId (required)
762           The Instance Id for which to retrieve the password.
763
764       Returns a Net::Amazon::EC2::InstancePassword object
765
766   modify_image_attribute(%params)
767       This method modifies attributes of an machine image.
768
769       ImageId (required)
770           The AMI to modify the attributes of.
771
772       Attribute (required)
773           The attribute you wish to modify, right now the attributes you can
774           modify are launchPermission and productCodes
775
776       OperationType (required for launchPermission)
777           The operation you wish to perform on the attribute. Right now just
778           'add' and 'remove' are supported.
779
780       UserId (required for launchPermission)
781           User Id's you wish to add/remove from the attribute.
782
783       UserGroup (required for launchPermission)
784           Groups you wish to add/remove from the attribute.  Currently there
785           is only one User Group available 'all' for all Amazon EC2
786           customers.
787
788       ProductCode (required for productCodes)
789           Attaches a product code to the AMI. Currently only one product code
790           can be assigned to the AMI.  Once this is set it cannot be changed
791           or reset.
792
793       Returns 1 if the modification succeeds.
794
795   modify_instance_attribute(%params)
796       Modify an attribute of an instance.
797
798       InstanceId (required)
799           The instance id we want to modify the attributes of.
800
801       Attribute (required)
802           The attribute we want to modify. Valid values are:
803
804           •   instanceType
805
806           •   kernel
807
808           •   ramdisk
809
810           •   userData
811
812           •   disableApiTermination
813
814           •   instanceInitiatedShutdownBehavior
815
816           •   rootDeviceName
817
818           •   blockDeviceMapping
819
820       Value (required)
821           The value to set the attribute to.
822
823           You may also pass a hashref with one or more keys and values. This
824           hashref will be flattened and passed to AWS.
825
826           For example:
827
828                   $ec2->modify_instance_attribute(
829                           'InstanceId' => $id,
830                           'Attribute' => 'blockDeviceMapping',
831                           'Value' => {
832                                   'BlockDeviceMapping.1.DeviceName' => '/dev/sdf1',
833                                   'BlockDeviceMapping.1.Ebs.DeleteOnTermination' => 'true',
834                           }
835                   );
836
837       Returns 1 if the modification succeeds.
838
839   modify_snapshot_attribute(%params)
840       This method modifies attributes of a snapshot.
841
842       SnapshotId (required)
843           The snapshot id to modify the attributes of.
844
845       UserId (optional)
846           User Id you wish to add/remove create volume permissions for.
847
848       UserGroup (optional)
849           User Id you wish to add/remove create volume permissions for. To
850           make the snapshot createable by all set the UserGroup to "all".
851
852       Attribute (required)
853           The attribute you wish to modify, right now the only attribute you
854           can modify is "CreateVolumePermission"
855
856       OperationType (required)
857           The operation you wish to perform on the attribute. Right now just
858           'add' and 'remove' are supported.
859
860       Returns 1 if the modification succeeds.
861
862   monitor_instances(%params)
863       Enables monitoring for a running instance. For more information, refer
864       to the Amazon CloudWatch Developer Guide.
865
866       InstanceId (required)
867           The instance id(s) to monitor. Can be a scalar or an array ref
868
869       Returns an array ref of Net::Amazon::EC2::MonitoredInstance objects
870
871   purchase_reserved_instances_offering(%params)
872       Purchases a Reserved Instance for use with your account. With Amazon
873       EC2 Reserved Instances, you purchase the right to launch Amazon EC2
874       instances for a period of time (without getting insufficient capacity
875       errors) and pay a lower usage rate for the actual time used.
876
877       ReservedInstancesOfferingId (required)
878           ID of the Reserved Instances to describe. Can be either a scalar or
879           an array ref.
880
881       InstanceCount (optional)
882           The number of Reserved Instances to purchase (default is 1). Can be
883           either a scalar or an array ref.
884
885           NOTE NOTE NOTE, the array ref needs to line up with the
886           InstanceCount if you want to pass that in, so that the right number
887           of instances are started of the right instance offering
888
889       Returns 1 if the reservations succeeded.
890
891   reboot_instances(%params)
892       This method reboots an instance.  It takes the following parameters:
893
894       InstanceId (required)
895           Instance Id of the instance you wish to reboot. Can be either a
896           scalar or array ref of instances to reboot.
897
898       Returns 1 if the reboot succeeded.
899
900   register_image(%params)
901       This method registers an AMI on the EC2. It takes the following
902       parameter:
903
904       ImageLocation (optional)
905           The location of the AMI manifest on S3
906
907       Name (required)
908           The name of the AMI that was provided during image creation.
909
910       Description (optional)
911           The description of the AMI.
912
913       Architecture (optional)
914           The architecture of the image. Either i386 or x86_64
915
916       KernelId (optional)
917           The ID of the kernel to select.
918
919       RamdiskId (optional)
920           The ID of the RAM disk to select. Some kernels require additional
921           drivers at launch.
922
923       RootDeviceName (optional)
924           The root device name (e.g., /dev/sda1).
925
926       BlockDeviceMapping (optional)
927           This needs to be a data structure like this:
928
929            [
930                   {
931                           deviceName      => "/dev/sdh", (optional)
932                           virtualName     => "ephemerel0", (optional)
933                           noDevice        => "/dev/sdl", (optional),
934                           ebs                     => {
935                                   snapshotId                      => "snap-0000", (optional)
936                                   volumeSize                      => "20", (optional)
937                                   deleteOnTermination     => "false", (optional)
938                           },
939                   },
940                   ...
941            ]
942
943       Returns the image id of the new image on EC2.
944
945   release_address(%params)
946       Releases an allocated IP address. It takes the following arguments:
947
948       PublicIp (required)
949           The IP address to release
950
951       Returns true if the releasing succeeded.
952
953   reset_image_attribute(%params)
954       This method resets an attribute for an AMI to its default state (NOTE:
955       product codes cannot be reset).  It takes the following parameters:
956
957       ImageId (required)
958           The image id of the AMI you wish to reset the attributes on.
959
960       Attribute (required)
961           The attribute you want to reset.
962
963       Returns 1 if the attribute reset succeeds.
964
965   reset_instance_attribute(%params)
966       Reset an attribute of an instance. Only one attribute can be specified
967       per call.
968
969       InstanceId (required)
970           The instance id we want to reset the attributes of.
971
972       Attribute (required)
973           The attribute we want to reset. Valid values are:
974
975           •   kernel
976
977           •   ramdisk
978
979       Returns 1 if the reset succeeds.
980
981   reset_snapshot_attribute(%params)
982       This method resets an attribute for an snapshot to its default state.
983
984       It takes the following parameters:
985
986       SnapshotId (required)
987           The snapshot id of the snapshot you wish to reset the attributes
988           on.
989
990       Attribute (required)
991           The attribute you want to reset (currently "CreateVolumePermission"
992           is the only valid attribute).
993
994       Returns 1 if the attribute reset succeeds.
995
996   revoke_security_group_ingress(%params)
997       This method revoke permissions to a security group.  It takes the
998       following parameters:
999
1000       GroupName (required)
1001           The name of the group to revoke security rules from.
1002
1003       SourceSecurityGroupName (required when revoking a user and group
1004       together)
1005           Name of the group to revoke access from.
1006
1007       SourceSecurityGroupOwnerId (required when revoking a user and group
1008       together)
1009           Owner of the group to revoke access from.
1010
1011       IpProtocol (required when revoking access from a CIDR)
1012           IP Protocol of the rule you are revoking access from (TCP, UDP, or
1013           ICMP)
1014
1015       FromPort (required when revoking access from a CIDR)
1016           Beginning of port range to revoke access from.
1017
1018       ToPort (required when revoking access from a CIDR)
1019           End of port range to revoke access from.
1020
1021       CidrIp (required when revoking access from a CIDR)
1022           The CIDR IP space we are revoking access from.
1023
1024       Revoking a rule can be done in two ways: revoking a source group name +
1025       source group owner id, or, by Protocol + start port + end port + CIDR
1026       IP.  The two are mutally exclusive.
1027
1028       Returns 1 if rule is revoked successfully.
1029
1030   run_instances(%params)
1031       This method will start instance(s) of AMIs on EC2. The parameters
1032       indicate which AMI to instantiate and how many / what properties they
1033       have:
1034
1035       ImageId (required)
1036           The image id you want to start an instance of.
1037
1038       MinCount (required)
1039           The minimum number of instances to start.
1040
1041       MaxCount (required)
1042           The maximum number of instances to start.
1043
1044       KeyName (optional)
1045           The keypair name to associate this instance with.  If omitted, will
1046           use your default keypair.
1047
1048       SecurityGroup (optional)
1049           An scalar or array ref. Will associate this instance with the group
1050           names passed in.  If omitted, will be associated with the default
1051           security group.
1052
1053       SecurityGroupId (optional)
1054           An scalar or array ref. Will associate this instance with the group
1055           ids passed in.  If omitted, will be associated with the default
1056           security group.
1057
1058       AdditionalInfo (optional)
1059           Specifies additional information to make available to the
1060           instance(s).
1061
1062       UserData (optional)
1063           Optional data to pass into the instance being started.  Needs to be
1064           base64 encoded.
1065
1066       InstanceType (optional)
1067           Specifies the type of instance to start.
1068
1069           See http://aws.amazon.com/ec2/instance-types
1070
1071           The options are:
1072
1073           m1.small (default)
1074               1 EC2 Compute Unit (1 virtual core with 1 EC2 Compute Unit).
1075               32-bit or 64-bit, 1.7GB RAM, 160GB disk
1076
1077           m1.medium Medium Instance
1078               2 EC2 Compute Units (1 virtual core with 2 EC2 Compute Unit),
1079               32-bit or 64-bit, 3.75GB RAM, 410GB disk
1080
1081           m1.large: Standard Large Instance
1082               4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units
1083               each). 64-bit, 7.5GB RAM, 850GB disk
1084
1085           m1.xlarge: Standard Extra Large Instance
1086               8 EC2 Compute Units (4 virtual cores with 2 EC2 Compute Units
1087               each). 64-bit, 15GB RAM, 1690GB disk
1088
1089           t1.micro Micro Instance
1090               Up to 2 EC2 Compute Units (for short periodic bursts), 32-bit
1091               or 64-bit, 613MB RAM, EBS storage only
1092
1093           c1.medium: High-CPU Medium Instance
1094               5 EC2 Compute Units (2 virtual cores with 2.5 EC2 Compute Units
1095               each). 32-bit or 64-bit, 1.7GB RAM, 350GB disk
1096
1097           c1.xlarge: High-CPU Extra Large Instance
1098               20 EC2 Compute Units (8 virtual cores with 2.5 EC2 Compute
1099               Units each). 64-bit, 7GB RAM, 1690GB disk
1100
1101           m2.2xlarge High-Memory Double Extra Large Instance
1102               13 EC2 Compute Units (4 virtual cores with 3.25 EC2 Compute
1103               Units each). 64-bit, 34.2GB RAM, 850GB disk
1104
1105           m2.4xlarge High-Memory Quadruple Extra Large Instance
1106               26 EC2 Compute Units (8 virtual cores with 3.25 EC2 Compute
1107               Units each). 64-bit, 68.4GB RAM, 1690GB disk
1108
1109           cc1.4xlarge Cluster Compute Quadruple Extra Large Instance
1110               33.5 EC2 Compute Units (2 x Intel Xeon X5570, quad-core
1111               "Nehalem" architecture), 64-bit, 23GB RAM, 1690GB disk, 10Gbit
1112               Ethernet
1113
1114           cc1.8xlarge Cluster Compute Eight Extra Large Instance
1115               88 EC2 Compute Units (2 x Intel Xeon E5-2670, eight-core "Sandy
1116               Bridge" architecture), 64-bit, 60.5GB RAM, 3370GB disk, 10Gbit
1117               Ethernet
1118
1119           cg1.4xlarge Cluster GPU Quadruple Extra Large Instance
1120               33.5 EC2 Compute Units (2 x Intel Xeon X5570, quad-core
1121               "Nehalem" architecture), 64-bit, 22GB RAM 1690GB disk, 10Gbit
1122               Ethernet, 2 x NVIDIA Tesla "Fermi" M2050 GPUs
1123
1124           hi1.4xlarge High I/O Quadruple Extra Large Instance
1125               35 EC2 Compute Units (16 virtual cores), 60.5GB RAM, 64-bit, 2
1126               x 1024GB SSD disk, 10Gbit Ethernet
1127
1128       Placement.AvailabilityZone (optional)
1129           The availability zone you want to run the instance in
1130
1131       KernelId (optional)
1132           The id of the kernel you want to launch the instance with
1133
1134       RamdiskId (optional)
1135           The id of the ramdisk you want to launch the instance with
1136
1137       BlockDeviceMapping.VirtualName (optional)
1138           This is the virtual name for a blocked device to be attached, may
1139           pass in a scalar or arrayref
1140
1141       BlockDeviceMapping.DeviceName (optional)
1142           This is the device name for a block device to be attached, may pass
1143           in a scalar or arrayref
1144
1145       BlockDeviceMapping.Ebs.VolumeSize (optional)
1146           Specifies the size of the root block device as an integer (GB). If
1147           used, required that "BlockDeviceMapping.DeviceName" also be
1148           specified. One may pass in a scalar or arrayref. This parameter
1149           will override the disk size settings implied by the "InstanceType",
1150           if used.
1151
1152           Additional volume related parameters include,
1153
1154           BlockDeviceMapping.Ebs.SnapshotId
1155               May pass in a scalar or arrayref.
1156
1157           BlockDeviceMapping.Ebs.VolumeType
1158               May pass in a scalar or arrayref.
1159
1160           BlockDeviceMapping.Ebs.DeleteOnTermination
1161               May pass in a scalar or arrayref.
1162
1163       Encoding (optional)
1164           The encoding.
1165
1166       Version (optional)
1167           The version.
1168
1169       Monitoring.Enabled (optional)
1170           Enables monitoring for this instance.
1171
1172       SubnetId (optional)
1173           Specifies the subnet ID within which to launch the instance(s) for
1174           Amazon Virtual Private Cloud.
1175
1176       ClientToken (optional)
1177           Specifies the idempotent instance id.
1178
1179       EbsOptimized (optional)
1180           Whether the instance is optimized for EBS I/O.
1181
1182       PrivateIpAddress (optional)
1183           Specifies the private IP address to use when launching an Amazon
1184           VPC instance.
1185
1186       IamInstanceProfile.Name (optional)
1187           Specifies the IAM profile to associate with the launched
1188           instance(s).  This is the name of the role.
1189
1190       IamInstanceProfile.Arn (optional)
1191           Specifies the IAM profile to associate with the launched
1192           instance(s).  This is the ARN of the profile.
1193
1194       Returns a Net::Amazon::EC2::ReservationInfo object
1195
1196   start_instances(%params)
1197       Starts an instance that uses an Amazon EBS volume as its root device.
1198
1199       InstanceId (required)
1200           Either a scalar or an array ref can be passed in (containing
1201           instance ids to be started).
1202
1203       Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
1204
1205   stop_instances(%params)
1206       Stops an instance that uses an Amazon EBS volume as its root device.
1207
1208       InstanceId (required)
1209           Either a scalar or an array ref can be passed in (containing
1210           instance ids to be stopped).
1211
1212       Force (optional)
1213           If set to true, forces the instance to stop. The instance will not
1214           have an opportunity to flush file system caches nor file system
1215           meta data. If you use this option, you must perform file system
1216           check and repair procedures. This option is not recommended for
1217           Windows instances.
1218
1219           The default is false.
1220
1221       Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
1222
1223   terminate_instances(%params)
1224       This method shuts down instance(s) passed into it. It takes the
1225       following parameter:
1226
1227       InstanceId (required)
1228           Either a scalar or an array ref can be passed in (containing
1229           instance ids)
1230
1231       Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
1232
1233   unmonitor_instances(%params)
1234       Disables monitoring for a running instance. For more information, refer
1235       to the Amazon CloudWatch Developer Guide.
1236
1237       InstanceId (required)
1238           The instance id(s) to monitor. Can be a scalar or an array ref
1239
1240       Returns an array ref of Net::Amazon::EC2::MonitoredInstance objects
1241

TESTING

1243       Set AWS_ACCESS_KEY_ID and SECRET_ACCESS_KEY environment variables to
1244       run the live tests.  Note: because the live tests start an instance
1245       (and kill it) in both the tests and backwards compat tests there will
1246       be 2 hours of machine instance usage charges (since there are 2
1247       instances started) which as of February 1st, 2010 costs a total of
1248       $0.17 USD
1249
1250       Important note about the windows-only methods.  These have not been
1251       well tested as I do not run windows-based instances, so exercise
1252       caution in using these.
1253

BUGS

1255       Please report any bugs or feature requests to "bug-net-amazon-ec2 at
1256       rt.cpan.org", or through the web interface at
1257       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Amazon-EC2>.  I
1258       will be notified, and then you'll automatically be notified of progress
1259       on your bug as I make changes.
1260

AUTHOR

1262       Jeff Kim <cpan@chosec.com>
1263

CONTRIBUTORS

1265       John McCullough and others as listed in the Changelog
1266

MAINTAINER

1268       The current maintainer is Mark Allen "<mallen@cpan.org>"
1269
1271       Copyright (c) 2006-2010 Jeff Kim.
1272
1273       Copyright (c) 2012 Mark Allen.
1274
1275       This program is free software; you can redistribute it and/or modify it
1276       under the same terms as Perl itself.
1277

SEE ALSO

1279       Amazon EC2 API:
1280       <http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/>
1281
1282
1283
1284perl v5.38.0                      2023-07-21               Net::Amazon::EC2(3)
Impressum