class Aws::Ec2

Aws::EC2 – RightScale Amazon EC2 interface

The Aws::EC2 class provides a complete interface to Amazon's Elastic Compute Cloud service, as well as the associated EBS (Elastic Block Store). For explanations of the semantics of each call, please refer to Amazon's documentation at developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=87

Examples:

Create an EC2 interface handle:

@ec2   = Aws::Ec2.new(aws_access_key_id,
                            aws_secret_access_key)

Create a new SSH key pair:

@key   = 'right_ec2_awesome_test_key'
new_key = @ec2.create_key_pair(@key)
keys = @ec2.describe_key_pairs

Create a security group:

@group = 'right_ec2_awesome_test_security_group'
@ec2.create_security_group(@group,'My awesome test group')
group = @ec2.describe_security_groups([@group])[0]

Configure a security group:

@ec2.authorize_security_group_named_ingress(@group, account_number, 'default')
@ec2.authorize_security_group_IP_ingress(@group, 80,80,'udp','192.168.1.0/8')

Describe the available images:

images = @ec2.describe_images

Launch an instance:

ec2.run_instances('ami-9a9e7bf3', 1, 1, ['default'], @key, 'SomeImportantUserData', 'public')

Describe running instances:

@ec2.describe_instances

Error handling: all operations raise an Aws::AwsError in case of problems. Note that transient errors are automatically retried.

Constants

API_VERSION

Amazon EC2 API version being used

DEFAULT_ADDRESSING_TYPE

Default addressing type (public=NAT, direct=no-NAT) used when launching instances.

DEFAULT_HOST
DEFAULT_INSTANCE_TYPE

Amazon EC2 Instance Types : www.amazon.com/b?ie=UTF8&node=370375011 Default EC2 instance type (platform)

DEFAULT_PATH
DEFAULT_PORT
DEFAULT_PROTOCOL
DNS_ADDRESSING_SET
INSTANCE_TYPES

Public Class Methods

api() click to toggle source
# File lib/ec2/ec2.rb, line 106
def self.api
  @@api
end
bench() click to toggle source
# File lib/ec2/ec2.rb, line 91
def self.bench
  @@bench
end
bench_ec2() click to toggle source
# File lib/ec2/ec2.rb, line 99
def self.bench_ec2
  @@bench.service
end
bench_xml() click to toggle source
# File lib/ec2/ec2.rb, line 95
def self.bench_xml
  @@bench.xml
end
connection_name() click to toggle source
# File lib/ec2/ec2.rb, line 86
def self.connection_name
  :ec2_connection
end
new(aws_access_key_id=nil, aws_secret_access_key=nil, params={}) click to toggle source

Create a new handle to an EC2 account. All handles share the same per process or per thread HTTP connection to Amazon EC2. Each handle is for a specific account. The params have the following options:

  • :endpoint_url a fully qualified url to Amazon API endpoint (this overwrites: :server, :port, :service, :protocol and :region). Example: 'eu-west-1.ec2.amazonaws.com/'

  • :server: EC2 service host, default: DEFAULT_HOST

  • :region: EC2 region (North America by default)

  • :port: EC2 service port, default: DEFAULT_PORT

  • :protocol: 'http' or 'https', default: DEFAULT_PROTOCOL

  • :multi_thread: true=HTTP connection per thread, false=per process

  • :logger: for log messages, default: Rails.logger else STDOUT

  • :signature_version: The signature version : '0' or '1'(default)

  • :cache: true/false: caching for: ec2_describe_images, #describe_instances,

#describe_images_by_owner, #describe_images_by_executable_by, #describe_availability_zones, #describe_security_groups, #describe_key_pairs, #describe_addresses, #describe_volumes, #describe_snapshots methods, default: false.

# File lib/ec2/ec2.rb, line 126
def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
  init({:name             => 'EC2',
        :default_host     => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).host : DEFAULT_HOST,
        :default_port     => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).port : DEFAULT_PORT,
        :default_service  => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).path : DEFAULT_PATH,
        :default_protocol => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).scheme : DEFAULT_PROTOCOL,
        :api_version      => API_VERSION},
       aws_access_key_id || ENV['AWS_ACCESS_KEY_ID'],
       aws_secret_access_key|| ENV['AWS_SECRET_ACCESS_KEY'],
       params)
  # EC2 doesn't really define any transient errors to retry, and in fact,
  # when they return a 503 it is usually for 'request limit exceeded' which
  # we most certainly should not retry.  So let's pare down the list of
  # retryable errors to InternalError only (see AwsBase for the default
  # list)
  amazon_problems = ['InternalError']
end

Public Instance Methods

allocate_address() click to toggle source

Acquire a new elastic IP address for use with your account. Returns allocated IP address or an exception.

ec2.allocate_address #=> '75.101.154.140'
# File lib/ec2/ec2.rb, line 1068
def allocate_address
  link = generate_request("AllocateAddress")
  request_info(link, QEc2AllocateAddressParser.new(:logger => @logger))
rescue Exception
  on_exception
end
associate_address(instance_id, public_ip) click to toggle source

Associate an elastic IP address with an instance. Returns true or an exception.

