Class: RightAws::Ec2

Inherits:
RightAwsBase show all
Includes:
RightAwsBaseInterface
Defined in:
lib/ec2/right_ec2.rb

Overview

RightAWS::EC2 – RightScale Amazon EC2 interface

The RightAws::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   = RightAws::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, , '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 RightAws::AwsError in case of problems. Note that transient errors are automatically retried.

Defined Under Namespace

Classes: QEc2AllocateAddressParser, QEc2AttachAndDetachVolumeParser, QEc2BundleInstanceParser, QEc2ConfirmProductInstanceParser, QEc2CreateKeyPairParser, QEc2CreateSnapshotParser, QEc2CreateVolumeParser, QEc2DescribeAddressesParser, QEc2DescribeAvailabilityZonesParser, QEc2DescribeBundleTasksParser, QEc2DescribeImageAttributeParser, QEc2DescribeImagesParser, QEc2DescribeInstancesParser, QEc2DescribeKeyPairParser, QEc2DescribeRegionsParser, QEc2DescribeReservedInstancesOfferingsParser, QEc2DescribeReservedInstancesParser, QEc2DescribeSecurityGroupsParser, QEc2DescribeSnapshotsParser, QEc2DescribeVolumesParser, QEc2GetConsoleOutputParser, QEc2IpPermissionType, QEc2PurchaseReservedInstancesOfferingParser, QEc2RegisterImageParser, QEc2SecurityGroupItemType, QEc2TerminateInstancesParser, QEc2UserIdGroupPairType, RightBoolResponseParser

Constant Summary collapse

API_VERSION =

Amazon EC2 API version being used

"2009-03-01"
DEFAULT_HOST = 
"ec2.amazonaws.com"
DEFAULT_PATH = 
'/'
DEFAULT_PROTOCOL = 
'https'
DEFAULT_PORT = 
443
DEFAULT_ADDRESSING_TYPE =

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

'public'
DNS_ADDRESSING_SET = 
['public','direct']
DEFAULT_INSTANCE_TYPE =

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

'm1.small'
INSTANCE_TYPES = 
['m1.small','c1.medium','m1.large','m1.xlarge','c1.xlarge']
@@bench = 
AwsBenchmarkingBlock.new
@@api =

Current API version (sometimes we have to check it outside the GEM).

ENV['EC2_API_VERSION'] || API_VERSION

Constants included from RightAwsBaseInterface

RightAwsBaseInterface::DEFAULT_SIGNATURE_VERSION

Constants inherited from RightAwsBase

RightAwsBase::AMAZON_PROBLEMS

Instance Attribute Summary

Attributes included from RightAwsBaseInterface

#aws_access_key_id, #cache, #connection, #last_errors, #last_request, #last_request_id, #last_response, #logger, #params, #signature_version

Class Method Summary collapse

Instance Method Summary collapse

Methods included from RightAwsBaseInterface

#amazonize_list, #cache_hits?, caching, caching=, #caching?, #generate_request_impl, #get_connection, #init, #on_exception, #request_cache_or_info, #request_info_impl, #signed_service_params, #update_cache

Methods inherited from RightAwsBase

amazon_problems, amazon_problems=

Constructor Details

#initialize(aws_access_key_id = nil, aws_secret_access_key = nil, params = {}) ⇒ Ec2

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_DEFAULT_LOGGER else STDOUT

  • :signature_version: The signature version : ‘0’,‘1’ or ‘2’(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.



116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/ec2/right_ec2.rb', line 116

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,
         :default_api_version => @@api },
       aws_access_key_id    || ENV['AWS_ACCESS_KEY_ID'] , 
       aws_secret_access_key|| ENV['AWS_SECRET_ACCESS_KEY'],
       params)
end

Class Method Details

.api ⇒ Object 



96
97
98
 
# File 'lib/ec2/right_ec2.rb', line 96

def self.api 
  @@api
end

.bench_ec2 ⇒ Object 



90
91
92
 
# File 'lib/ec2/right_ec2.rb', line 90

def self.bench_ec2
  @@bench.service
end

.bench_xml ⇒ Object 



87
88
89
 
