The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Amazon-EC2-0.04
River stage one • 6 direct dependents • 6 total dependents
6 ++
/ Net::Amazon::EC2

NAME

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

VERSION

This document describes version 0.04 of Net::Amazon::EC2, released April 1, 2007. This module is coded against the Query version of the '2007-01-19' version of the EC2 API.

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 $inst (@{$running_instances}) {
        print "$inst->{instance}[0]{instanceId}\n";
 }

 # Terminate instance

 my $result = $ec2->terminate_instances(InstanceId => $instance->{instance}[0]{instanceId});

If an error occurs in communicating with EC2, the return value will be undef and $ec2->{error} will be populated with the message.

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

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.

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: a data structure like this: or undef if an error occured

        [
                {
                        'imageOwnerId' => '',
                        'imageState' => '',
                        'isPublic' => '',
                        'imageLocation' => '',
                        'imageId' => ''
                },
                ...
        ]

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 a boolean 1 for success 0 for failure.

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.

AddressingType (options)

Optional addressing scheme to launch the instance. If passed in it should have a value of either "direct" or "public".

Returns a data structure which looks like this:

 {
        'groups' => [
                                'group1',
                                'group2',
                                '....'
                          ],
        'instance' => {
                                  'instanceState' => {
                                                                         'name' => '',
                                                                         'code' => ''
                                                                   },
                                  'instanceId' => '',
                                  'reason' => {},
                                  'dnsName' => '',
                                  'privateDnsName' => '',
                                  'amiLaunchIndex' => '',
                                  'keyName' => '',
                                  'imageId' => ''
                                },
        'ownerId' => '',
        'reservationId' => ''
 }

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 the following data structure, or undef if a failure has occured:

 [
          {
            'instance' => {
                            'instanceState' => {
                                               'name' => '',
                                               'code' => ''
                                             },
                            'instanceId' => '',
                            'reason' => {},
                            'privateDnsName' => '',
                            'dnsName' => '',
                            'keyName' => '',
                            'imageId' => ''
                          },
            'ownerId' => '',
            'reservationId' => '',
            'groups' => [
                          ''
                        ],            
          },
 ];

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 the following data struct or undef:

 [
          {
            'instanceId' => '',
            'shutdownState' => {
                               'name' => '',
                               'code' => ''
                             },
            'previousState' => {
                               'name' => '',
                               'code' => ''
                             }
          },
          ...
 ];

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 hashref containing:

keyName

The key name provided in the original request.

KeyFingerprint

A SHA-1 digest of the DER encoded private key.

KeyMaterial

An unencrypted PEM encoded RSA private key.

or undef if the creation failed.

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 a data structure like: (or undef if an error occured)

 [
          {
            'keyFingerprint' => '',
            'keyName' => ''
          },
          ...
 ];

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.

modify_image_attribute(%params)

This method modifies attributes of an AMI on EC2. Right now the only attribute that can be modified is to grant launch permissions. It takes the following parameters:

ImageId (required)

The AMI to modify the attributes of.

Attribute (required)

The attribute you wish to modify, right now the only attribute that exists is launchPermission.

OperationType (required)

The operation you wish to perform on the attribute. Right now just 'add' and 'remove' are supported.

UserId (required when changing the launchPermission attribute)

User Id's you wish to add/remove from the attribute (right now just for launchPermission)

UserGroup (required when changing the launchPermission attribute)

Groups you wish to add/remove from the attribute (right now just for launchPermission). Currently there is only one User Group available 'all' for all Amazon EC2 customers.

Returns 1 if the modification succeeds, or 0 if it does not.

reset_image_attribute(%params)

This method resets an attribute for an AMI to its default state. 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. Right now the only attribute which exists is launchPermission.

Returns 1 if the reset succeeds, or 0 if it does not.

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.

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 the data structure: (or undef if error)

 [
        {
        'ipPermissions' => {
                                           'item' => [
                                                                 {
                                                                   'ipRanges' => {
                                                                                                 'item' => [
                                                                                                                   {
                                                                                                                         'cidrIp' => ''
                                                                                                                   }
                                                                                                                 ]
                                                                                           },
                                                                   'toPort' => '',
                                                                   'fromPort' => '',
                                                                   'groups' => {},
                                                                   'ipProtocol' => 'tcp'
                                                                 },
                                                                 ...
                                                ],
        'groupDescription' => '',
        'groupName' => '',
        'ownerId' => ''
        },
        ...
 ]

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.

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.

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 authorizing a user and group together)

Name of the group to revoke access from.

SourceSecurityGroupOwnerId (required when authorizing 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.

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 the output from the console for the instance.

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.

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. Currently the only possible value for this is 'launchPermission'.

Returns the following data structure, or undef if a failure has occured:

 {
        'ImageId' => '',
        'launchPermission' => {
                                        item => [
                                                'group' => '',
                                                'user_id' => ''
                                        ]
        }
 };

TODO

  • Add more automated testing.

  • Make the data coming back an collection of objects rather than a arrayref/hashref based structure.

TESTING

Due to the nature of this module automated testing is both difficult and expensive (since starting and stopping instances and putting data on S3 all cost money). So the tests run on a make test are fairly minimal (though, this module has been tested heavily)

AUTHOR

Jeff Kim <jkim@chosec.com>

COPYRIGHT

Copyright (c) 2006-2007 Jeff Kim. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Amazon EC2 API: http://docs.amazonwebservices.com/AmazonEC2/dg/2007-01-19/