ec2.associate_address('i-d630cbbf', '75.101.154.140') #=> true
# File lib/ec2/ec2.rb, line 1080
def associate_address(instance_id, public_ip)
  link = generate_request("AssociateAddress",
                          "InstanceId" => instance_id.to_s,
                          "PublicIp"   => public_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
attach_volume(volume_id, instance_id, device) click to toggle source

Attach the specified EBS volume to a specified instance, exposing the volume using the specified device name.

ec2.attach_volume('vol-898a6fe0', 'i-7c905415', '/dev/sdh') #=>
  { :aws_instance_id => "i-7c905415",
    :aws_device      => "/dev/sdh",
    :aws_status      => "attaching",
    :aws_attached_at => "2008-03-28T14:14:39.000Z",
    :aws_id          => "vol-898a6fe0" }
# File lib/ec2/ec2.rb, line 1284
def attach_volume(volume_id, instance_id, device)
  link = generate_request("AttachVolume",
                          "VolumeId"   => volume_id.to_s,
                          "InstanceId" => instance_id.to_s,
                          "Device"     => device.to_s)
  request_info(link, QEc2AttachAndDetachVolumeParser.new(:logger => @logger))
rescue Exception
  on_exception
end
authorize_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0') click to toggle source

Add permission to a security group. Returns true or an exception. protocol is one of :'tcp'|'udp'|'icmp'.

ec2.authorize_security_group_IP_ingress('my_awesome_group', 80, 82, 'udp', '192.168.1.0/8') #=> true
ec2.authorize_security_group_IP_ingress('my_awesome_group', -1, -1, 'icmp') #=> true
# File lib/ec2/ec2.rb, line 968
def authorize_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0')
  link = generate_request("AuthorizeSecurityGroupIngress",
                          'GroupName'  => name.to_s,
                          'IpProtocol' => protocol.to_s,
                          'FromPort'   => from_port.to_s,
                          'ToPort'     => to_port.to_s,
                          'CidrIp'     => cidr_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
authorize_security_group_named_ingress(name, owner, group) click to toggle source

Authorize named ingress for security group. Allows instances that are member of someone else's security group to open connections to instances in my group.

ec2.authorize_security_group_named_ingress('my_awesome_group', '7011-0219-8268', 'their_group_name') #=> true
# File lib/ec2/ec2.rb, line 939
def authorize_security_group_named_ingress(name, owner, group)
  link = generate_request("AuthorizeSecurityGroupIngress",
                          'GroupName'                  => name.to_s,
                          'SourceSecurityGroupName'    => group.to_s,
                          'SourceSecurityGroupOwnerId' => owner.to_s.gsub(/-/, ''))
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
bundle_instance(instance_id, s3_bucket, s3_prefix, s3_owner_aws_access_key_id=nil, s3_owner_aws_secret_access_key=nil, s3_expires = S3Interface::DEFAULT_EXPIRES_AFTER, s3_upload_policy='ec2-bundle-read') click to toggle source

Bundle a Windows image. Internally, it queues the bundling task and shuts down the instance. It then takes a snapshot of the Windows volume bundles it, and uploads it to S3. After bundling completes, #register_image may be used to register the new Windows AMI for subsequent launches.

ec2.bundle_instance('i-e3e24e8a', 'my-awesome-bucket', 'my-win-image-1') #=>
 [{:aws_update_time => "2008-10-16T13:58:25.000Z",
   :s3_bucket       => "kd-win-1",
   :s3_prefix       => "win2pr",
   :aws_state       => "pending",
   :aws_id          => "bun-26a7424f",
   :aws_instance_id => "i-878a25ee",
   :aws_start_time  => "2008-10-16T13:58:02.000Z"}]
# File lib/ec2/ec2.rb, line 739
def bundle_instance(instance_id, s3_bucket, s3_prefix,
    s3_owner_aws_access_key_id=nil, s3_owner_aws_secret_access_key=nil,
    s3_expires = S3Interface::DEFAULT_EXPIRES_AFTER,
    s3_upload_policy='ec2-bundle-read')
  # S3 access and signatures
  s3_owner_aws_access_key_id     ||= @aws_access_key_id
  s3_owner_aws_secret_access_key ||= @aws_secret_access_key
  s3_expires = Time.now.utc + s3_expires if s3_expires.is_a?(Fixnum) && (s3_expires < S3Interface::ONE_YEAR_IN_SECONDS)
  # policy
  policy          = {'expiration' => s3_expires.strftime('%Y-%m-%dT%H:%M:%SZ'),
                     'conditions' => [{'bucket' => s3_bucket},
                                      {'acl' => s3_upload_policy},
                                      ['starts-with', '$key', s3_prefix]]}.to_json
  policy64        = Base64.encode64(policy).gsub("\n", "")
  signed_policy64 = Utils.sign(s3_owner_aws_secret_access_key, policy64)
  # fill request params
  params          = {'InstanceId'                       => instance_id,
                     'Storage.S3.AWSAccessKeyId'        => s3_owner_aws_access_key_id,
                     'Storage.S3.UploadPolicy'          => policy64,
                     'Storage.S3.UploadPolicySignature' => signed_policy64,
                     'Storage.S3.Bucket'                => s3_bucket,
                     'Storage.S3.Prefix'                => s3_prefix,
  }
  link            = generate_request("BundleInstance", params)
  request_info(link, QEc2BundleInstanceParser.new)
rescue Exception
  on_exception
end
cancel_bundle_task(bundle_id) click to toggle source

Cancel an in‐progress or pending bundle task by id.

ec2.cancel_bundle_task('bun-73a7421a') #=>
 [{:s3_bucket         => "my-awesome-bucket"
   :aws_id            => "bun-0fa70206",
   :s3_prefix         => "win02",
   :aws_start_time    => "2008-10-14T13:00:29.000Z",
   :aws_error_message => "User has requested bundling operation cancellation",
   :aws_state         => "failed",
   :aws_update_time   => "2008-10-14T13:01:31.000Z",
   :aws_error_code    => "Client.Cancelled",
   :aws_instance_id   => "i-e3e24e8a"}
# File lib/ec2/ec2.rb, line 803
def cancel_bundle_task(bundle_id)
  link = generate_request("CancelBundleTask", {'BundleId' => bundle_id})
  request_info(link, QEc2BundleInstanceParser.new)
rescue Exception
  on_exception
end
confirm_product_instance(instance, product_code) click to toggle source

Return the product code attached to instance or nil otherwise.

ec2.confirm_product_instance('ami-e444444d','12345678') #=> nil
ec2.confirm_product_instance('ami-e444444d','00001111') #=> "000000000888"
# File lib/ec2/ec2.rb, line 456
def confirm_product_instance(instance, product_code)
  link = generate_request("ConfirmProductInstance", {'ProductCode' => product_code,
                                                     'InstanceId'  => instance})
  request_info(link, QEc2ConfirmProductInstanceParser.new(:logger => @logger))
end
create_image(instance_id, name, description="") click to toggle source

Creates an Amazon EBS-backed AMI from an Amazon EBS-backed instance Instance must be either the running or stopped state

ec2.create_image('i-4jhdmaw', 'New image')

# File lib/ec2/ec2.rb, line 1264
def create_image(instance_id, name, description="")
  link = generate_request("CreateImage",
                          "InstanceId" => instance_id,
                          "Name" => name,
                          "Description" => description)
  request_info(link, QEc2CreateImageParser.new(:logger => @logger))
rescue
    on_exception
end
create_key_pair(name) click to toggle source

Create new SSH key. Returns a hash of the key's data or an exception.

ec2.create_key_pair('my_awesome_key') #=>
  {:aws_key_name    => "my_awesome_key",
   :aws_fingerprint => "01:02:03:f4:25:e6:97:e8:9b:02:1a:26:32:4e:58:6b:7a:8c:9f:03",
   :aws_material    => "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAK...Q8MDrCbuQ=\n-----END RSA PRIVATE KEY-----"}
# File lib/ec2/ec2.rb, line 1022
def create_key_pair(name)
  link = generate_request("CreateKeyPair",
                          'KeyName' => name.to_s)
  request_info(link, QEc2CreateKeyPairParser.new(:logger => @logger))
rescue Exception
  on_exception
end
create_security_group(name, description) click to toggle source

Create new Security Group. Returns true or an exception.

ec2.create_security_group('default-1',"Default allowing SSH, HTTP, and HTTPS ingress") #=> true
# File lib/ec2/ec2.rb, line 874
def create_security_group(name, description)
  # EC2 doesn't like an empty description...
  description = " " if Aws::Utils.blank?(description)
  link = generate_request("CreateSecurityGroup",
                          'GroupName'        => name.to_s,
                          'GroupDescription' => description.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
create_snapshot(volume_id, options={}) click to toggle source

Create a snapshot of specified volume.

ec2.create_snapshot('vol-898a6fe0') #=>
    {:aws_volume_id  => "vol-fd9f7a94",
     :aws_started_at => Tue Jun 24 18:40:40 UTC 2008,
     :aws_progress   => "",
     :aws_status     => "pending",
     :aws_id         => "snap-d56783bc"}
# File lib/ec2/ec2.rb, line 1363
def create_snapshot(volume_id, options={})
  link = generate_request("CreateSnapshot", options.merge({"VolumeId" => volume_id.to_s}))
  request_info(link, QEc2CreateSnapshotParser.new(:logger => @logger))
rescue Exception
  on_exception
end
create_subnet(vpc_id, cidr_block, availability_zone = nil) click to toggle source

Create subnet in a VPC docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-CreateSubnet.html

ec2.create_subnet(vpc_id, cidr_block) ec2.create_subnet(vpc_id, cidr_block, availability_zone))

# File lib/ec2/ec2.rb, line 1528
def create_subnet(vpc_id, cidr_block, availability_zone = nil)
  params = { "VpcId" => vpc_id, "CidrBlock" => cidr_block }
  params["AvailabilityZone"] = availability_zone if availability_zone
  link = generate_request("CreateSubnet", params)
  request_info(link, QEc2SubnetsParser.new("subnet", :logger => @logger))
rescue Exception
  on_exception
end
create_tag(resource_id, key, value = nil) click to toggle source

Add/replace one tag to a resource docs.amazonwebservices.com/AWSEC2/latest/APIReference/index.html?ApiReference_query_CreateTags.html

ec2.create_tag('ami-1a2b3c4d', 'webserver') #=> true
ec2.create_tag('i-7f4d3a2b',   'stack', 'Production') #=> true
# File lib/ec2/ec2.rb, line 1427
def create_tag(resource_id, key, value = nil)
  link = generate_request("CreateTags",
                          "ResourceId.1" => resource_id.to_s,
                          "Tag.1.Key"    => key.to_s,
                          "Tag.1.Value"  => value.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
create_volume(snapshot_id, size, zone) click to toggle source

Create new EBS volume based on previously created snapshot. Size in Gigabytes.

ec2.create_volume('snap-000000', 10, zone) #=>
    {:snapshot_id    => "snap-e21df98b",
     :aws_status     => "creating",
     :aws_id         => "vol-fc9f7a95",
     :zone           => "merlot",
     :aws_created_at => Tue Jun 24 18:13:32 UTC 2008,
     :aws_size       => 94}
# File lib/ec2/ec2.rb, line 1236
def create_volume(snapshot_id, size, zone)
  params = {'Size' => size.to_s, 'AvailabilityZone' => zone.to_s}
  params['SnapshotId'] = snapshot_id if snapshot_id && snapshot_id.length > 0 # snapshotId is conditional
  link = generate_request("CreateVolume",
                          params)
  request_info(link, QEc2CreateVolumeParser.new(:logger => @logger))
rescue Exception
  on_exception
end
create_vpc(cidr_block = "10.0.0.0/16") click to toggle source

Create VPC docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-CreateVpc.html

ec2.create_vpc(“10.0.0.0/16”) FIXME: EVen though the EC2 docs describe the parameter instanceTenancy, I could not get it to recognize that

# File lib/ec2/ec2.rb, line 1484
def create_vpc(cidr_block = "10.0.0.0/16")
  params = { "CidrBlock" => cidr_block }
  link = generate_request("CreateVpc", params)
  request_info(link, QEc2VpcsParser.new("vpc", :logger => @logger))
rescue Exception
  on_exception
end
delete_key_pair(name) click to toggle source

Delete a key pair. Returns true or an exception.

ec2.delete_key_pair('my_awesome_key') #=> true
# File lib/ec2/ec2.rb, line 1051
def delete_key_pair(name)
  link = generate_request("DeleteKeyPair",
                          'KeyName' => name.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
delete_security_group(name) click to toggle source

Remove Security Group. Returns true or an exception.

ec2.delete_security_group('default-1') #=> true
# File lib/ec2/ec2.rb, line 889
def delete_security_group(name)
  link = generate_request("DeleteSecurityGroup",
                          'GroupName' => name.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
delete_snapshot(snapshot_id) click to toggle source

Delete the specified snapshot.

ec2.delete_snapshot('snap-55a5403c') #=> true
# File lib/ec2/ec2.rb, line 1413
def delete_snapshot(snapshot_id)
  link = generate_request("DeleteSnapshot",
                          "SnapshotId" => snapshot_id.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
delete_subnet(subnet_id) click to toggle source

Delete Subnet docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DeleteSubnet.html

ec2.delete_subnet(subnet_id)

# File lib/ec2/ec2.rb, line 1562
def delete_subnet(subnet_id)
  params = { "SubnetId" => subnet_id }
  link = generate_request("DeleteSubnet", params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
delete_tag(resource_id, key, value = nil) click to toggle source

Delete one or all tags from a resource docs.amazonwebservices.com/AWSEC2/latest/APIReference/index.html?ApiReference_query_DeleteTags.html

ec2.delete_tag('i-7f4d3a2b', 'stack') #=> true
ec2.delete_tag('i-7f4d3a2b', 'stack', 'Production') #=> true

“If you omit Tag.n.Value, we delete the tag regardless of its value. If you specify this parameter with an empty string as the value, we delete the key only if its value is an empty string.” docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference_query_DeleteTags.html

# File lib/ec2/ec2.rb, line 1464
def delete_tag(resource_id, key, value = nil)
  request_args = {"ResourceId.1" => resource_id.to_s, "Tag.1.Key" => key.to_s}
  request_args["Tag.1.Value"] = value.to_s if value

  link = generate_request("DeleteTags", request_args)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
delete_volume(volume_id) click to toggle source

Delete the specified EBS volume. This does not deletes any snapshots created from this volume.

ec2.delete_volume('vol-b48a6fdd') #=> true
# File lib/ec2/ec2.rb, line 1251
def delete_volume(volume_id)
  link = generate_request("DeleteVolume",
                          "VolumeId" => volume_id.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
delete_vpc(vpc_id) click to toggle source

Delete VPC docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DeleteVpc.html

ec2.delete_vpc(vpc_id)

# File lib/ec2/ec2.rb, line 1515
def delete_vpc(vpc_id)
  params = { "VpcId" => vpc_id }
  link = generate_request("DeleteVpc", params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
deregister_image(image_id) click to toggle source

Deregister image at Amazon. Returns true or an exception.

ec2.deregister_image('ami-e444444d') #=> true
# File lib/ec2/ec2.rb, line 289
def deregister_image(image_id)
  link = generate_request("DeregisterImage",
                          'ImageId' => image_id.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
describe_addresses(list=[]) click to toggle source

List elastic IP addresses assigned to your account. Returns an array of 2 keys (:instance_id and :public_ip) hashes:

ec2.describe_addresses  #=> [{:instance_id=>"i-d630cbbf", :public_ip=>"75.101.154.140"},
                             {:instance_id=>nil, :public_ip=>"75.101.154.141"}]

ec2.describe_addresses('75.101.154.140') #=> [{:instance_id=>"i-d630cbbf", :public_ip=>"75.101.154.140"}]
# File lib/ec2/ec2.rb, line 1097
def describe_addresses(list=[])
  link = generate_request("DescribeAddresses",
                          hash_params('PublicIp', list.to_a))
  request_cache_or_info :describe_addresses, link, QEc2DescribeAddressesParser, @@bench, list.nil? || list.empty?
rescue Exception
  on_exception
end
describe_availability_zones(list=[]) click to toggle source

Describes availability zones that are currently available to the account and their states. Returns an array of 2 keys (:zone_name and :zone_state) hashes:

ec2.describe_availability_zones  #=> [{:region_name=>"us-east-1",
                                       :zone_name=>"us-east-1a",
                                       :zone_state=>"available"}, ... ]

ec2.describe_availability_zones('us-east-1c') #=> [{:region_name=>"us-east-1",
                                                    :zone_state=>"available",
                                                    :zone_name=>"us-east-1c"}]
# File lib/ec2/ec2.rb, line 1146
def describe_availability_zones(list=[])
  link = generate_request("DescribeAvailabilityZones",
                          hash_params('ZoneName', list.to_a))
  request_cache_or_info :describe_availability_zones, link, QEc2DescribeAvailabilityZonesParser, @@bench, list.nil? || list.empty?
rescue Exception
  on_exception
end
describe_availability_zones2(options={}) click to toggle source

This is using the new way, but not sure it's backwrads compatible

# File lib/ec2/ec2.rb, line 1155
def describe_availability_zones2(options={})
  link = generate_request("DescribeAvailabilityZones", options={})
  request_info_xml_simple(self.class.connection_name, @params, link, @logger,
                          :group_tags     =>{"DBInstances"      =>"DBInstance",
                                             "DBParameterGroups"=>"DBParameterGroup",
                                             "DBSecurityGroups" =>"DBSecurityGroup",
                                             "EC2SecurityGroups"=>"EC2SecurityGroup",
                                             "IPRanges"         =>"IPRange"},
                          :force_array    =>["DBInstances",
                                             "DBParameterGroups",
                                             "DBSecurityGroups",
                                             "EC2SecurityGroups",
                                             "IPRanges"],
                          :pull_out_array =>options[:pull_out_array],
                          :pull_out_single=>options[:pull_out_single],
                          :wrapper        =>options[:wrapper])
rescue Exception
  on_exception
end
describe_bundle_tasks(list=[]) click to toggle source

Describe the status of the Windows AMI bundlings. If list is omitted the returns the whole list of tasks.

ec2.describe_bundle_tasks(['bun-4fa74226']) #=>
  [{:s3_bucket         => "my-awesome-bucket"
    :aws_id            => "bun-0fa70206",
    :s3_prefix         => "win1pr",
    :aws_start_time    => "2008-10-14T16:27:57.000Z",
    :aws_update_time   => "2008-10-14T16:37:10.000Z",
    :aws_error_code    => "Client.S3Error",
    :aws_error_message =>
     "AccessDenied(403)- Invalid according to Policy: Policy Condition failed: [\"eq\", \"$acl\", \"aws-exec-read\"]",
    :aws_state         => "failed",
    :aws_instance_id   => "i-e3e24e8a"}]
# File lib/ec2/ec2.rb, line 783
def describe_bundle_tasks(list=[])
  link = generate_request("DescribeBundleTasks", hash_params('BundleId', list.to_a))
  request_info(link, QEc2DescribeBundleTasksParser.new)
rescue Exception
  on_exception
end
describe_image_attribute(image_id, attribute='launchPermission') click to toggle source

Describe image attributes. Currently 'launchPermission', 'productCodes', 'kernel', 'ramdisk' and 'blockDeviceMapping' are supported.

ec2.describe_image_attribute('ami-e444444d') #=> {:groups=>["all"], :users=>["000000000777"]}
# File lib/ec2/ec2.rb, line 302
def describe_image_attribute(image_id, attribute='launchPermission')
  link = generate_request("DescribeImageAttribute",
                          'ImageId'   => image_id,
                          'Attribute' => attribute)
  request_info(link, QEc2DescribeImageAttributeParser.new(:logger => @logger))
rescue Exception
  on_exception
end
describe_images(list=[], image_type=nil) click to toggle source

Retrieve a list of images. Returns array of hashes describing the images or an exception: image_type = 'machine' || 'kernel' || 'ramdisk'

ec2.describe_images #=>
  [{:aws_owner => "522821470517",
    :aws_id => "ami-e4b6538d",
    :aws_state => "available",
    :aws_location => "marcins_cool_public_images/ubuntu-6.10.manifest.xml",
    :aws_is_public => true,
    :aws_architecture => "i386",
    :aws_image_type => "machine"},
   {...},
   {...} ]

If list param is set, then retrieve information about the listed images only:

ec2.describe_images(['ami-e4b6538d']) #=>
  [{:aws_owner => "522821470517",
    :aws_id => "ami-e4b6538d",
    :aws_state => "available",
    :aws_location => "marcins_cool_public_images/ubuntu-6.10.manifest.xml",
    :aws_is_public => true,
    :aws_architecture => "i386",
    :aws_image_type => "machine"}]
# File lib/ec2/ec2.rb, line 240
def describe_images(list=[], image_type=nil)
  list      = list.to_a
  cache_for = list.empty? && !image_type ? :describe_images : nil
  ec2_describe_images({'ImageId' => list}, image_type, cache_for)
end
describe_images_by_executable_by(list=['self'], image_type=nil) click to toggle source

Example:

ec2.describe_images_by_executable_by('522821470517')
ec2.describe_images_by_executable_by('self')
ec2.describe_images_by_executable_by('all')
# File lib/ec2/ec2.rb, line 265
def describe_images_by_executable_by(list=['self'], image_type=nil)
  list      = list.to_a
  cache_for = list==['self'] && !image_type ? :describe_images_by_executable_by : nil
  ec2_describe_images({'ExecutableBy' => list}, image_type, cache_for)
end
describe_images_by_owner(list=['self'], image_type=nil) click to toggle source

Example:

ec2.describe_images_by_owner('522821470517')
ec2.describe_images_by_owner('self')
# File lib/ec2/ec2.rb, line 252
def describe_images_by_owner(list=['self'], image_type=nil)
  list      = list.to_a
  cache_for = list==['self'] && !image_type ? :describe_images_by_owner : nil
  ec2_describe_images({'Owner' => list}, image_type, cache_for)
end
describe_instances(list=[]) click to toggle source

Retrieve information about EC2 instances. If list is omitted then returns the list of all instances.

ec2.describe_instances #=>
  [{:aws_image_id       => "ami-e444444d",
    :aws_reason         => "",
    :aws_state_code     => "16",
    :aws_owner          => "000000000888",
    :aws_instance_id    => "i-123f1234",
    :aws_reservation_id => "r-aabbccdd",
    :aws_state          => "running",
    :dns_name           => "domU-12-34-67-89-01-C9.usma2.compute.amazonaws.com",
    :ssh_key_name       => "staging",
    :aws_groups         => ["default"],
    :private_dns_name   => "domU-12-34-67-89-01-C9.usma2.compute.amazonaws.com",
    :aws_instance_type  => "m1.small",
    :aws_launch_time    => "2008-1-1T00:00:00.000Z"},
    :aws_availability_zone => "us-east-1b",
    :aws_kernel_id      => "aki-ba3adfd3",
    :aws_ramdisk_id     => "ari-badbad00",
    :monitoring_state         => ...,
     ..., {...}]
# File lib/ec2/ec2.rb, line 442
def describe_instances(list=[])
  link = generate_request("DescribeInstances", hash_params('InstanceId', list.to_a))
  request_cache_or_info(:describe_instances, link, QEc2DescribeInstancesParser, @@bench, list.nil? || list.empty?) do |parser|
    get_desc_instances(parser.result)
  end
rescue Exception
  on_exception
end
describe_key_pairs(list=[]) click to toggle source

Retrieve a list of SSH keys. Returns an array of keys or an exception. Each key is represented as a two-element hash.

ec2.describe_key_pairs #=>
  [{:aws_fingerprint=> "01:02:03:f4:25:e6:97:e8:9b:02:1a:26:32:4e:58:6b:7a:8c:9f:03", :aws_key_name=>"key-1"},
   {:aws_fingerprint=> "1e:29:30:47:58:6d:7b:8c:9f:08:11:20:3c:44:52:69:74:80:97:08", :aws_key_name=>"key-2"},
    ..., {...} ]
# File lib/ec2/ec2.rb, line 1008
def describe_key_pairs(list=[])
  link = generate_request("DescribeKeyPairs", hash_params('KeyName', list.to_a))
  request_cache_or_info :describe_key_pairs, link, QEc2DescribeKeyPairParser, @@bench, list.nil? || list.empty?
rescue Exception
  on_exception
end
describe_owned_snapshots(list=[]) click to toggle source
# File lib/ec2/ec2.rb, line 1342
def describe_owned_snapshots(list=[])
  params = {"Owner" => "self"}
  snap_ids = hash_params('SnapshotId', list.to_a)
  params.update(snap_ids)
  link = generate_request("DescribeSnapshots",
                          params)
  request_cache_or_info :describe_owned_snapshots, link, QEc2DescribeSnapshotsParser, @@bench, list.nil? || list.empty?
rescue Exception
  on_exception
end
describe_regions(list=[]) click to toggle source

Describe regions.

ec2.describe_regions  #=> ["eu-west-1", "us-east-1"]
# File lib/ec2/ec2.rb, line 1184
def describe_regions(list=[])
  link = generate_request("DescribeRegions",
                          hash_params('RegionName', list.to_a))
  request_cache_or_info :describe_regions, link, QEc2DescribeRegionsParser, @@bench, list.nil? || list.empty?
rescue Exception
  on_exception
end
describe_security_groups(list=[]) click to toggle source

Retrieve Security Group information. If list is omitted the returns the whole list of groups.

ec2.describe_security_groups #=>
  [{:aws_group_name  => "default-1",
    :aws_owner       => "000000000888",
    :aws_description => "a default security group",
    :aws_perms       =>
      [ {:protocol => "tcp", :from_port=>"1000", :to_port=>"2000",
         :ip_ranges=>[{cidr_ip=>"10.1.2.3/32"}, {cidr_ip=>"192.168.1.10/24"}],
         :groups =>  [{:owner=>"123456789012", :group_name="default"}] },

        {:protocol ="icmp", :from_port="-1", :to_port=>"-1",
         :ip_ranges=>[{:cidr_ip=>"0.0.0.0/0"}],
         :groups=>[] },

        {:protocol=>"udp", :from_port=>"0", :to_port=>"65535",
         :ip_ranges=>[],
         :groups=>[{:owner=>"123456789012", :group_name=>"newgroup"}, {:owner=>"123456789012", :group_name=>"default"}],

        {:protocol=>"tcp", :from_port="22", :to_port=>"22",
         :ip_ranges=>[{:cidr_ip=>"0.0.0.0/0"}],
         :groups=>[{:owner=>"", :group_name=>"default"}] },

       ..., {...}
      ]
# File lib/ec2/ec2.rb, line 840
def describe_security_groups(list=[])
  link = generate_request("DescribeSecurityGroups", hash_params('GroupName', list.to_a))
  request_cache_or_info(:describe_security_groups, link, QEc2DescribeSecurityGroupsParser, @@bench, list.nil? || list.empty?) do |parser|
  result = []
  parser.result.each do |item|
    perms = []
    item.ipPermissions.each do |perm|
      current = {:from_port => perm.fromPort,
                 :to_port => perm.toPort,
                 :protocol => perm.ipProtocol,
                 :groups => [], :ip_ranges => []}
      perm.groups.each do |ngroup|
         current[:groups] << {:group_name => ngroup.groupName, :owner => ngroup.userId}
      end
      perm.ipRanges.each do |cidr_ip|
         current[:ip_ranges] << {:cidr_ip => cidr_ip.cidrIp}
      end
    perms << current
    end
    result << {:aws_owner       => item.ownerId,
               :aws_group_name  => item.groupName,
               :aws_description => item.groupDescription,
               :aws_perms       => perms}
    end
    result
  end
rescue Exception
  on_exception
end
describe_snapshots(list=[]) click to toggle source

Describe all EBS snapshots.

ec2.describe_snapshots #=>

[ { :aws_progress   => "100%",
    :aws_status     => "completed",
    :aws_id         => "snap-72a5401b",
    :aws_volume_id  => "vol-5582673c",
    :aws_started_at => "2008-02-23T02:50:48.000Z"},
  { :aws_progress   => "100%",
    :aws_status     => "completed",
    :aws_id         => "snap-75a5401c",
    :aws_volume_id  => "vol-5582673c",
    :aws_started_at => "2008-02-23T16:23:19.000Z" },...]
# File lib/ec2/ec2.rb, line 1334
def describe_snapshots(list=[])
  link = generate_request("DescribeSnapshots",
                          hash_params('SnapshotId', list.to_a))
  request_cache_or_info :describe_snapshots, link, QEc2DescribeSnapshotsParser, @@bench, list.nil? || list.empty?
rescue Exception
  on_exception
end
describe_subnets(*args) click to toggle source

Describe subnets docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeSubnets.html

ec2.describe_subnets ecs.describe_subnets(subnetId1, SubnetId2, …,

'Filter.1.Name' => 'state',
'Filter.1.Value.1' => 'pending',
'Filter.2.Name' => ...)
# File lib/ec2/ec2.rb, line 1545
def describe_subnets(*args)
  if args.last.is_a?(Hash)
    params = args.pop.dup
  else
    params = {}
  end
  1.upto(args.size) { |i| params["SubnetId.#{i}"] = args[i-1] }
  link = generate_request("DescribeSubnets", params)
  request_info(link, QEc2SubnetsParser.new("item", :logger => @logger))
rescue Exception
  on_exception
end
describe_tags(filters = {}) click to toggle source

Describe tags docs.amazonwebservices.com/AWSEC2/latest/APIReference/index.html?ApiReference_query_DescribeTags.html

ec2.describe_tags
ec2.describe_tags(
  'Filter.1.Name' => 'resource-type', 'Filter.1.Value.1' => 'instance',
  'Filter.2.Name' => 'value',         'Filter.2.Value.1' => 'Test', 'Filter.2.Value.2' => 'Production'
)
# File lib/ec2/ec2.rb, line 1446
def describe_tags(filters = {})
  link = generate_request("DescribeTags", filters)
  request_info(link, QEc2DescribeTagsParser.new(:logger => @logger))
rescue Exception
  on_exception
end
describe_volumes(list=[]) click to toggle source

Describe all EBS volumes.

ec2.describe_volumes #=>
    [{:aws_size              => 94,
      :aws_device            => "/dev/sdc",
      :aws_attachment_status => "attached",
      :zone                  => "merlot",
      :snapshot_id           => nil,
      :aws_attached_at       => Wed Jun 18 08:19:28 UTC 2008,
      :aws_status            => "in-use",
      :aws_id                => "vol-60957009",
      :aws_created_at        => Wed Jun 18 08:19:20s UTC 2008,
      :aws_instance_id       => "i-c014c0a9"},
     {:aws_size       => 1,
      :zone           => "merlot",
      :snapshot_id    => nil,
      :aws_status     => "available",
      :aws_id         => "vol-58957031",
      :aws_created_at => Wed Jun 18 08:19:21 UTC 2008,}, ... ]
# File lib/ec2/ec2.rb, line 1217
def describe_volumes(list=[])
  link = generate_request("DescribeVolumes",
                          hash_params('VolumeId', list.to_a))
  request_cache_or_info :describe_volumes, link, QEc2DescribeVolumesParser, @@bench, list.nil? || list.empty?
rescue Exception
  on_exception
end
describe_vpcs(*args) click to toggle source

Describe VPC's docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeVpcs.html

ec2.describe_vpcs ec2.describe_vpcs(vpcId1, vpcId2, 'Filter.1.Name' => 'state', 'Filter.1.Value' = > 'pending', …)

# File lib/ec2/ec2.rb, line 1498
def describe_vpcs(*args)
  if args.last.is_a?(Hash)
    params = args.pop.dup
  else
    params = {}
  end
  1.upto(args.size) { |i| params["VpcId.#{i}"] = args[i-1] }
  link = generate_request("DescribeVpcs", params)
  request_info(link, QEc2VpcsParser.new("item", :logger => @logger))
rescue Exception
  on_exception
end
detach_volume(volume_id, instance_id=nil, device=nil, force=nil) click to toggle source

Detach the specified EBS volume from the instance to which it is attached.

ec2.detach_volume('vol-898a6fe0') #=>
  { :aws_instance_id => "i-7c905415",
    :aws_device      => "/dev/sdh",
    :aws_status      => "detaching",
    :aws_attached_at => "2008-03-28T14:38:34.000Z",
    :aws_id          => "vol-898a6fe0"}
# File lib/ec2/ec2.rb, line 1303
def detach_volume(volume_id, instance_id=nil, device=nil, force=nil)
  hash = {"VolumeId" => volume_id.to_s}
  hash["InstanceId"] = instance_id.to_s unless Aws::Utils.blank?(instance_id)
  hash["Device"] = device.to_s unless Aws::Utils.blank?(device)
  hash["Force"] = 'true' if     force
  #
  link = generate_request("DetachVolume", hash)
  request_info(link, QEc2AttachAndDetachVolumeParser.new(:logger => @logger))
rescue Exception
  on_exception
end
disassociate_address(public_ip) click to toggle source

Disassociate the specified elastic IP address from the instance to which it is assigned. Returns true or an exception.

ec2.disassociate_address('75.101.154.140') #=> true
# File lib/ec2/ec2.rb, line 1110
def disassociate_address(public_ip)
  link = generate_request("DisassociateAddress",
                          "PublicIp" => public_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
get_console_output(instance_id) click to toggle source

Retreive EC2 instance OS logs. Returns a hash of data or an exception.

ec2.get_console_output('i-f222222d') =>
  {:aws_instance_id => 'i-f222222d',
   :aws_timestamp   => "2007-05-23T14:36:07.000-07:00",
   :timestamp       => Wed May 23 21:36:07 UTC 2007,          # Time instance
   :aws_output      => "Linux version 2.6.16-xenU (builder@patchbat.amazonsa) (gcc version 4.0.1 20050727 ..."
# File lib/ec2/ec2.rb, line 672
def get_console_output(instance_id)
  link = generate_request("GetConsoleOutput", {'InstanceId.1' => instance_id})
  request_info(link, QEc2GetConsoleOutputParser.new(:logger => @logger))
rescue Exception
  on_exception
end
get_initial_password(instance_id, private_key) click to toggle source

Get initial Windows Server setup password from an instance console output.

my_awesome_key = ec2.create_key_pair('my_awesome_key') #=>
  {:aws_key_name    => "my_awesome_key",
   :aws_fingerprint => "01:02:03:f4:25:e6:97:e8:9b:02:1a:26:32:4e:58:6b:7a:8c:9f:03",
   :aws_material    => "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAK...Q8MDrCbuQ=\n-----END RSA PRIVATE KEY-----"}

my_awesome_instance = ec2.run_instances('ami-a000000a',1,1,['my_awesome_group'],'my_awesome_key', 'WindowsInstance!!!') #=>
 [{:aws_image_id       => "ami-a000000a",
   :aws_instance_id    => "i-12345678",
   ...
   :aws_availability_zone => "us-east-1b"
   }]

# wait until instance enters 'operational' state and get it's initial password

puts ec2.get_initial_password(my_awesome_instance[:aws_instance_id], my_awesome_key[:aws_material]) #=> "MhjWcgZuY6"
# File lib/ec2/ec2.rb, line 712
def get_initial_password(instance_id, private_key)
  console_output   = get_console_output(instance_id)
  crypted_password = console_output[:aws_output][%r{<Password>(.+)</Password>}] && $1
  unless crypted_password
    raise AwsError.new("Initial password was not found in console output for #{instance_id}")
  else
    OpenSSL::PKey::RSA.new(private_key).private_decrypt(Base64.decode64(crypted_password))
  end
rescue Exception
  on_exception
end
import_key_pair(name, public_key) click to toggle source

Import existing SSH key. Returns a hash of the key's data or an exception.

ec2.import_key_pair('my_awesome_key',
                    'ssh-rsa AABB3NzaC1yc2FSAAADAQABAAABAQCntvz2Cpx8EE4lBRjQKOtwNaGeJXjgnFLaxnQH4HB+dRTinjlew+153KLCjAMbbanD9Wym/b1FfSHywP299RdTPpBZ2QD7Hh7qKp8penGszFQbaSewYQTBP9Htjn7NDg3VeVcIx0LP3lmp4ZNnYDZGLKCGJJ+ldT/cljW3FAA2/xwco98BujLlKUcU/BZlZ4zvESM3S0gF3pgOjuz2UKAEbsbuuaEQP88NZ/GXXIUgGNFoJSpxDrNCHA7pap/3gdyPq3zTkt4YK/bSxSJ24FMfYtehB36V9rqV8RsIro+yrzRBW4XcA976OKQbh5pS75rp herp@derp')
#=>
  {:aws_key_name    => "my_awesome_key",
   :aws_fingerprint => "01:02:03:f4:25:e6:97:e8:9b:02:1a:26:32:4e:58:6b:7a:8c:9f:03"}
# File lib/ec2/ec2.rb, line 1038
def import_key_pair(name, public_key)
  link = generate_request("ImportKeyPair",
                          "KeyName" => name.to_s,
                          "PublicKeyMaterial"=>Base64.encode64(public_key.to_s))
  request_info(link, QEc2ImportPublicKeyParser.new(:logger => @logger))
  rescue Exception
    on_exception
end
launch_instances(image_id, options={}) click to toggle source

Launch new EC2 instances. Returns a list of launched instances or an exception.

lparams keys (default values in parenthesis):

:min_count              fixnum, (1)
:max_count              fixnum, (1)
:group_ids              array or string ([] == 'default')
:instance_type          string (DEFAULT_INSTACE_TYPE)
:addressing_type        string (DEFAULT_ADDRESSING_TYPE
:key_name               string
:kernel_id              string
:ramdisk_id             string
:availability_zone      string
:block_device_mappings  string
:user_data              string
:monitoring_enabled     boolean (default=false)

ec2.launch_instances('ami-e444444d', :group_ids => 'my_awesome_group',
                                     :user_data => "Woohoo!!!",
                                     :addressing_type => "public",
                                     :key_name => "my_awesome_key",
                                     :availability_zone => "us-east-1c") #=>
 [{:aws_image_id       => "ami-e444444d",
   :aws_reason         => "",
   :aws_state_code     => "0",
   :aws_owner          => "000000000888",
   :aws_instance_id    => "i-123f1234",
   :aws_reservation_id => "r-aabbccdd",
   :aws_state          => "pending",
   :dns_name           => "",
   :ssh_key_name       => "my_awesome_key",
   :aws_groups         => ["my_awesome_group"],
   :private_dns_name   => "",
   :aws_instance_type  => "m1.small",
   :aws_launch_time    => "2008-1-1T00:00:00.000Z",
   :aws_ramdisk_id     => "ari-8605e0ef"
   :aws_kernel_id      => "aki-9905e0f0",
   :ami_launch_index   => "0",
   :aws_availability_zone => "us-east-1c"
   }]
# File lib/ec2/ec2.rb, line 545
def launch_instances(image_id, options={})
  @logger.info("Launching instance of image #{image_id} for #{@aws_access_key_id}, " +
                   "key: #{options[:key_name]}, groups: #{(options[:group_ids]).to_a.join(',')}")
  # careful: keyName and securityGroups may be nil
  params = hash_params('SecurityGroup', options[:group_ids].to_a)
  params.update({'ImageId'        => image_id,
                 'MinCount'       => (options[:min_count] || 1).to_s,
                 'MaxCount'       => (options[:max_count] || 1).to_s,
                 'AddressingType' => options[:addressing_type] || DEFAULT_ADDRESSING_TYPE,
                 'InstanceType'   => options[:instance_type] || DEFAULT_INSTANCE_TYPE})
  # optional params
  params['KeyName'] = options[:key_name] unless Aws::Utils.blank?(options[:key_name])
  params['KernelId'] = options[:kernel_id] unless Aws::Utils.blank?(options[:kernel_id])
  params['RamdiskId'] = options[:ramdisk_id] unless Aws::Utils.blank?(options[:ramdisk_id])
  params['Placement.AvailabilityZone'] = options[:availability_zone] unless Aws::Utils.blank?(options[:availability_zone])
  params['BlockDeviceMappings'] = options[:block_device_mappings] unless Aws::Utils.blank?(options[:block_device_mappings])
  params['Monitoring.Enabled'] = options[:monitoring_enabled] unless Aws::Utils.blank?(options[:monitoring_enabled])
  params['SubnetId'] = options[:subnet_id] unless Aws::Utils.blank?(options[:subnet_id])
  params['AdditionalInfo'] = options[:additional_info] unless Aws::Utils.blank?(options[:additional_info])
  params['DisableApiTermination'] = options[:disable_api_termination].to_s unless options[:disable_api_termination].nil?
  params['InstanceInitiatedShutdownBehavior'] = options[:instance_initiated_shutdown_behavior] unless Aws::Utils.blank?(options[:instance_initiated_shutdown_behavior])
  unless Aws::Utils.blank?(options[:user_data])
    options[:user_data].strip!
    # Do not use CGI::escape(encode64(...)) as it is done in Amazons EC2 library.
    # Amazon 169.254.169.254 does not like escaped symbols!
    # And it doesn't like "\n" inside of encoded string! Grrr....
    # Otherwise, some of UserData symbols will be lost...
    params['UserData'] = Base64.encode64(options[:user_data]).delete("\n").strip unless Aws::Utils.blank?(options[:user_data])
  end
  unless Aws::Utils.blank?(options[:block_device_mappings])
    options[:block_device_mappings].size.times do |n|
      if options[:block_device_mappings][n][:virtual_name]
        params["BlockDeviceMapping.#{n+1}.VirtualName"] = options[:block_device_mappings][n][:virtual_name]
      end
      if options[:block_device_mappings][n][:device_name]
        params["BlockDeviceMapping.#{n+1}.DeviceName"] = options[:block_device_mappings][n][:device_name]
      end
      if options[:block_device_mappings][n][:ebs_snapshot_id]
        params["BlockDeviceMapping.#{n+1}.Ebs.SnapshotId"] = options[:block_device_mappings][n][:ebs_snapshot_id]
      end
    end
  end
  link      = generate_request("RunInstances", params)
  #debugger
  instances = request_info(link, QEc2DescribeInstancesParser.new(:logger => @logger))
  get_desc_instances(instances)
rescue Exception
  on_exception
end
manage_security_group_ingress(name, from_port, to_port, protocol, action, source_ip_ranges, source_groups = []) click to toggle source

Authorize OR Revoke ingress for security group, depending on the value of the 'action' parameter. If you 'authorize' then you allow instances that are member of some other security groups, or some range of ip addresses to open connections to instances in my group. Can specify an array of ip addresses, source groups or mix of both in a single rule:

ec2.manage_security_group_ingress('authorize', 'new_firewall', 80, 80, 'tcp', ['192.168.0.1/32', '10.0.0.1/24'],

[{'group_name'=>'default', 'owner'=>'297467797945'}, {'group_name'=>'test', 'owner'=>'123456789012'}])

ec2.manage_security_group_ingress('new_firewall', 0, 1000, 'udp', 'revoke', [],

[{'group_name'=>'default', 'owner'=>'123456789012'}])

ec2.manage_security_group_ingress('new_firewall', 0, 1000, 'udp', 'authorize', ['0.0.0.0/0'])

Similarly, if you specify 'revoke' as the action parameter then you will remove the specified source ip addresses or source groups from access to instances in the named group:

# File lib/ec2/ec2.rb, line 913
def manage_security_group_ingress(name, from_port, to_port, protocol, action, source_ip_ranges, source_groups = [])
  call_params = {  'GroupName'   => name.to_s,
                  'IpPermissions.1.IpProtocol' => protocol.to_s,
                   'IpPermissions.1.FromPort'   => from_port.to_s,
                   'IpPermissions.1.ToPort'     => to_port.to_s  }
  source_ip_ranges.each_index do |i|
    call_params.merge!({"IpPermissions.1.IpRanges.#{i+1}.CidrIp" => source_ip_ranges[i].to_s})
  end
  source_groups.each_index do |i|
    call_params.merge!({"IpPermissions.1.Groups.#{i+1}.GroupName" => source_groups[i]['group_name'].to_s,
                        "IpPermissions.1.Groups.#{i+1}.UserId"=> source_groups[i]['owner'].to_s.gsub(/-/,'')})
  end
  unless ['Authorize', 'Revoke'].include?(action.capitalize)
     raise AwsError.new("Invalid action #{action} - must be one of \'Authorize\' or \'Revoke\'")
  end
  link = generate_request("#{action.capitalize}SecurityGroupIngress", call_params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
  rescue Exception
    on_exception
end
modify_image_attribute(image_id, operation_type = nil, vars = {}) click to toggle source

Modify an image's attributes. It is recommended that you use #modify_image_launch_perm_add_users, #modify_image_launch_perm_remove_users, etc. instead of #modify_image_attribute because the signature of #modify_image_attribute may change with EC2 service changes.

operation_type : currently, only 'Add' & 'Remove' are supported.
vars:
  :user_group  : currently, only 'all' is supported.
  :user_id
  :product_code
  :description
# File lib/ec2/ec2.rb, line 335
def modify_image_attribute(image_id, operation_type = nil, vars = {})
  params = {'ImageId' => image_id }
  params.update(hash_params_with_suffix("LaunchPermission.#{operation_type}", 'UserId', vars[:user_id].to_a)) if vars[:user_id]
  params.update(hash_params_with_suffix("LaunchPermission.#{operation_type}", 'Group', vars[:user_group].to_a)) if vars[:user_group]
  params.update(hash_params('ProductCode', vars[:product_code])) if vars[:product_code]
  params.update('Description.Value' => vars[:description].to_s) if vars[:description]
  link = generate_request("ModifyImageAttribute", params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
modify_image_description(image_id, description='') click to toggle source

Change image description

ec2.modify_image_description('ami-e444444d','My new AMI') #=> true
# File lib/ec2/ec2.rb, line 393
def modify_image_description(image_id, description='')
  modify_image_attribute(image_id, nil, :description => description)
end
modify_image_launch_perm_add_groups(image_id, user_group=['all']) click to toggle source

Add image launch permissions for users groups (currently only 'all' is supported, which gives public launch permissions). Returns true or an exception.

ec2.modify_image_launch_perm_add_groups('ami-e444444d') #=> true
# File lib/ec2/ec2.rb, line 369
def modify_image_launch_perm_add_groups(image_id, user_group=['all'])
  modify_image_attribute(image_id, 'Add', :user_group => user_group.to_a)
end
modify_image_launch_perm_add_users(image_id, user_id=[]) click to toggle source

Grant image launch permissions to users. Parameter userId is a list of user AWS account ids. Returns true or an exception.

ec2.modify_image_launch_perm_add_users('ami-e444444d',['000000000777','000000000778']) #=> true
# File lib/ec2/ec2.rb, line 352
def modify_image_launch_perm_add_users(image_id, user_id=[])
  modify_image_attribute(image_id, 'Add', :user_id => user_id.to_a)
end
modify_image_launch_perm_remove_groups(image_id, user_group=['all']) click to toggle source

Remove image launch permissions for users groups (currently only 'all' is supported, which gives public launch permissions).

ec2.modify_image_launch_perm_remove_groups('ami-e444444d') #=> true
# File lib/ec2/ec2.rb, line 377
def modify_image_launch_perm_remove_groups(image_id, user_group=['all'])
  modify_image_attribute(image_id, 'Remove', :user_group => user_group.to_a)
end
modify_image_launch_perm_remove_users(image_id, user_id=[]) click to toggle source

Revokes image launch permissions for users. userId is a list of users AWS accounts ids. Returns true or an exception.

ec2.modify_image_launch_perm_remove_users('ami-e444444d',['000000000777','000000000778']) #=> true
# File lib/ec2/ec2.rb, line 360
def modify_image_launch_perm_remove_users(image_id, user_id=[])
  modify_image_attribute(image_id, 'Remove', :user_id => user_id.to_a)
end
modify_image_product_code(image_id, product_code=[]) click to toggle source

Add product code to image

ec2.modify_image_product_code('ami-e444444d','0ABCDEF') #=> true
# File lib/ec2/ec2.rb, line 385
def modify_image_product_code(image_id, product_code=[])
  modify_image_attribute(image_id, nil, :product_code => product_code.to_a)
end
monitor_instances(list=[]) click to toggle source
# File lib/ec2/ec2.rb, line 595
def monitor_instances(list=[])
  link = generate_request("MonitorInstances", hash_params('InstanceId', list.to_a))
  request_info(link, QEc2TerminateInstancesParser.new(:logger => @logger))
rescue Exception
  on_exception
end
reboot_instances(list) click to toggle source

Reboot an EC2 instance. Returns true or an exception.

ec2.reboot_instances(['i-f222222d','i-f222222e']) #=> true
# File lib/ec2/ec2.rb, line 683
def reboot_instances(list)
  link = generate_request("RebootInstances", hash_params('InstanceId', list.to_a))
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
register_image(image_location) click to toggle source

Register new image at Amazon. Returns new image id or an exception.

ec2.register_image('bucket/key/manifest') #=> 'ami-e444444d'
# File lib/ec2/ec2.rb, line 277
def register_image(image_location)
  link = generate_request("RegisterImage",
                          'ImageLocation' => image_location.to_s)
  request_info(link, QEc2RegisterImageParser.new(:logger => @logger))
rescue Exception
  on_exception
end
release_address(public_ip) click to toggle source

Release an elastic IP address associated with your account. Returns true or an exception.

ec2.release_address('75.101.154.140') #=> true
# File lib/ec2/ec2.rb, line 1123
def release_address(public_ip)
  link = generate_request("ReleaseAddress",
                          "PublicIp" => public_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
reset_image_attribute(image_id, attribute='launchPermission') click to toggle source

Reset image attribute. Currently, only 'launchPermission' is supported. Returns true or an exception.

ec2.reset_image_attribute('ami-e444444d') #=> true
# File lib/ec2/ec2.rb, line 315
def reset_image_attribute(image_id, attribute='launchPermission')
  link = generate_request("ResetImageAttribute",
                          'ImageId'   => image_id,
                          'Attribute' => attribute)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
revoke_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0') click to toggle source

Remove permission from a security group. Returns true or an exception. protocol is one of :'tcp'|'udp'|'icmp' ('tcp' is default).

ec2.revoke_security_group_IP_ingress('my_awesome_group', 80, 82, 'udp', '192.168.1.0/8') #=> true
# File lib/ec2/ec2.rb, line 984
def revoke_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0')
  link = generate_request("RevokeSecurityGroupIngress",
                          'GroupName'  => name.to_s,
                          'IpProtocol' => protocol.to_s,
                          'FromPort'   => from_port.to_s,
                          'ToPort'     => to_port.to_s,
                          'CidrIp'     => cidr_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
revoke_security_group_named_ingress(name, owner, group) click to toggle source

Revoke named ingress for security group.

ec2.revoke_security_group_named_ingress('my_awesome_group', aws_user_id, 'another_group_name') #=> true
# File lib/ec2/ec2.rb, line 953
def revoke_security_group_named_ingress(name, owner, group)
  link = generate_request("RevokeSecurityGroupIngress",
                          'GroupName'                  => name.to_s,
                          'SourceSecurityGroupName'    => group.to_s,
                          'SourceSecurityGroupOwnerId' => owner.to_s.gsub(/-/, ''))
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end
run_instances(image_id, min_count, max_count, group_ids, key_name, user_data='', addressing_type = nil, instance_type = nil, kernel_id = nil, ramdisk_id = nil, availability_zone = nil, block_device_mappings = nil) click to toggle source

DEPRECATED, USE #launch_instances instead.

Launch new EC2 instances. Returns a list of launched instances or an exception.

ec2.run_instances('ami-e444444d',1,1,['my_awesome_group'],'my_awesome_key', 'Woohoo!!!', 'public') #=>
 [{:aws_image_id       => "ami-e444444d",
   :aws_reason         => "",
   :aws_state_code     => "0",
   :aws_owner          => "000000000888",
   :aws_instance_id    => "i-123f1234",
   :aws_reservation_id => "r-aabbccdd",
   :aws_state          => "pending",
   :dns_name           => "",
   :ssh_key_name       => "my_awesome_key",
   :aws_groups         => ["my_awesome_group"],
   :private_dns_name   => "",
   :aws_instance_type  => "m1.small",
   :aws_launch_time    => "2008-1-1T00:00:00.000Z"
   :aws_ramdisk_id     => "ari-8605e0ef"
   :aws_kernel_id      => "aki-9905e0f0",
   :ami_launch_index   => "0",
   :aws_availability_zone => "us-east-1b"
   }]
# File lib/ec2/ec2.rb, line 486
def run_instances(image_id, min_count, max_count, group_ids, key_name, user_data='',
    addressing_type = nil, instance_type = nil,
    kernel_id = nil, ramdisk_id = nil, availability_zone = nil,
    block_device_mappings = nil)
  launch_instances(image_id, {:min_count             => min_count,
                              :max_count             => max_count,
                              :user_data             => user_data,
                              :group_ids             => group_ids,
                              :key_name              => key_name,
                              :instance_type         => instance_type,
                              :addressing_type       => addressing_type,
                              :kernel_id             => kernel_id,
                              :ramdisk_id            => ramdisk_id,
                              :availability_zone     => availability_zone,
                              :block_device_mappings => block_device_mappings
  })
end
start_instances(list=[]) click to toggle source

Start EBS-backed EC2 instances. Returns a list of instance state changes or an exception.

ec2.start_instances(['i-f222222d', 'i-f222222e']) #=>
  [{:aws_instance_id         => "i-f222222d",
    :aws_current_state_code  => 0,
    :aws_current_state       => "pending",
    :aws_prev_state_code     => 80,
    :aws_prev_state          => "stopped"},
   {:aws_instance_id         => "i-f222222e",
    :aws_current_state_code  => 0,
    :aws_current_state       => "pending",
    :aws_prev_state_code     => 80,
    :aws_prev_state          => "stopped"}]
# File lib/ec2/ec2.rb, line 658
def start_instances(list=[])
  link = generate_request("StartInstances", hash_params('InstanceId', list.to_a))
  request_info(link, QEc2StartInstancesParser.new(:logger => @logger))
rescue Exception
  on_exception
end
stop_instances(list=[]) click to toggle source

Stop EBS-backed EC2 instances. Returns a list of instance state changes or an exception.

ec2.stop_instances(['i-f222222d', 'i-f222222e']) #=>
  [{:aws_instance_id         => "i-f222222d",
    :aws_current_state_code  => 64,
    :aws_current_state       => "stopping",
    :aws_prev_state_code     => 16,
    :aws_prev_state          => "running"},
   {:aws_instance_id         => "i-f222222e",
    :aws_current_state_code  => 64,
    :aws_current_state       => "stopping",
    :aws_prev_state_code     => 16,
    :aws_prev_state          => "running"}]
# File lib/ec2/ec2.rb, line 637
def stop_instances(list=[])
  link = generate_request("StopInstances", hash_params('InstanceId', list.to_a))
  request_info(link, QEc2StopInstancesParser.new(:logger => @logger))
rescue Exception
  on_exception
end
terminate_instances(list=[]) click to toggle source

Terminates EC2 instances. Returns a list of termination params or an exception.

ec2.terminate_instances(['i-f222222d','i-f222222e']) #=>
  [{:aws_shutdown_state      => "shutting-down",
    :aws_instance_id         => "i-f222222d",
    :aws_shutdown_state_code => 32,
    :aws_prev_state          => "running",
    :aws_prev_state_code     => 16},
   {:aws_shutdown_state      => "shutting-down",
    :aws_instance_id         => "i-f222222e",
    :aws_shutdown_state_code => 32,
    :aws_prev_state          => "running",
    :aws_prev_state_code     => 16}]
# File lib/ec2/ec2.rb, line 616
def terminate_instances(list=[])
  link = generate_request("TerminateInstances", hash_params('InstanceId', list.to_a))
  request_info(link, QEc2TerminateInstancesParser.new(:logger => @logger))
rescue Exception
  on_exception
end
try_create_snapshot(volume_id, connect_timeout = nil, read_timeout = nil) click to toggle source

Create a snapshot of specified volume, but with the normal retry algorithms disabled. This method will return immediately upon error. The user can specify connect and read timeouts (in s) for the connection to AWS. If the user does not specify timeouts, #try_create_snapshot uses the default values in Rightscale::HttpConnection.

ec2.try_create_snapshot('vol-898a6fe0') #=>
    {:aws_volume_id  => "vol-fd9f7a94",
     :aws_started_at => Tue Jun 24 18:40:40 UTC 2008,
     :aws_progress   => "",
     :aws_status     => "pending",
     :aws_id         => "snap-d56783bc"}
# File lib/ec2/ec2.rb, line 1382
def try_create_snapshot(volume_id, connect_timeout = nil, read_timeout = nil)
  # For safety in the ensure block...we don't want to restore values
  # if we never read them in the first place
  orig_reiteration_time                         = nil
  orig_http_params                              = nil

  orig_reiteration_time                         = Aws::AWSErrorHandler::reiteration_time
  Aws::AWSErrorHandler::reiteration_time        = 0

  orig_http_params                              = Rightscale::HttpConnection::params()
  new_http_params                               = orig_http_params.dup
  new_http_params[:http_connection_retry_count] = 0
  new_http_params[:http_connection_open_timeout] = connect_timeout if !connect_timeout.nil?
  new_http_params[:http_connection_read_timeout] = read_timeout if !read_timeout.nil?
  Rightscale::HttpConnection::params = new_http_params

  link                               = generate_request("CreateSnapshot",
                                                        "VolumeId" => volume_id.to_s)
  request_info(link, QEc2CreateSnapshotParser.new(:logger => @logger))

rescue Exception
  on_exception
ensure
  Aws::AWSErrorHandler::reiteration_time = orig_reiteration_time if orig_reiteration_time
  Rightscale::HttpConnection::params = orig_http_params if orig_http_params
end