# File 'lib/ec2/right_ec2.rb', line 87

def self.bench_xml
  @@bench.xml
end

Instance Method Details

#allocate_address ⇒ Object

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'



954
955
956
957
958
959
 
# File 'lib/ec2/right_ec2.rb', line 954

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) ⇒ Object

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

ec2.associate_address('i-d630cbbf', '75.101.154.140') #=> true



966
967
968
969
970
971
972
973
 
# File 'lib/ec2/right_ec2.rb', line 966

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) ⇒ Object

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" }



1134
1135
1136
1137
1138
1139
1140
1141
1142
 
# File 'lib/ec2/right_ec2.rb', line 1134

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') ⇒ Object

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



871
872
873
874
875
876
877
878
879
880
881
 
# File 'lib/ec2/right_ec2.rb', line 871

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) ⇒ Object

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



842
843
844
845
846
847
848
849
850
 
# File 'lib/ec2/right_ec2.rb', line 842

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') ⇒ Object

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, Rightaws::Ec2#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"}]



605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
 
# File 'lib/ec2/right_ec2.rb', line 605

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 = AwsUtils.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) ⇒ Object

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"}



669
670
671
672
673
674
 
# File 'lib/ec2/right_ec2.rb', line 669

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) ⇒ Object

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"



392
393
394
395
396
 
# File 'lib/ec2/right_ec2.rb', line 392

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_key_pair(name) ⇒ Object

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-----"}



925
926
927
928
929
930
931
 
# File 'lib/ec2/right_ec2.rb', line 925

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) ⇒ Object

Create new Security Group. Returns true or an exception.

ec2.create_security_group('default-1',"Default allowing SSH, HTTP, and HTTPS ingress") #=> true



814
815
816
817
818
819
820
821
822
823
 
# File 'lib/ec2/right_ec2.rb', line 814

def create_security_group(name, description)
  # EC2 doesn't like an empty description...
  description = " " if description.blank?
  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) ⇒ Object

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"}



1201
1202
1203
1204
1205
1206
1207
 
# File 'lib/ec2/right_ec2.rb', line 1201

def create_snapshot(volume_id)
  link = generate_request("CreateSnapshot", 
                          "VolumeId" => volume_id.to_s)
  request_info(link, QEc2CreateSnapshotParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#create_volume(snapshot_id, size, zone) ⇒ Object

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}



1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
 
# File 'lib/ec2/right_ec2.rb', line 1100

def create_volume(snapshot_id, size, zone)
  hash = { "Size"              => size.to_s,
           "AvailabilityZone"  => zone.to_s }
  # Get rig of empty snapshot: e8s guys do not like it
  hash["SnapshotId"] = snapshot_id.to_s unless snapshot_id.blank?
  link = generate_request("CreateVolume", hash )
  request_info(link, QEc2CreateVolumeParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_key_pair(name) ⇒ Object

Delete a key pair. Returns true or an exception.

ec2.delete_key_pair('my_awesome_key') #=> true



937
938
939
940
941
942
943
 
# File 'lib/ec2/right_ec2.rb', line 937

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) ⇒ Object

Remove Security Group. Returns true or an exception.

ec2.delete_security_group('default-1') #=> true



829
830
831
832
833
834
835
 
# File 'lib/ec2/right_ec2.rb', line 829

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) ⇒ Object

Delete the specified snapshot.

ec2.delete_snapshot('snap-55a5403c') #=> true



1252
1253
1254
1255
1256
1257
1258
 
# File 'lib/ec2/right_ec2.rb', line 1252

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_volume(volume_id) ⇒ Object

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

ec2.delete_volume('vol-b48a6fdd') #=> true



1116
1117
1118
1119
1120
1121
1122
 
# File 'lib/ec2/right_ec2.rb', line 1116

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

#deregister_image(image_id) ⇒ Object

Deregister image at Amazon. Returns true or an exception.

ec2.deregister_image('ami-e444444d') #=> true



233
234
235
236
237
238
239
 
# File 'lib/ec2/right_ec2.rb', line 233

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 = []) ⇒ Object

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"}]



983
984
985
986
987
988
989
 
