1Net::Amazon::EC2(3) User Contributed Perl Documentation Net::Amazon::EC2(3)
2
6 Net::Amazon::EC2 - Perl interface to the Amazon Elastic Compute Cloud
7 (EC2) environment.
8
10 EC2 Query API version: '2014-06-15'
11
13 use Net::Amazon::EC2;
14 my $ec2 = Net::Amazon::EC2->new(
16 AWSAccessKeyId => 'PUBLIC_KEY_HERE',
17 SecretAccessKey => 'SECRET_KEY_HERE',
18 signature_version => 4,
19 );
20 # Start 1 new instance from AMI: ami-XXXXXXXX
22 my $instance = $ec2->run_instances(ImageId => 'ami-XXXXXXXX', MinCount => 1, MaxCount => 1);
23 my $running_instances = $ec2->describe_instances;
25 foreach my $reservation (@$running_instances) {
27 foreach my $instance ($reservation->instances_set) {
28 print $instance->instance_id . "\n";
29 }
30 }
31 my $instance_id = $instance->instances_set->[0]->instance_id;
33 print "$instance_id\n";
35 # Terminate instance
37 my $result = $ec2->terminate_instances(InstanceId => $instance_id);
39 If an error occurs while communicating with EC2, these methods will
41 throw a Net::Amazon::EC2::Errors exception.
42
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
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 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 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 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 region (optional)
68 The region to run the API requests through. Defaults to us-east-1.
69 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 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 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 If you want/need the old behavior, set this attribute to a true
87 value.
88
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 Returns the IP address obtained.
95 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 Returns the allocationId of the allocated address.
101 associate_address(%params)
103 Associates an elastic IP address with an instance. It takes the
104 following arguments:
105 InstanceId (required)
107 The instance id you wish to associate the IP address with
108 PublicIp (optional)
110 The IP address. Used for allocating addresses to EC2-classic
111 instances.
112 AllocationId (optional)
114 The allocation ID. Used for allocating address to VPC instances.
115 Returns true if the association succeeded.
117 attach_volume(%params)
119 Attach a volume to an instance.
120 VolumeId (required)
122 The volume id you wish to attach.
123 InstanceId (required)
125 The instance id you wish to attach the volume to.
126 Device (required)
128 The device id you want the volume attached as.
129 Returns a Net::Amazon::EC2::Attachment object containing the resulting
131 volume status.
132 authorize_security_group_ingress(%params)
134 This method adds permissions to a security group. It takes the
135 following parameters:
136 GroupName (required)
138 The name of the group to add security rules to.
139 SourceSecurityGroupName (required when authorizing a user and group
141 together)
142 Name of the group to add access for.
143 SourceSecurityGroupOwnerId (required when authorizing a user and group
145 together)
146 Owner of the group to add access for.
147 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 FromPort (required when adding access for a CIDR)
153 Beginning of port range to add access for.
154 ToPort (required when adding access for a CIDR)
156 End of port range to add access for.
157 CidrIp (required when adding access for a CIDR)
159 The CIDR IP space we are adding access for.
160 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 Returns 1 if rule is added successfully.
166 bundle_instance(%params)
168 Bundles the Windows instance. This procedure is not applicable for
169 Linux and UNIX instances.
170 NOTE NOTE NOTE This is not well tested as I don't run windows instances
172 InstanceId (required)
174 The ID of the instance to bundle.
175 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 Storage.S3.Prefix (required)
183 Specifies the beginning of the file name of the AMI.
184 Storage.S3.AWSAccessKeyId (required)
186 The Access Key ID of the owner of the Amazon S3 bucket.
187 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 Storage.S3.UploadPolicySignature (required)
193 The signature of the Base64 encoded JSON document.
194 JSON Parameters: (all are required)
196 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 Returns a Net::Amazon::EC2::BundleInstanceResponse object
204 cancel_bundle_task(%params)
206 Cancels the bundle task. This procedure is not applicable for Linux and
207 UNIX instances.
208 BundleId (required)
210 The ID of the bundle task to cancel.
211 Returns a Net::Amazon::EC2::BundleInstanceResponse object
213 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 ProductCode (required)
219 The Product Code to check
220 InstanceId (required)
222 The Instance Id to check
223 Returns a Net::Amazon::EC2::ConfirmProductInstanceResponse object
225 create_image(%params)
227 Creates an AMI that uses an Amazon EBS root device from a "running" or
228 "stopped" instance.
229 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 InstanceId (required)
235 The ID of the instance.
236 Name (required)
238 The name of the AMI that was provided during image creation.
239 Note that the image name has the following constraints:
241 3-128 alphanumeric characters, parenthesis, commas, slashes,
243 dashes, or underscores.
244 Description (optional)
246 The description of the AMI that was provided during image creation.
247 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 BlockDeviceMapping (optional)
257 Array ref of the device names exposed to the instance.
258 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 BlockDeviceMapping => [
264 '/dev/sda=:256:true:standard',
265 '/dev/sdb=none',
266 '/dev/sdc=ephemeral0',
267 '/dev/sdd=ephemeral1',
268 ],
269 Returns the ID of the AMI created.
271 create_key_pair(%params)
273 Creates a new 2048 bit key pair, taking the following parameter:
274 KeyName (required)
276 A name for this key. Should be unique.
277 Returns a Net::Amazon::EC2::KeyPair object
279 create_security_group(%params)
281 This method creates a new security group. It takes the following
282 parameters:
283 GroupName (required)
285 The name of the new group to create.
286 GroupDescription (required)
288 A short description of the new group.
289 Returns 1 if the group creation succeeds.
291 create_snapshot(%params)
293 Create a snapshot of a volume. It takes the following arguments:
294 VolumeId (required)
296 The volume id of the volume you want to take a snapshot of.
297 Description (optional)
299 Description of the Amazon EBS snapshot.
300 Returns a Net::Amazon::EC2::Snapshot object of the newly created
302 snapshot.
303 create_tags(%params)
305 Creates tags.
306 ResourceId (required)
308 The ID of the resource to create tags. Can be a scalar or arrayref
309 Tags (required)
311 Hashref where keys and values will be set on all resources given in
312 the first element.
313 Returns true if the tag creation succeeded.
315 create_volume(%params)
317 Creates a volume.
318 Size (required)
320 The size in GiB ( 1024^3 ) of the volume you want to create.
321 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 AvailabilityZone (required)
327 The availability zone to create the volume in.
328 VolumeType (optional)
330 The volume type: 'standard', 'gp2', or 'io1'. Defaults to
331 'standard'.
332 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 Required when the volume type is io1; not used otherwise.
340 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 Returns a Net::Amazon::EC2::Volume object containing the resulting
348 volume status
349 delete_key_pair(%params)
351 This method deletes a keypair. Takes the following parameter:
352 KeyName (required)
354 The name of the key to delete.
355 Returns 1 if the key was successfully deleted.
357 delete_security_group(%params)
359 This method deletes a security group. It takes the following
360 parameter:
361 GroupName (required)
363 The name of the security group to delete.
364 Returns 1 if the delete succeeded.
366 delete_snapshot(%params)
368 Deletes the snapshots passed in. It takes the following arguments:
369 SnapshotId (required)
371 A snapshot id can be passed in. Will delete the corresponding
372 snapshot.
373 Returns true if the deleting succeeded.
375 delete_volume(%params)
377 Delete a volume.
378 VolumeId (required)
380 The volume id you wish to delete.
381 Returns true if the deleting succeeded.
383 delete_tags(%params)
385 Delete tags.
386 ResourceId (required)
388 The ID of the resource to delete tags
389 Tag.Key (required)
391 Key for a tag, may pass in a scalar or arrayref.
392 Tag.Value (required)
394 Value for a tag, may pass in a scalar or arrayref.
395 Returns true if the releasing succeeded.
397 deregister_image(%params)
399 This method will deregister an AMI. It takes the following parameter:
400 ImageId (required)
402 The image id of the AMI you want to deregister.
403 Returns 1 if the deregistering succeeded
405 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 PublicIp (optional)
411 The IP address to describe. Can be either a scalar or an array ref.
412 Returns an array ref of Net::Amazon::EC2::DescribeAddress objects
414 describe_availability_zones(%params)
416 This method describes the availability zones currently available to
417 choose from. It takes the following arguments:
418 ZoneName (optional)
420 The zone name to describe. Can be either a scalar or an array ref.
421 Returns an array ref of Net::Amazon::EC2::AvailabilityZone objects
423 describe_bundle_tasks(%params)
425 Describes current bundling tasks. This procedure is not applicable for
426 Linux and UNIX instances.
427 BundleId (optional)
429 The optional ID of the bundle task to describe.
430 Returns a array ref of Net::Amazon::EC2::BundleInstanceResponse objects
432 describe_image_attributes(%params)
434 This method pulls a list of attributes for the image id specified
435 ImageId (required)
437 A scalar containing the image you want to get the list of
438 attributes for.
439 Attribute (required)
441 A scalar containing the attribute to describe.
442 Valid attributes are:
444 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 Returns a Net::Amazon::EC2::DescribeImageAttribute object
455 * 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 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 ImageId (optional)
466 Either a scalar or an array ref can be passed in, will cause just
467 these AMIs to be 'described'
468 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 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 Returns an array ref of Net::Amazon::EC2::DescribeImagesResponse
481 objects
482 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 InstanceId (optional)
489 Either a scalar or an array ref can be passed in, will cause just
490 these instances to be 'described'
491 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 Returns an array ref of Net::Amazon::EC2::ReservationInfo objects
499 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 InstanceId (optional)
506 Either a scalar or an array ref can be passed in, will cause just
507 these instances to be 'described'
508 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 Returns an array ref of Net::Amazon::EC2::InstanceStatuses objects
516 _create_describe_instance_status(%instanceElement)
518 Returns a blessed object. Used internally for wrapping
519 describe_instance_status nextToken calls
520 InstanceStatusElement (required)
522 The instance status element we want to build out and return
523 Returns a Net::Amazon::EC2::InstanceStatuses object
525 describe_instance_attribute(%params)
527 Returns information about an attribute of an instance. Only one
528 attribute can be specified per call.
529 InstanceId (required)
531 The instance id we want to describe the attributes of.
532 Attribute (required)
534 The attribute we want to describe. Valid values are:
535 • instanceType
537 • kernel
539 • ramdisk
541 • userData
543 • disableApiTermination
545 • ebsOptimized
547 • instanceInitiatedShutdownBehavior
549 • rootDeviceName
551 • sourceDestCheck
553 • blockDeviceMapping
555 Returns a Net::Amazon::EC2::DescribeInstanceAttributeResponse object
557 describe_key_pairs(%params)
559 This method describes the keypairs available on this account. It takes
560 the following parameter:
561 KeyName (optional)
563 The name of the key to be described. Can be either a scalar or an
564 array ref.
565 Returns an array ref of Net::Amazon::EC2::DescribeKeyPairsResponse
567 objects
568 describe_regions(%params)
570 Describes EC2 regions that are currently available to launch instances
571 in for this account.
572 RegionName (optional)
574 The name of the region(s) to be described. Can be either a scalar
575 or an array ref.
576 Returns an array ref of Net::Amazon::EC2::Region objects
578 describe_reserved_instances(%params)
580 Describes Reserved Instances that you purchased.
581 ReservedInstancesId (optional)
583 The reserved instance id(s) to be described. Can be either a scalar
584 or an array ref.
585 Returns an array ref of Net::Amazon::EC2::ReservedInstance objects
587 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 ReservedInstancesOfferingId (optional)
595 ID of the Reserved Instances to describe.
596 InstanceType (optional)
598 The instance type. The default is m1.small. Amazon frequently
599 updates their instance types.
600 See http://aws.amazon.com/ec2/instance-types
602 AvailabilityZone (optional)
604 The Availability Zone in which the Reserved Instance can be used.
605 ProductDescription (optional)
607 The Reserved Instance description.
608 Returns an array ref of Net::Amazon::EC2::ReservedInstanceOffering
610 objects
611 describe_security_groups(%params)
613 This method describes the security groups available to this account. It
614 takes the following parameter:
615 GroupName (optional)
617 The name of the security group(s) to be described. Can be either a
618 scalar or an array ref.
619 GroupId (optional)
621 The id of the security group(s) to be described. Can be either a
622 scalar or an array ref.
623 Returns an array ref of Net::Amazon::EC2::SecurityGroup objects
625 describe_snapshot_attribute(%params)
627 Describes the snapshots attributes related to the snapshot in question.
628 It takes the following arguments:
629 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 Attribute (required)
636 The attribute to describe, currently, the only valid attribute is
637 createVolumePermission.
638 Returns a Net::Amazon::EC2::SnapshotAttribute object.
640 describe_snapshots(%params)
642 Describes the snapshots available to the user. It takes the following
643 arguments:
644 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 Owner (optional)
650 The owner of the snapshot.
651 RestorableBy (optional)
653 A user who can create volumes from the snapshot.
654 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 Returns an array ref of Net::Amazon::EC2::Snapshot objects.
662 describe_volumes(%params)
664 Describes the volumes currently created. It takes the following
665 arguments:
666 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 Returns an array ref of Net::Amazon::EC2::Volume objects.
672 describe_subnets(%params)
674 This method describes the subnets on this account. It takes the
675 following parameters:
676 SubnetId (optional)
678 The id of a subnet to be described. Can either be a scalar or an
679 array ref.
680 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 Filter.Value (optional)
688 The name of the Filter.Value to be described. Can be either a
689 scalar or an array ref.
690 Returns an array ref of Net::Amazon::EC2::DescribeSubnetResponse
692 objects
693 describe_tags(%params)
695 This method describes the tags available on this account. It takes the
696 following parameter:
697 Filter.Name (optional)
699 The name of the Filter.Name to be described. Can be either a scalar
700 or an array ref.
701 Filter.Value (optional)
703 The name of the Filter.Value to be described. Can be either a
704 scalar or an array ref.
705 Returns an array ref of Net::Amazon::EC2::DescribeTags objects
707 detach_volume(%params)
709 Detach a volume from an instance.
710 VolumeId (required)
712 The volume id you wish to detach.
713 InstanceId (optional)
715 The instance id you wish to detach from.
716 Device (optional)
718 The device the volume was attached as.
719 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 Returns a Net::Amazon::EC2::Attachment object containing the resulting
729 volume status.
730 disassociate_address(%params)
732 Disassociates an elastic IP address with an instance. It takes the
733 following arguments:
734 PublicIp (conditional)
736 The IP address to disassociate, mandatory to remove an IP from a
737 EC2-classic instance.
738 AssociationId (conditional)
740 The Association ID of an IP address, mandatory to remove an IP from
741 a VPC instance.
742 Returns true if the disassociation succeeded.
744 get_console_output(%params)
746 This method gets the output from the virtual console for an instance.
747 It takes the following parameters:
748 InstanceId (required)
750 A scalar containing a instance id.
751 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 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 InstanceId (required)
762 The Instance Id for which to retrieve the password.
763 Returns a Net::Amazon::EC2::InstancePassword object
765 modify_image_attribute(%params)
767 This method modifies attributes of an machine image.
768 ImageId (required)
770 The AMI to modify the attributes of.
771 Attribute (required)
773 The attribute you wish to modify, right now the attributes you can
774 modify are launchPermission and productCodes
775 OperationType (required for launchPermission)
777 The operation you wish to perform on the attribute. Right now just
778 'add' and 'remove' are supported.
779 UserId (required for launchPermission)
781 User Id's you wish to add/remove from the attribute.
782 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 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 Returns 1 if the modification succeeds.
794 modify_instance_attribute(%params)
796 Modify an attribute of an instance.
797 InstanceId (required)
799 The instance id we want to modify the attributes of.
800 Attribute (required)
802 The attribute we want to modify. Valid values are:
803 • instanceType
805 • kernel
807 • ramdisk
809 • userData
811 • disableApiTermination
813 • instanceInitiatedShutdownBehavior
815 • rootDeviceName
817 • blockDeviceMapping
819 Value (required)
821 The value to set the attribute to.
822 You may also pass a hashref with one or more keys and values. This
824 hashref will be flattened and passed to AWS.
825 For example:
827 $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 Returns 1 if the modification succeeds.
838 modify_snapshot_attribute(%params)
840 This method modifies attributes of a snapshot.
841 SnapshotId (required)
843 The snapshot id to modify the attributes of.
844 UserId (optional)
846 User Id you wish to add/remove create volume permissions for.
847 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 Attribute (required)
853 The attribute you wish to modify, right now the only attribute you
854 can modify is "CreateVolumePermission"
855 OperationType (required)
857 The operation you wish to perform on the attribute. Right now just
858 'add' and 'remove' are supported.
859 Returns 1 if the modification succeeds.
861 monitor_instances(%params)
863 Enables monitoring for a running instance. For more information, refer
864 to the Amazon CloudWatch Developer Guide.
865 InstanceId (required)
867 The instance id(s) to monitor. Can be a scalar or an array ref
868 Returns an array ref of Net::Amazon::EC2::MonitoredInstance objects
870 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 ReservedInstancesOfferingId (required)
878 ID of the Reserved Instances to describe. Can be either a scalar or
879 an array ref.
880 InstanceCount (optional)
882 The number of Reserved Instances to purchase (default is 1). Can be
883 either a scalar or an array ref.
884 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 Returns 1 if the reservations succeeded.
890 reboot_instances(%params)
892 This method reboots an instance. It takes the following parameters:
893 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 Returns 1 if the reboot succeeded.
899 register_image(%params)
901 This method registers an AMI on the EC2. It takes the following
902 parameter:
903 ImageLocation (optional)
905 The location of the AMI manifest on S3
906 Name (required)
908 The name of the AMI that was provided during image creation.
909 Description (optional)
911 The description of the AMI.
912 Architecture (optional)
914 The architecture of the image. Either i386 or x86_64
915 KernelId (optional)
917 The ID of the kernel to select.
918 RamdiskId (optional)
920 The ID of the RAM disk to select. Some kernels require additional
921 drivers at launch.
922 RootDeviceName (optional)
924 The root device name (e.g., /dev/sda1).
925 BlockDeviceMapping (optional)
927 This needs to be a data structure like this:
928 [
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 Returns the image id of the new image on EC2.
944 release_address(%params)
946 Releases an allocated IP address. It takes the following arguments:
947 PublicIp (required)
949 The IP address to release
950 Returns true if the releasing succeeded.
952 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 ImageId (required)
958 The image id of the AMI you wish to reset the attributes on.
959 Attribute (required)
961 The attribute you want to reset.
962 Returns 1 if the attribute reset succeeds.
964 reset_instance_attribute(%params)
966 Reset an attribute of an instance. Only one attribute can be specified
967 per call.
968 InstanceId (required)
970 The instance id we want to reset the attributes of.
971 Attribute (required)
973 The attribute we want to reset. Valid values are:
974 • kernel
976 • ramdisk
978 Returns 1 if the reset succeeds.
980 reset_snapshot_attribute(%params)
982 This method resets an attribute for an snapshot to its default state.
983 It takes the following parameters:
985 SnapshotId (required)
987 The snapshot id of the snapshot you wish to reset the attributes
988 on.
989 Attribute (required)
991 The attribute you want to reset (currently "CreateVolumePermission"
992 is the only valid attribute).
993 Returns 1 if the attribute reset succeeds.
995 revoke_security_group_ingress(%params)
997 This method revoke permissions to a security group. It takes the
998 following parameters:
999 GroupName (required)
1001 The name of the group to revoke security rules from.
1002 SourceSecurityGroupName (required when revoking a user and group
1004 together)
1005 Name of the group to revoke access from.
1006 SourceSecurityGroupOwnerId (required when revoking a user and group
1008 together)
1009 Owner of the group to revoke access from.
1010 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 FromPort (required when revoking access from a CIDR)
1016 Beginning of port range to revoke access from.
1017 ToPort (required when revoking access from a CIDR)
1019 End of port range to revoke access from.
1020 CidrIp (required when revoking access from a CIDR)
1022 The CIDR IP space we are revoking access from.
1023 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 Returns 1 if rule is revoked successfully.
1029 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 ImageId (required)
1036 The image id you want to start an instance of.
1037 MinCount (required)
1039 The minimum number of instances to start.
1040 MaxCount (required)
1042 The maximum number of instances to start.
1043 KeyName (optional)
1045 The keypair name to associate this instance with. If omitted, will
1046 use your default keypair.
1047 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 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 AdditionalInfo (optional)
1059 Specifies additional information to make available to the
1060 instance(s).
1061 UserData (optional)
1063 Optional data to pass into the instance being started. Needs to be
1064 base64 encoded.
1065 InstanceType (optional)
1067 Specifies the type of instance to start.
1068 See http://aws.amazon.com/ec2/instance-types
1070 The options are:
1072 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 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 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 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 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 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 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 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 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 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 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 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 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 Placement.AvailabilityZone (optional)
1129 The availability zone you want to run the instance in
1130 KernelId (optional)
1132 The id of the kernel you want to launch the instance with
1133 RamdiskId (optional)
1135 The id of the ramdisk you want to launch the instance with
1136 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 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 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 Additional volume related parameters include,
1153 BlockDeviceMapping.Ebs.SnapshotId
1155 May pass in a scalar or arrayref.
1156 BlockDeviceMapping.Ebs.VolumeType
1158 May pass in a scalar or arrayref.
1159 BlockDeviceMapping.Ebs.DeleteOnTermination
1161 May pass in a scalar or arrayref.
1162 Encoding (optional)
1164 The encoding.
1165 Version (optional)
1167 The version.
1168 Monitoring.Enabled (optional)
1170 Enables monitoring for this instance.
1171 SubnetId (optional)
1173 Specifies the subnet ID within which to launch the instance(s) for
1174 Amazon Virtual Private Cloud.
1175 ClientToken (optional)
1177 Specifies the idempotent instance id.
1178 EbsOptimized (optional)
1180 Whether the instance is optimized for EBS I/O.
1181 PrivateIpAddress (optional)
1183 Specifies the private IP address to use when launching an Amazon
1184 VPC instance.
1185 IamInstanceProfile.Name (optional)
1187 Specifies the IAM profile to associate with the launched
1188 instance(s). This is the name of the role.
1189 IamInstanceProfile.Arn (optional)
1191 Specifies the IAM profile to associate with the launched
1192 instance(s). This is the ARN of the profile.
1193 Returns a Net::Amazon::EC2::ReservationInfo object
1195 start_instances(%params)
1197 Starts an instance that uses an Amazon EBS volume as its root device.
1198 InstanceId (required)
1200 Either a scalar or an array ref can be passed in (containing
1201 instance ids to be started).
1202 Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
1204 stop_instances(%params)
1206 Stops an instance that uses an Amazon EBS volume as its root device.
1207 InstanceId (required)
1209 Either a scalar or an array ref can be passed in (containing
1210 instance ids to be stopped).
1211 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 The default is false.
1220 Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
1222 terminate_instances(%params)
1224 This method shuts down instance(s) passed into it. It takes the
1225 following parameter:
1226 InstanceId (required)
1228 Either a scalar or an array ref can be passed in (containing
1229 instance ids)
1230 Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
1232 unmonitor_instances(%params)
1234 Disables monitoring for a running instance. For more information, refer
1235 to the Amazon CloudWatch Developer Guide.
1236 InstanceId (required)
1238 The instance id(s) to monitor. Can be a scalar or an array ref
1239 Returns an array ref of Net::Amazon::EC2::MonitoredInstance objects
1241
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 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
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
1262 Jeff Kim <cpan@chosec.com>
1263
1265 John McCullough and others as listed in the Changelog
1266
1268 The current maintainer is Mark Allen "<mallen@cpan.org>"
1269
1271 Copyright (c) 2006-2010 Jeff Kim.
1272 Copyright (c) 2012 Mark Allen.
1274 This program is free software; you can redistribute it and/or modify it
1276 under the same terms as Perl itself.
1277
1279 Amazon EC2 API:
1280 <http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/>
1281perl v5.36.0 2023-01-20 Net::Amazon::EC2(3)