NAME

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

VERSION

This document describes version 0.09 of Net::Amazon::EC2, released August 22nd, 2008. This module is coded against the Query version of the '2008-05-05' EC2 API which was last updated June 10th 2008.

SYNOPSIS

 use Net::Amazon::EC2;

 my $ec2 = Net::Amazon::EC2->new(
        AWSAccessKeyId => 'PUBLIC_KEY_HERE', 
        SecretAccessKey => 'SECRET_KEY_HERE'
 );

 # 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, the return value of these methods will be a Net::Amazon::EC2::Errors object.

DESCRIPTION

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.

CLASS METHODS

new(%params)

This is the constructor, it will return you a Net::Amazon::EC2 object to work with. It takes these parameters:

AWSAccessKeyId (required): Your AWS access key.
SecretAccessKey (required): Your secret key, WARNING! don't give this out or someone will be able to use your account and incur charges on your behalf.
debug (optional): A flag to turn on debugging. It is turned off by default

OBJECT METHODS

authorize_security_group_ingress(%params)

This method adds permissions to a security group. It takes the following parameters:

GroupName (required): The name of the group to add security rules to.
SourceSecurityGroupName (requred when authorizing a user and group together): Name of the group to add access for.
SourceSecurityGroupOwnerId (required when authorizing a user and group together): Owner of the group to add access for.
IpProtocol (required when adding access for a CIDR): IP Protocol of the rule you are adding access for (TCP, UDP, or ICMP)
FromPort (required when adding access for a CIDR): Beginning of port range to add access for.
ToPort (required when adding access for a CIDR): End of port range to add access for.
CidrIp (required when adding access for a CIDR): The CIDR IP space we are adding access for.

Adding a rule can be done in two ways: adding 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 added successfully.

confirm_product_instance(%params)

Checks to see if the product code passed in is attached to the instance id, taking the following parameter:

ProductCode (required): The Product Code to check
InstanceId (required): The Instance Id to check

Returns a Net::Amazon::EC2::ConfirmProductInstanceResponse object

create_key_pair(%params)

Creates a new 2048 bit key pair, taking the following parameter:

KeyName (required): A name for this key. Should be unique.

Returns a Net::Amazon::EC2::KeyPair object

create_security_group(%params)

This method creates a new security group. It takes the following parameters:

GroupName (required): The name of the new group to create.
GroupDescription (required): A short description of the new group.

Returns 1 if the group creation succeeds.

delete_key_pair(%params)

This method deletes a keypair. Takes the following parameter:

KeyName (required): The name of the key to delete.

Returns 1 if the key was successfully deleted.

delete_security_group(%params)

This method deletes a security group. It takes the following parameter:

GroupName (required): The name of the security group to delete.

Returns 1 if the delete succeeded.

deregister_image(%params)

This method will deregister an AMI. It takes the following parameter:

ImageId (required): The image id of the AMI you want to deregister.

Returns 1 if the deregistering succeeded

describe_image_attributes(%params)

This method pulls a list of attributes for the image id specified

ImageId (required)

A scalar containing the image you want to get the list of attributes for.

Attribute (required)

A scalar containing the attribute to describe.

Valid attributes are:

launchPermission - The AMIs launch permissions.
ImageId - ID of the AMI for which an attribute will be described.
productCodes - The product code attached to the AMI.
kernel - Describes the ID of the kernel associated with the AMI.
ramdisk - Describes the ID of RAM disk associated with the AMI.
blockDeviceMapping - Defines native device names to use when exposing virtual devices.

Returns a Net::Amazon::EC2::DescribeImageAttribute object

describe_images(%params)

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:

ImageId (optional): Either a scalar or an array ref can be passed in, will cause just these AMIs to be 'described'
Owner (optional): Either a scalar or an array ref can be passed in, will cause AMIs owned by the Owner's provided will be 'described'. Pass either account ids, or 'amazon' for all amazon-owned AMIs, or 'self' for your own AMIs.
ExecutableBy (optional): Either a scalar or an array ref can be passed in, will cause AMIs executable by the account id's specified. Or 'self' for your own AMIs.

Returns an array ref of Net::Amazon::EC2::DescribeImagesResponse objects

describe_instances(%params)

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:

InstanceId (optional): Either a scalar or an array ref can be passed in, will cause just these instances to be 'described'

Returns an array ref of Net::Amazon::EC2::ReservationInfo objects

describe_key_pairs(%params)

This method describes the keypairs available on this account. It takes the following parameter:

KeyName (optional): The name of the key to be described. Can be either a scalar or an array ref.

Returns an array ref of Net::Amazon::EC2::DescribeKeyPairsResponse objects

describe_security_groups(%params)

This method describes the security groups available to this account. It takes the following parameter:

GroupName (optional): The name of the security group(s) to be described. Can be either a scalar or an array ref.

Returns an array ref of Net::Amazon::EC2::SecurityGroup objects

get_console_output(%params)

This method gets the output from the virtual console for an instance. It takes the following parameters:

InstanceId (required): A scalar containing a instance id.

Returns a Net::Amazon::EC2::ConsoleOutput object.

modify_image_attribute(%params)

This method modifies attributes of an machine image.

ImageId (required): The AMI to modify the attributes of.
Attribute (required): The attribute you wish to modify, right now the attributes you can modify are launchPermission and productCodes
OperationType (required for launchPermission): The operation you wish to perform on the attribute. Right now just 'add' and 'remove' are supported.
UserId (required for launchPermission): User Id's you wish to add/remove from the attribute.
UserGroup (required for launchPermission): Groups you wish to add/remove from the attribute. Currently there is only one User Group available 'all' for all Amazon EC2 customers.
ProductCode (required for productCodes): Attaches a product code to the AMI. Currently only one product code can be assigned to the AMI. Once this is set it cannot be changed or reset.

Returns 1 if the modification succeeds.

reboot_instances(%params)

This method reboots an instance. It takes the following parameters:

InstanceId (required): Instance Id of the instance you wish to reboot. Can be either a scalar or array ref of instances to reboot.

Returns 1 if the reboot succeeded.

register_image(%params)

This method registers an AMI on the EC2. It takes the following parameter:

ImageLocation (required): The location of the AMI manifest on S3

Returns the image id of the new image on EC2.

reset_image_attribute(%params)

This method resets an attribute for an AMI to its default state (NOTE: product codes cannot be reset). It takes the following parameters:

ImageId (required): The image id of the AMI you wish to reset the attributes on.
Attribute (required): The attribute you want to reset.

Returns 1 if the attribute reset succeeds.

revoke_security_group_ingress(%params)

This method revoke permissions to a security group. It takes the following parameters:

GroupName (required): The name of the group to revoke security rules from.
SourceSecurityGroupName (requred when revoking a user and group together): Name of the group to revoke access from.
SourceSecurityGroupOwnerId (required when revoking a user and group together): Owner of the group to revoke access from.
IpProtocol (required when revoking access from a CIDR): IP Protocol of the rule you are revoking access from (TCP, UDP, or ICMP)
FromPort (required when revoking access from a CIDR): Beginning of port range to revoke access from.
ToPort (required when revoking access from a CIDR): End of port range to revoke access from.
CidrIp (required when revoking access from a CIDR): The CIDR IP space we are revoking access from.

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.

run_instances(%params)

This method will start instance(s) of AMIs on EC2. The parameters indicate which AMI to instantiate and how many / what properties they have:

ImageId (required)

The image id you want to start an instance of.

MinCount (required)

The minimum number of instances to start.

MaxCount (required)

The maximum number of instances to start.

KeyName (optional)

The keypair name to associate this instance with. If omitted, will use your default keypair.

SecurityGroup (optional)

An scalar or array ref. Will associate this instance with the group names passed in. If omitted, will be associated with the default security group.

UserData (optional)

Optional data to pass into the instance being started. Needs to be base64 encoded.

InstanceType (optional)

Specifies the type of instance to start. The options are:

m1.small (default): 1 EC2 Compute Unit (1 virtual core with 1 EC2 Compute Unit). 32-bit, 1.7GB RAM, 160GB disk
m1.large: Standard Large Instance: 4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units each). 64-bit, 7.5GB RAM, 850GB disk
m1.xlarge: Standard Extra Large Instance: 8 EC2 Compute Units (4 virtual cores with 2 EC2 Compute Units each). 64-bit, 15GB RAM, 1690GB disk
c1.medium: High-CPU Medium Instance: 5 EC2 Compute Units (2 virutal cores with 2.5 EC2 Compute Units each). 32-bit, 1.7GB RAM, 350GB disk
c1.xlarge: High-CPU Extra Large Instance: 20 EC2 Compute Units (8 virtual cores with 2.5 EC2 Compute Units each). 64-bit, 7GB RAM, 1690GB disk

Placement.AvailabilityZone (optional)

The availability zone you want to run the instance in

KernelId (optional)

The id of the kernel you want to launch the instance with

RamdiskId (optional)

The id of the ramdisk you want to launch the instance with

BlockDeviceMapping.VirtualName (optional)

This is the virtual name for a blocked device to be attached, may pass in a scalar or arrayref

BlockDeviceMapping.DeviceName (optional)

This is the device name for a block device to be attached, may pass in a scalar or arrayref

Returns a Net::Amazon::EC2::ReservationInfo object

terminate_instances(%params)

This method shuts down instance(s) passed into it. It takes the following parameter:

InstanceId (required): Either a scalar or an array ref can be passed in (containing instance ids)

Returns an array ref of Net::Amazon::EC2::TerminateInstancesResponse objects.

allocate_address()

Acquires an elastic IP address which can be associated with an instance to create a movable static IP. Takes no arguments

Returns the IP address obtained.

associate_address(%params)

Associates an elastic IP address with an instance. It takes the following arguments:

InstanceId (required): The instance id you wish to associate the IP address with
PublicIp (required): The IP address to associate with

Returns true if the association succeeded.

describe_addresses(%params)

This method describes the elastic addresses currently allocated and any instances associated with them. It takes the following arguments:

PublicIp (optional): The IP address to describe. Can be either a scalar or an array ref.

Returns an array ref of Net::Amazon::EC2::DescribeAddress objects

describe_availability_zones(%params)

This method describes the availability zones currently available to choose from. It takes the following arguments:

ZoneName (optional): The zone name to describe. Can be either a scalar or an array ref.

Returns an array ref of Net::Amazon::EC2::AvailabilityZone objects

disassociate_address(%params)

Disassociates an elastic IP address with an instance. It takes the following arguments:

PublicIp (required): The IP address to disassociate

Returns true if the disassociation succeeded.

release_address(%params)

Releases an allocated IP address. It takes the following arguments:

PublicIp (required): The IP address to release

Returns true if the releasing succeeded.

describe_volumes(%params)

Describes the volumes currently created. It takes the following arguments:

VolumeId (optional): Either a scalar or array ref of volume id's can be passed in. If this isn't passed in it will describe all the current volumes.

Returns an array ref of Net::Amazon::EC2::Volume objects.

create_volume(%params)

Creates a volume.

Size (required): The size in GiB of the volume you want to create.
SnapshotId (optional): The optional snapshot id to create the volume from.
AvailabilityZone (required): The availability zone to create the volume in.

Returns true if the releasing succeeded.

delete_volume(%params)

Delete a volume.

VolumeId (required): The volume id you wish to delete.

Returns true if the deleting succeeded.

attach_volume(%params)

Attach a volume to an instance.

VolumeId (required): The volume id you wish to attach.
InstanceId (required): The instance id you wish to attach the volume to.
Device (required): The device id you want the volume attached as.

Returns a Net::Amazon::EC2::Attachment object containing the resulting volume status.

detach_volume(%params)

Detach a volume from an instance.

VolumeId (required): The volume id you wish to detach.
InstanceId (optional): The instance id you wish to detach from.
Device (optional): The device the volume was attached as.
Force (optional): A boolean for if to forcibly detach the volume from the instance. WARNING: This can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance will not have an opportunity to flush file system caches nor file system meta data.

Returns a Net::Amazon::EC2::Attachment object containing the resulting volume status.

describe_snapshots(%params)

Describes the snapshots currently created. It takes the following arguments:

SnapshotId (optional): Either a scalar or array ref of snapshot id's can be passed in. If this isn't passed in it will describe all the current snapshots.

Returns an array ref of Net::Amazon::EC2::Snapshot objects.

create_snapshot(%params)

Create a snapshot of a volume. It takes the following arguments:

VolumeId (required): The volume id of the volume you want to take a snapshot of.

Returns a Net::Amazon::EC2::Snapshot object of the newly created snapshot.

delete_snapshot(%params)

Deletes the snapshots passed in. It takes the following arguments:

SnapshotId (required): Either a scalar or array ref of snapshot id's can be passed in. Will delete the corresponding snapshots.

Returns true if the deleting succeeded.

TESTING

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 August 21st, 2008 costs a total of $0.20 USD

AUTHOR

Jeff Kim <jkim@chosec.com>

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

CLASS METHODS

new(%params)

OBJECT METHODS

authorize_security_group_ingress(%params)

confirm_product_instance(%params)

create_key_pair(%params)

create_security_group(%params)

delete_key_pair(%params)

delete_security_group(%params)

deregister_image(%params)

describe_image_attributes(%params)

describe_images(%params)

describe_instances(%params)

describe_key_pairs(%params)

describe_security_groups(%params)

get_console_output(%params)

modify_image_attribute(%params)

reboot_instances(%params)

register_image(%params)

reset_image_attribute(%params)

revoke_security_group_ingress(%params)

run_instances(%params)

terminate_instances(%params)

allocate_address()

associate_address(%params)

describe_addresses(%params)

describe_availability_zones(%params)

disassociate_address(%params)

release_address(%params)

describe_volumes(%params)

create_volume(%params)

delete_volume(%params)

attach_volume(%params)

detach_volume(%params)

describe_snapshots(%params)

create_snapshot(%params)

delete_snapshot(%params)

TESTING

AUTHOR

COPYRIGHT

SEE ALSO

Module Install Instructions