# File 'lib/ec2/right_ec2.rb', line 983

def describe_addresses(list=[])
  link = generate_request("DescribeAddresses", 
                          amazonize_list('PublicIp',list.to_a))
  request_cache_or_info :describe_addresses, link,  QEc2DescribeAddressesParser, @@bench, list.blank?
rescue Exception
  on_exception
end

#describe_availability_zones(list = []) ⇒ Object

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"}]



1032
1033
1034
1035
1036
1037
1038
 
# File 'lib/ec2/right_ec2.rb', line 1032

def describe_availability_zones(list=[])
  link = generate_request("DescribeAvailabilityZones", 
                          amazonize_list('ZoneName',list.to_a))
  request_cache_or_info :describe_availability_zones, link,  QEc2DescribeAvailabilityZonesParser, @@bench, list.blank?
rescue Exception
  on_exception
end

#describe_bundle_tasks(list = []) ⇒ Object

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"}]



649
650
651
652
653
654
 
# File 'lib/ec2/right_ec2.rb', line 649

def describe_bundle_tasks(list=[])
  link = generate_request("DescribeBundleTasks", amazonize_list('BundleId', list.to_a))
  request_info(link, QEc2DescribeBundleTasksParser.new)
rescue Exception
  on_exception
end

#describe_image_attribute(image_id, attribute = 'launchPermission') ⇒ Object

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

ec2.describe_image_attribute('ami-e444444d') #=> {:groups=>["all"], :users=>["000000000777"]}



246
247
248
249
250
251
252
253
 
# File 'lib/ec2/right_ec2.rb', line 246

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) ⇒ Object

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"}]



184
185
186
187
188
 
# File 'lib/ec2/right_ec2.rb', line 184

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) ⇒ Object

Example:

ec2.describe_images_by_executable_by('522821470517')
ec2.describe_images_by_executable_by('self')
ec2.describe_images_by_executable_by('all')



209
210
211
212
213
 
# File 'lib/ec2/right_ec2.rb', line 209

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) ⇒ Object

Example:

ec2.describe_images_by_owner('522821470517')
ec2.describe_images_by_owner('self')



196
197
198
199
200
 
# File 'lib/ec2/right_ec2.rb', line 196

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 = []) ⇒ Object

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",
     ..., {...}]



378
379
380
381
382
383
384
385
 
# File 'lib/ec2/right_ec2.rb', line 378

def describe_instances(list=[])
  link = generate_request("DescribeInstances", amazonize_list('InstanceId',list.to_a))
  request_cache_or_info(:describe_instances, link,  QEc2DescribeInstancesParser, @@bench, list.blank?) do |parser|
    get_desc_instances(parser.result)
  end
rescue Exception
  on_exception
end

#describe_key_pairs(list = []) ⇒ Object

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"},
    ..., {...} ]



911
912
913
914
915
916
 
# File 'lib/ec2/right_ec2.rb', line 911

def describe_key_pairs(list=[])
  link = generate_request("DescribeKeyPairs", amazonize_list('KeyName',list.to_a))
  request_cache_or_info :describe_key_pairs, link,  QEc2DescribeKeyPairParser, @@bench, list.blank?
rescue Exception
  on_exception
end

#describe_regions(list = []) ⇒ Object

Describe regions.

ec2.describe_regions  #=> ["eu-west-1", "us-east-1"]



1048
1049
1050
1051
1052
1053
1054
 
# File 'lib/ec2/right_ec2.rb', line 1048

def describe_regions(list=[])
  link = generate_request("DescribeRegions",
                          amazonize_list('RegionName',list.to_a))
  request_cache_or_info :describe_regions, link,  QEc2DescribeRegionsParser, @@bench, list.blank?
rescue Exception
  on_exception
end

#describe_reserved_instances(list = []) ⇒ Object

Retrieve reserved instances list. Returns a list of Reserved Instances.

ec2.describe_reserved_instances #=>

