| Net::Amazon::EC2(3pm) | User Contributed Perl Documentation | Net::Amazon::EC2(3pm) |
Net::Amazon::EC2 - Perl interface to the Amazon Elastic Compute Cloud (EC2) environment.
EC2 Query API version: '2014-06-15'
use Net::Amazon::EC2;
my $ec2 = Net::Amazon::EC2->new(
AWSAccessKeyId => 'PUBLIC_KEY_HERE',
SecretAccessKey => 'SECRET_KEY_HERE',
signature_version => 4,
);
# Start 1 new instance from AMI: ami-XXXXXXXX
my $instance = $ec2->run_instances(ImageId => 'ami-XXXXXXXX', MinCount => 1, MaxCount => 1);
my $running_instances = $ec2->describe_instances;
foreach my $reservation (@$running_instances) {
foreach my $instance ($reservation->instances_set) {
print $instance->instance_id . "\n";
}
}
my $instance_id = $instance->instances_set->[0]->instance_id;
print "$instance_id\n";
# Terminate instance
my $result = $ec2->terminate_instances(InstanceId => $instance_id);
If an error occurs while communicating with EC2, these methods will throw a Net::Amazon::EC2::Errors exception.
This module is a Perl interface to Amazon's Elastic Compute Cloud. It uses the Query API to communicate with Amazon's Web Services framework.
This is the constructor, it will return you a Net::Amazon::EC2 object to work with. It takes these parameters:
If you want/need the old behavior, set this attribute to a true value.
Acquires an elastic IP address which can be associated with an EC2-classic instance to create a movable static IP. Takes no arguments.
Returns the IP address obtained.
Acquires an elastic IP address which can be associated with a VPC instance to create a movable static IP. Takes no arguments.
Returns the allocationId of the allocated address.
Associates an elastic IP address with an instance. It takes the following arguments:
Returns true if the association succeeded.
Attach a volume to an instance.
Returns a Net::Amazon::EC2::Attachment object containing the resulting volume status.
This method adds permissions to a security group. It takes the following parameters:
Adding a rule can be done in two ways: adding a source group name + source group owner id, or, CIDR IP range. Both methods allow IP protocol, from port and to port specifications.
Returns 1 if rule is added successfully.
Bundles the Windows instance. This procedure is not applicable for Linux and UNIX instances.
NOTE NOTE NOTE This is not well tested as I don't run windows instances
JSON Parameters: (all are required)
expiration - The expiration of the policy. Amazon recommends 12 hours or longer. conditions - A list of restrictions on what can be uploaded to Amazon S3. Must contain the bucket and ACL conditions in this table. bucket - The bucket to store the AMI. acl - This must be set to ec2-bundle-read.
Returns a Net::Amazon::EC2::BundleInstanceResponse object
Cancels the bundle task. This procedure is not applicable for Linux and UNIX instances.
Returns a Net::Amazon::EC2::BundleInstanceResponse object
Checks to see if the product code passed in is attached to the instance id, taking the following parameter:
Returns a Net::Amazon::EC2::ConfirmProductInstanceResponse object
Creates an AMI that uses an Amazon EBS root device from a "running" or "stopped" instance.
AMIs that use an Amazon EBS root device boot faster than AMIs that use instance stores. They can be up to 1 TiB in size, use storage that persists on instance failure, and can be stopped and started.
Note that the image name has the following constraints:
3-128 alphanumeric characters, parenthesis, commas, slashes, dashes, or underscores.
You can specify device names as '<device>=<block_device>' similar to ec2-create-image command. (<http://docs.aws.amazon.com/AWSEC2/latest/CommandLineReference/ApiReference-cmd-CreateImage.html>)
BlockDeviceMapping => [
'/dev/sda=:256:true:standard',
'/dev/sdb=none',
'/dev/sdc=ephemeral0',
'/dev/sdd=ephemeral1',
],
Returns the ID of the AMI created.
Creates a new 2048 bit key pair, taking the following parameter:
Returns a Net::Amazon::EC2::KeyPair object
This method creates a new security group. It takes the following parameters:
Returns 1 if the group creation succeeds.
Create a snapshot of a volume. It takes the following arguments:
Returns a Net::Amazon::EC2::Snapshot object of the newly created snapshot.
Creates tags.
Returns true if the tag creation succeeded.
Creates a volume.
Required when the volume type is io1; not used otherwise.
Returns a Net::Amazon::EC2::Volume object containing the resulting volume status
This method deletes a keypair. Takes the following parameter:
Returns 1 if the key was successfully deleted.
This method deletes a security group. It takes the following parameter:
Returns 1 if the delete succeeded.
Deletes the snapshots passed in. It takes the following arguments:
Returns true if the deleting succeeded.
Delete a volume.
Returns true if the deleting succeeded.
Delete tags.
Returns true if the releasing succeeded.
This method will deregister an AMI. It takes the following parameter:
Returns 1 if the deregistering succeeded
This method describes the elastic addresses currently allocated and any instances associated with them. It takes the following arguments:
Returns an array ref of Net::Amazon::EC2::DescribeAddress objects
This method describes the availability zones currently available to choose from. It takes the following arguments:
Returns an array ref of Net::Amazon::EC2::AvailabilityZone objects
Describes current bundling tasks. This procedure is not applicable for Linux and UNIX instances.
Returns a array ref of Net::Amazon::EC2::BundleInstanceResponse objects
This method pulls a list of attributes for the image id specified
Valid attributes are:
Returns a Net::Amazon::EC2::DescribeImageAttribute object
* NOTE: There is currently a bug in Amazon's SOAP and Query API for when you try and describe the attributes: kernel, ramdisk, blockDeviceMapping, or platform AWS returns an invalid response. No response yet from Amazon on an ETA for getting that bug fixed.
This method pulls a list of the AMIs which can be run. The list can be modified by passing in some of the following parameters:
Returns an array ref of Net::Amazon::EC2::DescribeImagesResponse objects
This method pulls a list of the instances which are running or were just running. The list can be modified by passing in some of the following parameters:
Returns an array ref of Net::Amazon::EC2::ReservationInfo objects
This method pulls a list of the instances based on some status filter. The list can be modified by passing in some of the following parameters:
Returns an array ref of Net::Amazon::EC2::InstanceStatuses objects
Returns a blessed object. Used internally for wrapping describe_instance_status nextToken calls
Returns a Net::Amazon::EC2::InstanceStatuses object
Returns information about an attribute of an instance. Only one attribute can be specified per call.
Returns a Net::Amazon::EC2::DescribeInstanceAttributeResponse object
This method describes the keypairs available on this account. It takes the following parameter:
Returns an array ref of Net::Amazon::EC2::DescribeKeyPairsResponse objects
Describes EC2 regions that are currently available to launch instances in for this account.
Returns an array ref of Net::Amazon::EC2::Region objects
Describes Reserved Instances that you purchased.
Returns an array ref of Net::Amazon::EC2::ReservedInstance objects
Describes Reserved Instance offerings that are available for purchase. With Amazon EC2 Reserved Instances, you purchase the right to launch Amazon EC2 instances for a period of time (without getting insufficient capacity errors) and pay a lower usage rate for the actual time used.
See http://aws.amazon.com/ec2/instance-types
Returns an array ref of Net::Amazon::EC2::ReservedInstanceOffering objects
This method describes the security groups available to this account. It takes the following parameter:
Returns an array ref of Net::Amazon::EC2::SecurityGroup objects
Describes the snapshots attributes related to the snapshot in question. It takes the following arguments:
Returns a Net::Amazon::EC2::SnapshotAttribute object.
Describes the snapshots available to the user. It takes the following arguments:
Returns an array ref of Net::Amazon::EC2::Snapshot objects.
Describes the volumes currently created. It takes the following arguments:
Returns an array ref of Net::Amazon::EC2::Volume objects.
This method describes the subnets on this account. It takes the following parameters:
Returns an array ref of Net::Amazon::EC2::DescribeSubnetResponse objects
This method describes the tags available on this account. It takes the following parameter:
Returns an array ref of Net::Amazon::EC2::DescribeTags objects
Detach a volume from an instance.
Returns a Net::Amazon::EC2::Attachment object containing the resulting volume status.
Disassociates an elastic IP address with an instance. It takes the following arguments:
Returns true if the disassociation succeeded.
This method gets the output from the virtual console for an instance. It takes the following parameters:
Returns a Net::Amazon::EC2::ConsoleOutput object or "undef" if there is no new output. (This can happen in cases where the console output has not changed since the last call.)
Retrieves the encrypted administrator password for the instances running Windows. This procedure is not applicable for Linux and UNIX instances.
Returns a Net::Amazon::EC2::InstancePassword object
This method modifies attributes of an machine image.
Returns 1 if the modification succeeds.
Modify an attribute of an instance.
You may also pass a hashref with one or more keys and values. This hashref will be flattened and passed to AWS.
For example:
$ec2->modify_instance_attribute(
'InstanceId' => $id,
'Attribute' => 'blockDeviceMapping',
'Value' => {
'BlockDeviceMapping.1.DeviceName' => '/dev/sdf1',
'BlockDeviceMapping.1.Ebs.DeleteOnTermination' => 'true',
}
);
Returns 1 if the modification succeeds.
This method modifies attributes of a snapshot.
Returns 1 if the modification succeeds.
Enables monitoring for a running instance. For more information, refer to the Amazon CloudWatch Developer Guide.
Returns an array ref of Net::Amazon::EC2::MonitoredInstance objects
Purchases a Reserved Instance for use with your account. With Amazon EC2 Reserved Instances, you purchase the right to launch Amazon EC2 instances for a period of time (without getting insufficient capacity errors) and pay a lower usage rate for the actual time used.
NOTE NOTE NOTE, the array ref needs to line up with the InstanceCount if you want to pass that in, so that the right number of instances are started of the right instance offering
Returns 1 if the reservations succeeded.
This method reboots an instance. It takes the following parameters:
Returns 1 if the reboot succeeded.
This method registers an AMI on the EC2. It takes the following parameter:
[
{
deviceName => "/dev/sdh", (optional)
virtualName => "ephemerel0", (optional)
noDevice => "/dev/sdl", (optional),
ebs => {
snapshotId => "snap-0000", (optional)
volumeSize => "20", (optional)
deleteOnTermination => "false", (optional)
},
},
...
]
Returns the image id of the new image on EC2.
Releases an allocated IP address. It takes the following arguments:
Returns true if the releasing succeeded.
This method resets an attribute for an AMI to its default state (NOTE: product codes cannot be reset). It takes the following parameters:
Returns 1 if the attribute reset succeeds.
Reset an attribute of an instance. Only one attribute can be specified per call.
Returns 1 if the reset succeeds.
This method resets an attribute for an snapshot to its default state.
It takes the following parameters:
Returns 1 if the attribute reset succeeds.
This method revoke permissions to a security group. It takes the following parameters:
Revoking a rule can be done in two ways: revoking a source group name + source group owner id, or, by Protocol + start port + end port + CIDR IP. The two are mutally exclusive.
Returns 1 if rule is revoked successfully.
This method will start instance(s) of AMIs on EC2. The parameters indicate which AMI to instantiate and how many / what properties they have:
See http://aws.amazon.com/ec2/instance-types
The options are:
Additional volume related parameters include,
Returns a Net::Amazon::EC2::ReservationInfo object
Starts an instance that uses an Amazon EBS volume as its root device.
Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
Stops an instance that uses an Amazon EBS volume as its root device.
The default is false.
Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
This method shuts down instance(s) passed into it. It takes the following parameter:
Returns an array ref of Net::Amazon::EC2::InstanceStateChange objects.
Disables monitoring for a running instance. For more information, refer to the Amazon CloudWatch Developer Guide.
Returns an array ref of Net::Amazon::EC2::MonitoredInstance objects
Set AWS_ACCESS_KEY_ID and SECRET_ACCESS_KEY environment variables to run the live tests. Note: because the live tests start an instance (and kill it) in both the tests and backwards compat tests there will be 2 hours of machine instance usage charges (since there are 2 instances started) which as of February 1st, 2010 costs a total of $0.17 USD
Important note about the windows-only methods. These have not been well tested as I do not run windows-based instances, so exercise caution in using these.
Please report any bugs or feature requests to "bug-net-amazon-ec2 at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Amazon-EC2>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
Jeff Kim <cpan@chosec.com>
John McCullough and others as listed in the Changelog
The current maintainer is Mark Allen "<mallen@cpan.org>"
Copyright (c) 2006-2010 Jeff Kim.
Copyright (c) 2012 Mark Allen.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Amazon EC2 API: <http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/>
| 2022-12-06 | perl v5.36.0 |