[{:aws_id=>"1ba8e2e3-1c40-434c-a741-5ff16a4c542e",
  :aws_duration=>31536000,
  :aws_instance_type=>"m1.small",
  :aws_usage_price=>0.03,
  :aws_availability_zone=>"us-east-1b",
  :aws_state=>"payment-pending",
  :aws_product_description=>"Test",
  :aws_fixed_price=>325.0,
  :aws_instance_count=>1}]



694
695
696
697
698
699
 
# File 'lib/ec2/right_ec2.rb', line 694

def describe_reserved_instances(list=[])
  link = generate_request("DescribeReservedInstances", amazonize_list('ReservedInstancesId',list.to_a))
  request_cache_or_info(:describe_reserved_instances, link,  QEc2DescribeReservedInstancesParser, @@bench, list.blank?)
rescue Exception
  on_exception
end

#describe_reserved_instances_offerings(params = {}) ⇒ Object

Retrieve reserved instances offerings. Returns a set of available offerings.

Optional params:

:aws_ids                 => String || Array
:aws_instance_type       => String
:aws_availability_zone   => String
:aws_product_description => String

ec2.describe_reserved_instances_offerings #=>
  [{:aws_instance_type=>"c1.medium",
    :aws_availability_zone=>"us-east-1c",
    :aws_duration=>94608000,
    :aws_product_description=>"Linux/UNIX",
    :aws_id=>"e5a2ff3b-f6eb-4b4e-83f8-b879d7060257",
    :aws_usage_price=>0.06,
    :aws_fixed_price=>1000.0},
    ...
   {:aws_instance_type=>"m1.xlarge",
    :aws_availability_zone=>"us-east-1a",
    :aws_duration=>31536000,
    :aws_product_description=>"Linux/UNIX",
    :aws_id=>"c48ab04c-63ab-4cd6-b8f5-978a29eb9bcc",
    :aws_usage_price=>0.24,
    :aws_fixed_price=>2600.0}]



727
728
729
730
731
732
733
734
735
736
737
 
# File 'lib/ec2/right_ec2.rb', line 727

def describe_reserved_instances_offerings(params={})
  rparams = {}
  rparams.update(amazonize_list('ReservedInstancesOfferingId', params[:aws_ids].to_a)) if params[:aws_ids]
  rparams['InstanceType']       = params[:aws_instance_type]       if params[:aws_instance_type]
  rparams['AvailabilityZone']   = params[:aws_availability_zone]   if params[:aws_availability_zone]
  rparams['ProductDescription'] = params[:aws_product_description] if params[:aws_product_description]
  link = generate_request("DescribeReservedInstancesOfferings", rparams)
  request_cache_or_info(:describe_reserved_instances_offerings, link,  QEc2DescribeReservedInstancesOfferingsParser, @@bench, params.blank?)
rescue Exception
  on_exception
end

#describe_security_groups(list = []) ⇒ Object

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 => "Default allowing SSH, HTTP, and HTTPS ingress",
    :aws_perms       =>
      [{:owner => "000000000888", :group => "default"},
       {:owner => "000000000888", :group => "default-1"},
       {:to_port => "-1",  :protocol => "icmp", :from_port => "-1",  :cidr_ips => "0.0.0.0/0"},
       {:to_port => "22",  :protocol => "tcp",  :from_port => "22",  :cidr_ips => "0.0.0.0/0"},
       {:to_port => "80",  :protocol => "tcp",  :from_port => "80",  :cidr_ips => "0.0.0.0/0"},
       {:to_port => "443", :protocol => "tcp",  :from_port => "443", :cidr_ips => "0.0.0.0/0"}]},
  ..., {...}]



771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
 
# File 'lib/ec2/right_ec2.rb', line 771

def describe_security_groups(list=[])
  link = generate_request("DescribeSecurityGroups", amazonize_list('GroupName',list.to_a))
  request_cache_or_info( :describe_security_groups, link,  QEc2DescribeSecurityGroupsParser, @@bench, list.blank?) do |parser|
    result = []     
    parser.result.each do |item|
      perms = []
      item.ipPermissions.each do |perm|
        perm.groups.each do |ngroup|
          perms << {:group => ngroup.groupName,
                    :owner => ngroup.userId}
        end
        perm.ipRanges.each do |cidr_ip|
          perms << {:from_port => perm.fromPort, 
                    :to_port   => perm.toPort, 
                    :protocol  => perm.ipProtocol,
                    :cidr_ips  => cidr_ip}
        end
      end

         # delete duplication
      perms.each_index do |i|
        (0...i).each do |j|
          if perms[i] == perms[j] then perms[i] = nil; break; end
        end
      end
      perms.compact!

      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 = []) ⇒ Object

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" },...]



1184
1185
1186
1187
1188
1189
1190
 
# File 'lib/ec2/right_ec2.rb', line 1184

def describe_snapshots(list=[])
  link = generate_request("DescribeSnapshots", 
                          amazonize_list('SnapshotId',list.to_a))
  request_cache_or_info :describe_snapshots, link,  QEc2DescribeSnapshotsParser, @@bench, list.blank?
rescue Exception
  on_exception
end

#describe_volumes(list = []) ⇒ Object

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,}, ... ]



1081
1082
1083
1084
1085
1086
1087
 
# File 'lib/ec2/right_ec2.rb', line 1081

def describe_volumes(list=[])
  link = generate_request("DescribeVolumes", 
                          amazonize_list('VolumeId',list.to_a))
  request_cache_or_info :describe_volumes, link,  QEc2DescribeVolumesParser, @@bench, list.blank?
rescue Exception
  on_exception
end

#detach_volume(volume_id, instance_id = nil, device = nil, force = nil) ⇒ Object

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"}



1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
 
# File 'lib/ec2/right_ec2.rb', line 1153

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 instance_id.blank?
  hash["Device"]     = device.to_s      unless device.blank?
  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) ⇒ Object

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



996
997
998
999
1000
1001
1002
 
# File 'lib/ec2/right_ec2.rb', line 996

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

#ec2_describe_images(params = {}, image_type = nil, cache_for = nil) ⇒ Object

params: 

{ 'ImageId'      => ['id1', ..., 'idN'],
  'Owner'        => ['self', ..., 'userN'],
  'ExecutableBy' => ['self', 'all', ..., 'userN']
}



147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/ec2/right_ec2.rb', line 147

def ec2_describe_images(params={}, image_type=nil, cache_for=nil) #:nodoc:
  request_hash = {}
  params.each do |list_by, list|
    request_hash.merge! amazonize_list(list_by, list.to_a)
  end
  request_hash['ImageType'] = image_type if image_type
  link = generate_request("DescribeImages", request_hash)
  request_cache_or_info cache_for, link,  QEc2DescribeImagesParser, @@bench, cache_for
rescue Exception
  on_exception
end

#generate_request(action, params = {}) ⇒ Object

:nodoc:



128
129
130
 
# File 'lib/ec2/right_ec2.rb', line 128

def generate_request(action, params={}) #:nodoc:
  generate_request_impl(:get, action, params )
end

#get_console_output(instance_id) ⇒ Object

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 ([email protected]) (gcc version 4.0.1 20050727 ..."



538
539
540
541
542
543
 
# File 'lib/ec2/right_ec2.rb', line 538

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_desc_instances(instances) ⇒ Object 

Instances



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/ec2/right_ec2.rb', line 338

def get_desc_instances(instances)  # :nodoc:
  result = []
  instances.each do |reservation|
    reservation[:instances_set].each do |instance|
      # Parse and remove timestamp from the reason string. The timestamp is of
      # the request, not when EC2 took action, thus confusing & useless...
      instance[:aws_reason]         = instance[:aws_reason].sub(/\(\d[^)]*GMT\) */, '')
      instance[:aws_owner]          = reservation[:aws_owner]
      instance[:aws_reservation_id] = reservation[:aws_reservation_id]
      instance[:aws_groups]         = reservation[:aws_groups]
      result << instance
    end
  end
  result
rescue Exception
  on_exception
end

#get_initial_password(instance_id, private_key) ⇒ Object

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"



578
579
580
581
582
583
584
585
586
587
588
 
# File 'lib/ec2/right_ec2.rb', line 578

def get_initial_password(instance_id, private_key)
  console_output = get_console_output(instance_id)
  crypted_password = console_output[:aws_output][%r{<Password>(.+)</Password>}m] && $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

#launch_instances(image_id, lparams = {}) ⇒ Object

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

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"
   }]



478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
 
# File 'lib/ec2/right_ec2.rb', line 478

def launch_instances(image_id, lparams={}) 
  @logger.info("Launching instance of image #{image_id} for #{@aws_access_key_id}, " + 
               "key: #{lparams[:key_name]}, groups: #{(lparams[:group_ids]).to_a.join(',')}")
  # careful: keyName and securityGroups may be nil
  params = amazonize_list('SecurityGroup', lparams[:group_ids].to_a)
  params.update( {'ImageId'        => image_id,
                  'MinCount'       => (lparams[:min_count] || 1).to_s, 
                  'MaxCount'       => (lparams[:max_count] || 1).to_s, 
                  'AddressingType' => lparams[:addressing_type] || DEFAULT_ADDRESSING_TYPE, 
                  'InstanceType'   => lparams[:instance_type]   || DEFAULT_INSTANCE_TYPE })
  # optional params
  params['KeyName']                    = lparams[:key_name]              unless lparams[:key_name].blank? 
  params['KernelId']                   = lparams[:kernel_id]             unless lparams[:kernel_id].blank? 
  params['RamdiskId']                  = lparams[:ramdisk_id]            unless lparams[:ramdisk_id].blank? 
  params['Placement.AvailabilityZone'] = lparams[:availability_zone]     unless lparams[:availability_zone].blank? 
  params['BlockDeviceMappings']        = lparams[:block_device_mappings] unless lparams[:block_device_mappings].blank?
  unless lparams[:user_data].blank? 
    lparams[: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(lparams[:user_data]).delete("\n") unless lparams[:user_data].blank?
  end
  link = generate_request("RunInstances", params)
    #debugger
  instances = request_info(link, QEc2DescribeInstancesParser.new(:logger => @logger))
  get_desc_instances(instances)
rescue Exception
  on_exception
end

#modify_image_attribute(image_id, attribute, operation_type = nil, vars = {}) ⇒ Object

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.

attribute      : currently, only 'launchPermission' is supported.
operation_type : currently, only 'add' & 'remove' are supported.
vars: 
  :user_group  : currently, only 'all' is supported.  
  :user_id
  :product_code



279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/ec2/right_ec2.rb', line 279

def modify_image_attribute(image_id, attribute, operation_type = nil, vars = {})
  params =  {'ImageId'   => image_id,
             'Attribute' => attribute}
  params['OperationType'] = operation_type if operation_type
  params.update(amazonize_list('UserId',      vars[:user_id].to_a))    if vars[:user_id]
  params.update(amazonize_list('UserGroup',   vars[:user_group].to_a)) if vars[:user_group]
  params.update(amazonize_list('ProductCode', vars[:product_code]))    if vars[:product_code]
  link = generate_request("ModifyImageAttribute", params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#modify_image_launch_perm_add_groups(image_id, user_group = ['all']) ⇒ Object

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



314
315
316
 
# File 'lib/ec2/right_ec2.rb', line 314

def modify_image_launch_perm_add_groups(image_id, user_group=['all'])
  modify_image_attribute(image_id, 'launchPermission', 'add', :user_group => user_group.to_a)
end

#modify_image_launch_perm_add_users(image_id, user_id = []) ⇒ Object

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



297
298
299
 
# File 'lib/ec2/right_ec2.rb', line 297

def modify_image_launch_perm_add_users(image_id, user_id=[])
  modify_image_attribute(image_id, 'launchPermission', 'add', :user_id => user_id.to_a)
end

#modify_image_launch_perm_remove_groups(image_id, user_group = ['all']) ⇒ Object

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



322
323
324
 
# File 'lib/ec2/right_ec2.rb', line 322

def modify_image_launch_perm_remove_groups(image_id, user_group=['all'])
  modify_image_attribute(image_id, 'launchPermission', 'remove', :user_group => user_group.to_a)
end

#modify_image_launch_perm_remove_users(image_id, user_id = []) ⇒ Object

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



305
306
307
 
# File 'lib/ec2/right_ec2.rb', line 305

def modify_image_launch_perm_remove_users(image_id, user_id=[])
  modify_image_attribute(image_id, 'launchPermission', 'remove', :user_id => user_id.to_a)
end

#modify_image_product_code(image_id, product_code = []) ⇒ Object

Add product code to image

ec2.modify_image_product_code('ami-e444444d','0ABCDEF') #=> true



330
331
332
 
# File 'lib/ec2/right_ec2.rb', line 330

def modify_image_product_code(image_id, product_code=[])
  modify_image_attribute(image_id, 'productCodes', nil, :product_code => product_code.to_a)
end

#purchase_reserved_instances_offering(reserved_instances_offering_id, instance_count = 1) ⇒ Object

Purchase a Reserved Instance. Returns ReservedInstancesId value.

ec2.purchase_reserved_instances_offering('e5a2ff3b-f6eb-4b4e-83f8-b879d7060257', 3) # => '4b2293b4-5813-4cc8-9ce3-1957fc1dcfc8'



744
745
746
747
748
749
750
 
# File 'lib/ec2/right_ec2.rb', line 744

def purchase_reserved_instances_offering(reserved_instances_offering_id, instance_count=1)
  link = generate_request("PurchaseReservedInstancesOffering", { 'ReservedInstancesOfferingId' => reserved_instances_offering_id,
                                                                 'InstanceCount'               => instance_count  })
  request_info(link, QEc2PurchaseReservedInstancesOfferingParser.new)
rescue Exception
  on_exception
end

#reboot_instances(list) ⇒ Object

Reboot an EC2 instance. Returns true or an exception.

ec2.reboot_instances(['i-f222222d','i-f222222e']) #=> true



549
550
551
552
553
554
 
# File 'lib/ec2/right_ec2.rb', line 549

def reboot_instances(list)
  link = generate_request("RebootInstances", amazonize_list('InstanceId', list.to_a))
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#register_image(image_location) ⇒ Object

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

ec2.register_image('bucket/key/manifest') #=> 'ami-e444444d'



221
222
223
224
225
226
227
 
# File 'lib/ec2/right_ec2.rb', line 221

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) ⇒ Object

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

ec2.release_address('75.101.154.140') #=> true



1009
1010
1011
1012
1013
1014
1015
 
# File 'lib/ec2/right_ec2.rb', line 1009

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

#request_info(request, parser) ⇒ Object

Sends request to Amazon and parses the response Raises AwsError if any banana happened



134
135
136
 
# File 'lib/ec2/right_ec2.rb', line 134

def request_info(request, parser)  #:nodoc:
  request_info_impl(:ec2_connection, @@bench, request, parser)
end

#reset_image_attribute(image_id, attribute = 'launchPermission') ⇒ Object

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

ec2.reset_image_attribute('ami-e444444d') #=> true



259
260
261
262
263
264
265
266
 
# File 'lib/ec2/right_ec2.rb', line 259

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') ⇒ Object

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



887
888
889
890
891
892
893
894
895
896
897
 
# File 'lib/ec2/right_ec2.rb', line 887

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) ⇒ Object

Revoke named ingress for security group.

ec2.revoke_security_group_named_ingress('my_awesome_group', aws_user_id, 'another_group_name') #=> true



856
857
858
859
860
861
862
863
864
 
# File 'lib/ec2/right_ec2.rb', line 856

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) ⇒ Object

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"
   }]



420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
 
# File 'lib/ec2/right_ec2.rb', line 420

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

#terminate_instances(list = []) ⇒ Object

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}]



524
525
526
527
528
529
 
# File 'lib/ec2/right_ec2.rb', line 524

def terminate_instances(list=[])
  link = generate_request("TerminateInstances", amazonize_list('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) ⇒ Object

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"}



1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
 
# File 'lib/ec2/right_ec2.rb', line 1221

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 = RightAws::AWSErrorHandler::reiteration_time
  RightAws::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
  RightAws::AWSErrorHandler::reiteration_time = orig_reiteration_time if orig_reiteration_time
  Rightscale::HttpConnection::params = orig_http_params if orig_http_params
end