Class: RightAws::Ec2

Inherits:
RightAwsBase show all
Includes:
RightAwsBaseInterface
Defined in:
lib/ec2/right_ec2.rb,
lib/ec2/right_ec2_ebs.rb,
lib/ec2/right_ec2_vpc.rb,
lib/ec2/right_ec2_images.rb,
lib/ec2/right_ec2_instances.rb,
lib/ec2/right_ec2_monitoring.rb,
lib/ec2/right_ec2_spot_instances.rb,
lib/ec2/right_ec2_security_groups.rb,
lib/ec2/right_ec2_reserved_instances.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, QEc2AttachVpnGatewayParser, QEc2BundleInstanceParser, QEc2CancelSpotInstanceParser, QEc2ConfirmProductInstanceParser, QEc2CreateKeyPairParser, QEc2CreateVolumeParser, QEc2DescribeAddressesParser, QEc2DescribeAvailabilityZonesParser, QEc2DescribeBundleTasksParser, QEc2DescribeCustomerGatewaysParser, QEc2DescribeDhcpOptionsParser, QEc2DescribeImageAttributeParser, QEc2DescribeImagesParser, QEc2DescribeInstanceAttributeParser, QEc2DescribeInstancesParser, QEc2DescribeKeyPairParser, QEc2DescribeRegionsParser, QEc2DescribeReservedInstancesOfferingsParser, QEc2DescribeReservedInstancesParser, QEc2DescribeSecurityGroupsParser, QEc2DescribeSnapshotAttributeParser, QEc2DescribeSnapshotsParser, QEc2DescribeSpotDatafeedSubscriptionParser, QEc2DescribeSpotInstanceParser, QEc2DescribeSpotPriceHistoryParser, QEc2DescribeSubnetsParser, QEc2DescribeVolumesParser, QEc2DescribeVpcsParser, QEc2DescribeVpnConnectionsParser, QEc2DescribeVpnGatewaysParser, QEc2GetConsoleOutputParser, QEc2GetPasswordDataParser, QEc2MonitorInstancesParser, QEc2PurchaseReservedInstancesOfferingParser, QEc2RegisterImageParser, QEc2TerminateInstancesParser

Constant Summary collapse

API_VERSION =

Amazon EC2 API version being used

"2010-08-31"
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', 'm2.xlarge', 'm2.2xlarge', 'm2.4xlarge']
INSTANCE_ATTRIBUTE_MAPPING = 
{
  "instance_type"                        => "instanceType",
  "kernel"                               => "kernel",
  "ramdisk"                              => "ramdisk",
  "user_data"                            => "userData",
  "disable_api_termination"              => "disableApiTermination",
  "instance_initiated_shutdown_behavior" => "instanceInitiatedShutdownBehavior",
  "root_device_name"                     => "rootDeviceName",
  "block_device_mapping"                 => "blockDeviceMapping"
}
@@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::BLOCK_DEVICE_KEY_MAPPING, RightAwsBaseInterface::DEFAULT_SIGNATURE_VERSION

Constants inherited from RightAwsBase

RightAwsBase::AMAZON_PROBLEMS

Instance Attribute Summary

Attributes included from RightAwsBaseInterface

#aws_access_key_id, #aws_secret_access_key, #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_block_device_mappings, #amazonize_list, #cache_hits?, caching, caching=, #caching?, #destroy_connection, #generate_request_impl, #get_connection, #get_connections_storage, #get_server_url, #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
127
128
129
130
 
# 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)
  # Eucalyptus supports some yummy features but Amazon does not
  if @params[:eucalyptus]
    @params[:port_based_group_ingress] = true unless @params.has_key?(:port_based_group_ingress)
  end
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'



198
199
200
201
202
203
 
# File 'lib/ec2/right_ec2.rb', line 198

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



210
211
212
213
214
215
216
217
 
# File 'lib/ec2/right_ec2.rb', line 210

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

#associate_dhcp_options(dhcp_options_id, vpc_id) ⇒ Object

Associate DHCP options

ec2.associate_dhcp_options(“dopt-cb0de3a2”, “vpc-890ce2e0” ) #=> true ec2.describe_vpcs #=>

[{:vpc_id=>"vpc-890ce2e0",
  :dhcp_options_id=>"dopt-cb0de3a2",
  :cidr_block=>"10.0.0.0/23",
  :state=>"available"}]



196
197
198
199
200
201
202
 
# File 'lib/ec2/right_ec2_vpc.rb', line 196

def associate_dhcp_options(dhcp_options_id, vpc_id)
  link = generate_request("AssociateDhcpOptions", 'DhcpOptionsId' => dhcp_options_id,
                                                  'VpcId'         => vpc_id)
  request_info(link, RightHttp2xxParser.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" }



105
106
107
108
109
110
111
112
113
 
# File 'lib/ec2/right_ec2_ebs.rb', line 105

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

#attach_vpn_gateway(vpn_gateway_id, vpc_id) ⇒ Object

Attach VPN gateway.

ec2.attach_vpn_gateway('vgw-dfa144b6','vpc-890ce2e0') #=>
   {:vpc_id=>"vpc-890ce2e0", :state=>"attaching"}



316
317
318
319
320
321
322
 
# File 'lib/ec2/right_ec2_vpc.rb', line 316

def attach_vpn_gateway(vpn_gateway_id, vpc_id)
  link = generate_request("AttachVpnGateway", 'VpnGatewayId' => vpn_gateway_id,
                                              'VpcId'        => vpc_id )
  request_info(link, QEc2AttachVpnGatewayParser.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



223
224
225
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 223

def authorize_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0')
  edit_security_group( :authorize, name, :from_port => from_port, :to_port => to_port, :protocol => protocol, :cidr_ip => cidr_ip )
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



206
207
208
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 206

def authorize_security_group_named_ingress(name, owner, group)
  edit_security_group( :authorize, name, :source_group_owner => owner, :source_group => group)
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"}]



456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'lib/ec2/right_ec2_instances.rb', line 456

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' => AwsUtils::utc_iso8601(s3_expires),
             '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"}



521
522
523
524
525
526
 
# File 'lib/ec2/right_ec2_instances.rb', line 521

def cancel_bundle_task(bundle_id)
  link = generate_request("CancelBundleTask", { 'BundleId' => bundle_id })
  request_info(link, QEc2BundleInstanceParser.new)
rescue Exception
  on_exception
end

#cancel_spot_instance_requests(*spot_instance_request_ids) ⇒ Object

Cancel one or more Spot Instance requests.

ec2.cancel_spot_instance_requests('sir-60662c03',"sir-d3c96e04", "sir-4fa8d804","sir-6992ce04") #=>
  [{:state=>"cancelled", :spot_instance_request_id=>"sir-60662c03"},
   {:state=>"cancelled", :spot_instance_request_id=>"sir-6992ce04"},
   {:state=>"cancelled", :spot_instance_request_id=>"sir-4fa8d804"},
   {:state=>"cancelled", :spot_instance_request_id=>"sir-d3c96e04"}]



240
241
242
243
 
# File 'lib/ec2/right_ec2_spot_instances.rb', line 240

def cancel_spot_instance_requests(*spot_instance_request_ids)
  link = generate_request("CancelSpotInstanceRequests", amazonize_list('SpotInstanceRequestId', spot_instance_request_ids.flatten))
  request_info(link, QEc2CancelSpotInstanceParser.new(:logger => @logger))
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"



102
103
104
105
106
 
# File 'lib/ec2/right_ec2_instances.rb', line 102

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_customer_gateway(type, ip_address, bgp_asn) ⇒ Object

Create customer gateway.

ec2.create_customer_gateway('ipsec.1', '12.1.2.3', 65534) #=>
  {:type=>"ipsec.1",
   :bgp_asn=>"65534",
   :ip_address=>"12.1.2.3",
   :state=>"pending",
   :customer_gateway_id=>"cgw-d5a643bc"}



250
251
252
253
254
255
256
257
 
# File 'lib/ec2/right_ec2_vpc.rb', line 250

def create_customer_gateway(type, ip_address, bgp_asn)
  link = generate_request("CreateCustomerGateway", 'Type'      => type,
                                                   'IpAddress' => ip_address,
                                                   'BgpAsn'    => bgp_asn )
  request_info(link, QEc2DescribeCustomerGatewaysParser.new(:logger => @logger)).first
rescue Exception
  on_exception
end

#create_dhcp_options(dhcp_configuration) ⇒ Object

Create DHCP options.

ec2.create_dhcp_options('domain-name' => 'my.awesomesite.ru',
                        'netbios-node-type' => 1) #=>
  {:dhcp_options_id=>"dopt-cb0de3a2",
   :dhcp_configuration_set=>
    {"netbios-node-type"=>["1"], "domain-name"=>["my.awesomesite.ru"]}}



178
179
180
181
182
183
184
185
 
# File 'lib/ec2/right_ec2_vpc.rb', line 178

def create_dhcp_options(dhcp_configuration)
  dhcp_configuration.each{ |key, values| dhcp_configuration[key] = Array(values) }
  request_hash = amazonize_list(['DhcpConfiguration.?.Key','DhcpConfiguration.?.Value.?'], dhcp_configuration)
  link = generate_request("CreateDhcpOptions", request_hash)
  request_info(link, QEc2DescribeDhcpOptionsParser.new(:logger => @logger)).first
rescue Exception
  on_exception
end

#create_image(instance_aws_id, options = {}) ⇒ Object

Create a new image. Options: :name, :description, :no_reboot(bool)

ec2.create_image(instance, :description => 'KD: test#1',
                           :no_reboot => true,
                           :name => 'kd-1' ) #=> "ami-84a1f792"



270
271
272
273
274
275
276
277
 
# File 'lib/ec2/right_ec2_images.rb', line 270

def create_image(instance_aws_id, options={})
  params = { 'InstanceId' => instance_aws_id }
  params['Name']        = options[:name]            unless options[:name].blank?
  params['Description'] = options[:description]     unless options[:description].blank?
  params['NoReboot']    = options[:no_reboot].to_s  unless options[:no_reboot].nil?
  link = generate_request("CreateImage", params)
  request_info(link, QEc2RegisterImageParser.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-----"}



169
170
171
172
173
174
175
 
# File 'lib/ec2/right_ec2.rb', line 169

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

Create new Security Group. Returns true or an exception.

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



130
131
132
133
134
135
136
137
138
139
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 130

def create_security_group(name, description=nil)
  # 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, description = '') ⇒ Object

Create a snapshot of specified volume.

ec2.create_snapshot('vol-898a6fe0', 'KD: WooHoo!!') #=>
  {:aws_volume_id=>"vol-e429db8d",
   :aws_started_at=>"2009-10-01T09:23:38.000Z",
   :aws_description=>"KD: WooHoo!!",
   :aws_owner=>"648770000000",
   :aws_progress=>"",
   :aws_status=>"pending",
   :aws_volume_size=>1,
   :aws_id=>"snap-3df54854"}



181
182
183
184
185
186
187
188
 
# File 'lib/ec2/right_ec2_ebs.rb', line 181

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

#create_spot_datafeed_subscription(bucket, prefix = nil) ⇒ Object

Create the data feed for Spot Instances (Enables to view Spot Instance usage logs)

ec2.create_spot_datafeed_subscription('bucket-for-konstantin-eu', 'splogs/') #=>
  { :owner_id=>"826693181925",
    :bucket=>"bucket-for-konstantin-eu",
    :prefix=>"splogs/",
    :state=>"Active"}



254
255
256
257
258
259
 
# File 'lib/ec2/right_ec2_spot_instances.rb', line 254

def create_spot_datafeed_subscription(bucket, prefix=nil)
  request_hash = { 'Bucket' => bucket }
  request_hash['Prefix'] = prefix unless prefix.blank?
  link = generate_request("CreateSpotDatafeedSubscription", request_hash)
  request_info(link, QEc2DescribeSpotDatafeedSubscriptionParser.new(:logger => @logger))
end

#create_subnet(vpc_id, cidr_block, availability_zone = nil) ⇒ Object

Create Subnet.

ec2.create_subnet("vpc-890ce2e0",'10.0.1.0/24') #=>
  {:available_ip_address_count=>"251",
   :vpc_id=>"vpc-890ce2e0",
   :availability_zone=>"us-east-1a",
   :subnet_id=>"subnet-770de31e",
   :cidr_block=>"10.0.1.0/24",
   :state=>"pending"}



128
129
130
131
132
133
134
135
136
 
# File 'lib/ec2/right_ec2_vpc.rb', line 128

def create_subnet(vpc_id, cidr_block, availability_zone = nil)
  request_hash = { 'VpcId'     => vpc_id,
                   'CidrBlock' => cidr_block }
  request_hash['AvailabilityZone'] = availability_zone unless availability_zone.blank?
  link = generate_request("CreateSubnet", request_hash)
  request_info(link, QEc2DescribeSubnetsParser.new(:logger => @logger)).first
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 => "2008-06-24T18:13:32.000Z",
     :aws_size       => 94}



71
72
73
74
75
76
77
78
79
80
 
# File 'lib/ec2/right_ec2_ebs.rb', line 71

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

#create_vpc(cidr_block) ⇒ Object

Create VPC.

ec2.create_vpc('10.0.0.0/23') #=>
  {:vpc_id=>"vpc-890ce2e0",
   :dhcp_options_id=>"default",
   :cidr_block=>"10.0.0.0/23",
   :state=>"pending"}



74
75
76
77
78
79
 
# File 'lib/ec2/right_ec2_vpc.rb', line 74

def create_vpc(cidr_block)
  link = generate_request("CreateVpc",'CidrBlock' => cidr_block )
  request_info(link, QEc2DescribeVpcsParser.new(:logger => @logger)).first
rescue Exception
  on_exception
end

#create_vpn_connection(type, customer_gateway_id, vpn_gateway_id) ⇒ Object

Create VPN connection.

ec2.create_vpn_connection('ipsec.1', 'cgw-81a643e8' ,'vgw-dfa144b6')
  {:customer_gateway_id=>"cgw-81a643e8",
   :vpn_connection_id=>"vpn-a9a643c0",
   :customer_gateway_configuration=>
    "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<vpn_connection id=\"vpn-a9a643c0\">\n...</vpn_connection>\n",
   :state=>"pending",
   :vpn_gateway_id=>"vgw-dfa144b6"}



384
385
386
387
388
389
390
391
 
# File 'lib/ec2/right_ec2_vpc.rb', line 384

def create_vpn_connection(type, customer_gateway_id, vpn_gateway_id)
  link = generate_request("CreateVpnConnection", 'Type'              => type,
                                                 'CustomerGatewayId' => customer_gateway_id,
                                                 'VpnGatewayId'      => vpn_gateway_id )
  request_info(link, QEc2DescribeVpnConnectionsParser.new(:logger => @logger)).first
rescue Exception
  on_exception
end

#create_vpn_gateway(type, availability_zone = nil) ⇒ Object

Create VPN gateway.

ec2.create_vpn_gateway('ipsec.1') #=>
  {:type=>"ipsec.1",
   :availability_zone=>"us-east-1a",
   :attachments=>[nil],
   :vpn_gateway_id=>"vgw-dfa144b6"}



302
303
304
305
306
307
308
309
 
# File 'lib/ec2/right_ec2_vpc.rb', line 302

def create_vpn_gateway(type, availability_zone=nil)
  request_hash = { 'Type' => type }
  request_hash['AvailabilityZone'] = availability_zone unless availability_zone.blank?
  link = generate_request("CreateVpnGateway", request_hash )
  request_info(link, QEc2DescribeVpnGatewaysParser.new(:logger => @logger)).first
rescue Exception
  on_exception
end

#delete_customer_gateway(customer_gateway_id) ⇒ Object

Delete customer gateway.

ec2.delete_customer_gateway("cgw-d5a643bc") #=> true



263
264
265
266
267
268
 
# File 'lib/ec2/right_ec2_vpc.rb', line 263

def delete_customer_gateway(customer_gateway_id)
  link = generate_request("DeleteCustomerGateway", 'CustomerGatewayId' => customer_gateway_id )
  request_info(link, RightHttp2xxParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_dhcp_options(dhcp_options_id) ⇒ Object

Delete DHCP Options.

ec2.delete_dhcp_options("dopt-cb0de3a2") #=> true



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

def delete_dhcp_options(dhcp_options_id)
  link = generate_request("DeleteDhcpOptions", 'DhcpOptionsId' => dhcp_options_id )
  request_info(link, RightHttp2xxParser.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



181
182
183
184
185
186
187
 
# File 'lib/ec2/right_ec2.rb', line 181

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



145
146
147
148
149
150
151
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 145

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



321
322
323
324
325
326
327
 
# File 'lib/ec2/right_ec2_ebs.rb', line 321

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

Delete the data feed for Spot Instances.

ec2.delete_spot_datafeed_subscription #=> true



278
279
280
281
 
# File 'lib/ec2/right_ec2_spot_instances.rb', line 278

def delete_spot_datafeed_subscription()
  link = generate_request("DeleteSpotDatafeedSubscription")
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
end

#delete_subnet(subnet_id) ⇒ Object

Delete Subnet.

ec2.delete_subnet("subnet-770de31e") #=> true



142
143
144
145
146
147
 
# File 'lib/ec2/right_ec2_vpc.rb', line 142

def delete_subnet(subnet_id)
  link = generate_request("DeleteSubnet", 'SubnetId' => subnet_id )
  request_info(link, RightHttp2xxParser.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



87
88
89
90
91
92
93
 
# File 'lib/ec2/right_ec2_ebs.rb', line 87

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

Delete VPC.

ec2.delete_vpc("vpc-890ce2e0") #=> true



85
86
87
88
89
90
 
# File 'lib/ec2/right_ec2_vpc.rb', line 85

def delete_vpc(vpc_id)
  link = generate_request("DeleteVpc", 'VpcId' => vpc_id )
  request_info(link, RightHttp2xxParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_vpn_connection(vpn_connection_id) ⇒ Object

Delete VPN connection.

ec2.delete_vpn_connection("vpn-a9a643c0") #=> true



397
398
399
400
401
402
 
# File 'lib/ec2/right_ec2_vpc.rb', line 397

def delete_vpn_connection(vpn_connection_id)
  link = generate_request("DeleteVpnConnection", 'VpnConnectionId' => vpn_connection_id )
  request_info(link, RightHttp2xxParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_vpn_gateway(vpn_gateway_id) ⇒ Object

Delete vpn gateway.

ec2.delete_vpn_gateway("vgw-dfa144b6") #=> true



340
341
342
343
344
345
 
# File 'lib/ec2/right_ec2_vpc.rb', line 340

def delete_vpn_gateway(vpn_gateway_id)
  link = generate_request("DeleteVpnGateway", 'VpnGatewayId' => vpn_gateway_id )
  request_info(link, RightHttp2xxParser.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



163
164
165
166
167
168
169
 
# File 'lib/ec2/right_ec2_images.rb', line 163

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(*addresses) ⇒ 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"}]



227
228
229
230
231
232
233
 
# File 'lib/ec2/right_ec2.rb', line 227

def describe_addresses(*addresses)
  addresses = addresses.flatten
  link = generate_request("DescribeAddresses", amazonize_list('PublicIp', addresses))
  request_cache_or_info :describe_addresses, link,  QEc2DescribeAddressesParser, @@bench, addresses.blank?
rescue Exception
  on_exception
end

#describe_availability_zones(*availability_zones) ⇒ 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"}]



276
277
278
279
280
281
282
 
# File 'lib/ec2/right_ec2.rb', line 276

def describe_availability_zones(*availability_zones)
  availability_zones = availability_zones.flatten
  link = generate_request("DescribeAvailabilityZones", amazonize_list('ZoneName', availability_zones))
  request_cache_or_info :describe_availability_zones, link,  QEc2DescribeAvailabilityZonesParser, @@bench, availability_zones.blank?
rescue Exception
  on_exception
end

#describe_bundle_tasks(*tasks) ⇒ 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"}]



500
501
502
503
504
505
506
 
# File 'lib/ec2/right_ec2_instances.rb', line 500

def describe_bundle_tasks(*tasks)
  tasks = tasks.flatten
  link = generate_request("DescribeBundleTasks", amazonize_list('BundleId', tasks))
  request_info(link, QEc2DescribeBundleTasksParser.new)
rescue Exception
  on_exception
end

#describe_customer_gateways(*list_and_filters) ⇒ Object

Describe customer gateways.

ec2.describe_customer_gateways

  [{:type=>"ipsec.1",
    :ip_address=>"12.1.2.3",
    :bgp_asn=>"65534",
    :state=>"available",
    :customer_gateway_id=>"cgw-d5a643bc"}]



229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/ec2/right_ec2_vpc.rb', line 229

def describe_customer_gateways(*list_and_filters)
  list, filters = vpc__split_list_and_filters(list_and_filters)
  cache_for = (list.empty? && filters.empty?) ? :describe_customer_gateways : nil
  request_hash = {}
  request_hash.merge!(amazonize_list('CustomerGatewayId', list))
  request_hash.merge!(amazonize_list(['Filter.?.Key','Filter.?.Value.?'], filters))
  link = generate_request("DescribeCustomerGateways", request_hash)
  request_cache_or_info cache_for, link,  QEc2DescribeCustomerGatewaysParser, @@bench, cache_for
rescue Exception
  on_exception
end

#describe_dhcp_options(*list) ⇒ Object

Describe DHCP options.

ec2.describe_dhcp_options #=>

[{:dhcp_options_id=>"dopt-cb0de3a2",
:dhcp_configuration_set=>
 {"netbios-node-type"=>["1"], "domain-name"=>["my.awesomesite.ru"]}}]



160
161
162
163
164
165
166
167
168
 
# File 'lib/ec2/right_ec2_vpc.rb', line 160

def describe_dhcp_options(*list)
  list = list.flatten
  cache_for = list.empty? ? :describe_dhcp_options : nil
  request_hash = amazonize_list('DhcpOptionsId', list)
  link = generate_request("DescribeDhcpOptions", request_hash)
  request_cache_or_info cache_for, link,  QEc2DescribeDhcpOptionsParser, @@bench, cache_for
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"]}



175
176
177
178
179
180
181
182
 
# File 'lib/ec2/right_ec2_images.rb', line 175

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(images = [], 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_id=>"ami-b0a1f7a6",
    :aws_image_type=>"machine",
    :root_device_name=>"/dev/sda1",
    :image_class=>"static",
    :aws_owner=>"826693181925",
    :aws_location=>"bucket_for_k_dzreyev/image_bundles/kd__CentOS_1_10_2009_10_21_13_30_43_MSD/image.manifest.xml",
    :aws_state=>"available",
    :aws_is_public=>false,
    :aws_architecture=>"i386"},
   {:description=>"EBS backed Fedora core 8 i386",
    :aws_architecture=>"i386",
    :aws_id=>"ami-c2a3f5d4",
    :aws_image_type=>"machine",
    :root_device_name=>"/dev/sda1",
    :image_class=>"elastic",
    :aws_owner=>"937766719418",
    :aws_location=>"937766719418/EBS backed FC8 i386",
    :aws_state=>"available",
    :block_device_mappings=>
     [{:ebs_snapshot_id=>"snap-829a20eb",
       :ebs_delete_on_termination=>true,
       :device_name=>"/dev/sda1"}],
    :name=>"EBS backed FC8 i386",
    :aws_is_public=>true}, ... ]

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

ec2.describe_images(['ami-5aa1f74c'])



83
84
85
86
87
 
# File 'lib/ec2/right_ec2_images.rb', line 83

def describe_images(images=[], image_type=nil)
  images = Array(images)
  cache_for = images.empty? && !image_type ? :describe_images : nil
  ec2_describe_images({ 'ImageId' => images }, image_type, cache_for)
end

#describe_images_by_executable_by(executable_by = ['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')



106
107
108
109
110
 
# File 'lib/ec2/right_ec2_images.rb', line 106

def describe_images_by_executable_by(executable_by=['self'], image_type=nil)
  executable_by = Array(executable_by)
  cache_for = (executable_by==['self']) && (!image_type ? :describe_images_by_executable_by : nil)
  ec2_describe_images({ 'ExecutableBy' => executable_by }, image_type, cache_for)
end

#describe_images_by_owner(owners = ['self'], image_type = nil) ⇒ Object

Example:

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



94
95
96
97
98
 
# File 'lib/ec2/right_ec2_images.rb', line 94

def describe_images_by_owner(owners=['self'], image_type=nil)
  owners = Array(owners)
  cache_for = (owners == ['self']) && (!image_type ? :describe_images_by_owner : nil)
  ec2_describe_images({ 'Owner' => owners }, image_type, cache_for)
end

#describe_instance_attribute(instance_id, attribute) ⇒ Object

Describe instance attribute. Attributes: :instance_type, :kernel, :ramdisk, :user_data, :disable_api_termination, :instance_initiated_shutdown_behavior, :root_device_name, :block_device_mapping

ec2.describe_instance_attribute(instance, "BlockDeviceMapping") #=>
   [{:ebs_delete_on_termination=>true,
     :ebs_volume_id=>"vol-683dc401",
     :device_name=>"/dev/sda1"}]

ec2.describe_instance_attribute(instance, "InstanceType") #=> "m1.small"

ec2.describe_instance_attribute(instance, "InstanceInitiatedShutdownBehavior") #=> "stop"



334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/ec2/right_ec2_instances.rb', line 334

def describe_instance_attribute(instance_id, attribute)
  attribute = INSTANCE_ATTRIBUTE_MAPPING[attribute.to_s] || attribute.to_s
  link = generate_request('DescribeInstanceAttribute',
                          'InstanceId' => instance_id,
                          'Attribute'  => attribute)
  value = request_info(link, QEc2DescribeInstanceAttributeParser.new(:logger => @logger))
  case attribute
  when "userData"
    Base64.decode64(value)
  else
    value
  end
rescue Exception
  on_exception
end

#describe_instances(*instances) ⇒ Object

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

ec2.describe_instances #=>
  [{:private_ip_address=>"10.240.7.99",
    :aws_image_id=>"ami-c2a3f5d4",
    :ip_address=>"174.129.134.109",
    :dns_name=>"ec2-174-129-134-109.compute-1.amazonaws.com",
    :aws_instance_type=>"m1.small",
    :aws_owner=>"826693181925",
    :root_device_name=>"/dev/sda1",
    :instance_class=>"elastic",
    :aws_state=>"running",
    :private_dns_name=>"domU-12-31-39-04-00-95.compute-1.internal",
    :aws_reason=>"",
    :aws_launch_time=>"2009-11-18T14:03:25.000Z",
    :aws_reservation_id=>"r-54d38542",
    :aws_state_code=>16,
    :ami_launch_index=>"0",
    :aws_availability_zone=>"us-east-1a",
    :aws_groups=>["default"],
    :monitoring_state=>"disabled",
    :aws_product_codes=>[],
    :ssh_key_name=>"",
    :block_device_mappings=>
     [{:ebs_status=>"attached",
       :ebs_delete_on_termination=>true,
       :ebs_attach_time=>"2009-11-18T14:03:34.000Z",
       :device_name=>"/dev/sda1",
       :ebs_volume_id=>"vol-e600f98f"},
      {:ebs_status=>"attached",
       :ebs_delete_on_termination=>true,
       :ebs_attach_time=>"2009-11-18T14:03:34.000Z",
       :device_name=>"/dev/sdk",
       :ebs_volume_id=>"vol-f900f990"}],
    :aws_instance_id=>"i-8ce84ae4"} , ... ]



87
88
89
90
91
92
93
94
95
 
# File 'lib/ec2/right_ec2_instances.rb', line 87

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

#describe_key_pairs(*key_pairs) ⇒ 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"},
    ..., {...} ]



154
155
156
157
158
159
160
 
# File 'lib/ec2/right_ec2.rb', line 154

def describe_key_pairs(*key_pairs)
  key_pairs = key_pairs.flatten
  link = generate_request("DescribeKeyPairs", amazonize_list('KeyName', key_pairs))
  request_cache_or_info :describe_key_pairs, link,  QEc2DescribeKeyPairParser, @@bench, key_pairs.blank?
rescue Exception
  on_exception
end

#describe_regions(*regions) ⇒ Object

Describe regions.

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



292
293
294
295
296
297
298
 
# File 'lib/ec2/right_ec2.rb', line 292

def describe_regions(*regions)
  regions = regions.flatten
  link = generate_request("DescribeRegions", amazonize_list('RegionName', regions))
  request_cache_or_info :describe_regions, link,  QEc2DescribeRegionsParser, @@bench, regions.blank?
rescue Exception
  on_exception
end

#describe_reserved_instances(*reserved_instances) ⇒ 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_start=>"2009-12-18T20:39:39.569Z"
  :aws_instance_count=>1}]



47
48
49
50
51
52
53
 
# File 'lib/ec2/right_ec2_reserved_instances.rb', line 47

def describe_reserved_instances(*reserved_instances)
  reserved_instances = reserved_instances.flatten
  link = generate_request("DescribeReservedInstances", amazonize_list('ReservedInstancesId', reserved_instances))
  request_cache_or_info(:describe_reserved_instances, link,  QEc2DescribeReservedInstancesParser, @@bench, reserved_instances.blank?)
rescue Exception
  on_exception
end

#describe_reserved_instances_offerings(*list_and_params) ⇒ Object

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

Optional params:

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



80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/ec2/right_ec2_reserved_instances.rb', line 80

def describe_reserved_instances_offerings(*list_and_params)
  list, params = AwsUtils::split_items_and_params(list_and_params)
  # backward compartibility with the old way
  list ||= Array(params[:aws_ids])
  rparams = {}
  rparams.update(amazonize_list('ReservedInstancesOfferingId', list)) unless list.blank?
  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, list.blank?)
rescue Exception
  on_exception
end

#describe_security_groups(list = []) ⇒ Object

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

# Amazon cloud:
ec2 = Rightscale::Ec2.new(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
ec2.describe_security_groups #=>
  [{:aws_perms=>
     [{:group=>"default", :owner=>"048291609141"},
      {:to_port=>"22",
       :protocol=>"tcp",
       :from_port=>"22",
       :cidr_ips=>"0.0.0.0/0"},
      {:to_port=>"9997",
       :protocol=>"tcp",
       :from_port=>"9997",
       :cidr_ips=>"0.0.0.0/0"}],
    :aws_group_name=>"photo_us",
    :aws_description=>"default group",
    :aws_owner=>"826693181925"}]

# Eucalyptus cloud:
ec2 = Rightscale::Ec2.new(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, :eucalyptus => true)
ec2.describe_security_groups #=>
  [{:aws_perms=>
     [{:to_port=>"65535",
       :group=>"default",
       :protocol=>"tcp",
       :owner=>"048291609141",
       :from_port=>"1"},
      {:to_port=>"65535",
       :group=>"default",
       :protocol=>"udp",
       :owner=>"048291609141",
       :from_port=>"1"},
      {:to_port=>"-1",
       :group=>"default",
       :protocol=>"icmp",
       :owner=>"048291609141",
       :from_port=>"-1"},
      {:to_port=>"22",
       :protocol=>"tcp",
       :from_port=>"22",
       :cidr_ip=>"0.0.0.0/0"},
      {:to_port=>"9997",
       :protocol=>"tcp",
       :from_port=>"9997",
       :cidr_ip=>"0.0.0.0/0"}],
    :aws_group_name=>"photo_us",
    :aws_description=>"default group",
    :aws_owner=>"826693181925"}]



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 82

def describe_security_groups(list=[])
  link = generate_request("DescribeSecurityGroups", amazonize_list('GroupName', list))

  request_cache_or_info( :describe_security_groups, link,  QEc2DescribeSecurityGroupsParser, @@bench, list.blank?) do |parser|
    result = []
    parser.result.each do |item|
      result_item = { :aws_owner       => item[:owner_id],
                      :aws_group_name  => item[:group_name],
                      :aws_description => item[:group_description] }
      aws_perms = []
      item[:ip_permissions].each do |permission|
        result_perm = {}
        result_perm[:from_port] = permission[:from_port]
        result_perm[:to_port]   = permission[:to_port]
        result_perm[:protocol]  = permission[:ip_protocol]
        # IP permissions
        Array(permission[:ip_ranges]).each do |ip_range|
          perm = result_perm.dup
          perm[:cidr_ips] = ip_range
          aws_perms << perm
        end
        # Group permissions
        Array(permission[:groups]).each do |group|
          perm = result_perm.dup
          perm[:group] = group[:group_name]
          perm[:owner] = group[:user_id]
          # AWS does not support Port Based Group Permissions but Eucalyptus does
          unless @params[:port_based_group_ingress]
            perm.delete(:from_port)
            perm.delete(:to_port)
            perm.delete(:protocol)
          end
          aws_perms << perm
        end
      end
      result_item[:aws_perms] = aws_perms.uniq
      result << result_item
    end
    result
  end
rescue Exception
  on_exception
end

#describe_snapshot_attribute(snapshot_id, attribute = 'createVolumePermission') ⇒ Object

Describe snapshot attribute.

ec2.describe_snapshot_attribute('snap-36fe435f') #=>
  {:create_volume_permission=>
     {:users=>["826690000000", "826690000001"], :groups=>['all']}}



239
240
241
242
243
244
245
246
 
# File 'lib/ec2/right_ec2_ebs.rb', line 239

def describe_snapshot_attribute(snapshot_id, attribute='createVolumePermission')
  link = generate_request("DescribeSnapshotAttribute",
                          'SnapshotId'=> snapshot_id,
                          'Attribute' => attribute)
  request_info(link, QEc2DescribeSnapshotAttributeParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#describe_snapshots(*snapshots) ⇒ Object

Describe all EBS snapshots.

ec2.describe_snapshots #=>

[ {:aws_volume_id=>"vol-545fac3d",
   :aws_description=>"Wikipedia XML Backups (Linux)",
   :aws_progress=>"100%",
   :aws_started_at=>"2009-09-28T23:49:50.000Z",
   :aws_owner=>"amazon",
   :aws_id=>"snap-8041f2e9",
   :aws_volume_size=>500,
   :aws_status=>"completed"},
  {:aws_volume_id=>"vol-185fac71",
   :aws_description=>"Sloan Digital Sky Survey DR6 Subset (Linux)",
   :aws_progress=>"100%",
   :aws_started_at=>"2009-09-28T23:56:10.000Z",
   :aws_owner=>"amazon",
   :aws_id=>"snap-3740f35e",
   :aws_volume_size=>180,
   :aws_status=>"completed"}, ...]



161
162
163
164
165
166
167
 
# File 'lib/ec2/right_ec2_ebs.rb', line 161

def describe_snapshots(*snapshots)
  snapshots = snapshots.flatten
  link = generate_request("DescribeSnapshots", amazonize_list('SnapshotId', snapshots))
  request_cache_or_info :describe_snapshots, link,  QEc2DescribeSnapshotsParser, @@bench, snapshots.blank?
rescue Exception
  on_exception
end

#describe_spot_datafeed_subscription ⇒ Object

Describe the data feed for Spot Instances.

ec2.describe_spot_datafeed_subscription #=>
  { :owner_id=>"826693181925",
    :bucket=>"bucket-for-konstantin-eu",
    :prefix=>"splogs/",
    :state=>"Active"}



269
270
271
272
 
# File 'lib/ec2/right_ec2_spot_instances.rb', line 269

def describe_spot_datafeed_subscription
  link = generate_request("DescribeSpotDatafeedSubscription")
  request_info(link, QEc2DescribeSpotDatafeedSubscriptionParser.new(:logger => @logger))
end

#describe_spot_instance_requests(*spot_instance_request_ids) ⇒ Object

Describe Spot Instance requests.

ec2.describe_spot_instance_requests #=>
  [{:type=>"one-time",
    :create_time=>"2010-03-10T10:30:32.000Z",
    :instance_type=>"c1.medium",
    :state=>"cancelled",
    :groups=>["default"],
    :product_description=>"Linux/UNIX",
    :spot_instance_request_id=>"sir-bfa06804",
    :image_id=>"ami-08f41161",
    :spot_price=>0.01,
    :monitoring_enabled=>false},
   {:type=>"one-time",
    :create_time=>"2010-03-10T10:33:29.000Z",
    :instance_type=>"c1.medium",
    :state=>"open",
    :groups=>["default", "33"],
    :product_description=>"Linux/UNIX",
    :spot_instance_request_id=>"sir-b1713a03",
    :image_id=>"ami-08f41161",
    :spot_price=>0.01,
    :monitoring_enabled=>false,
    :key_name=>"tim"},
   {:type=>"one-time",
    :instance_id=>"i-c516ceae",
    :create_time=>"2010-03-10T10:43:48.000Z",
    :instance_type=>"c1.medium",
    :state=>"active",
    :groups=>["default", "33"],
    :product_description=>"Linux/UNIX",
    :spot_instance_request_id=>"sir-5eb6c604",
    :image_id=>"ami-08f41161",
    :spot_price=>0.2,
    :monitoring_enabled=>false,
    :key_name=>"tim"}]



116
117
118
119
 
# File 'lib/ec2/right_ec2_spot_instances.rb', line 116

def describe_spot_instance_requests(*spot_instance_request_ids)
  link = generate_request("DescribeSpotInstanceRequests", amazonize_list('SpotInstanceRequestId', spot_instance_request_ids.flatten))
  request_info(link, QEc2DescribeSpotInstanceParser.new(:logger => @logger))
end

#describe_spot_price_history(options = {}) ⇒ Object

Describe Spot Price history. Options: :start_time, :end_time, instance_types, product_description

ec2.describe_spot_price_history #=>
  [{:spot_price=>0.054,
    :timestamp=>"2009-12-07T12:12:58.000Z",
    :product_description=>"Windows",
    :instance_type=>"m1.small"},
   {:spot_price=>0.06,
    :timestamp=>"2009-12-07T12:18:32.000Z",
    :product_description=>"Linux/UNIX",
    :instance_type=>"c1.medium"},
   {:spot_price=>0.198,
    :timestamp=>"2009-12-07T12:58:00.000Z",
    :product_description=>"Windows",
    :instance_type=>"m1.large"},
   {:spot_price=>0.028,
    :timestamp=>"2009-12-07T13:48:50.000Z",
    :product_description=>"Linux/UNIX",
    :instance_type=>"m1.small"}, ... ]

ec2.describe_spot_price_history(:start_time => 1.day.ago,
                                :end_time => 10.minutes.ago,
                                :instance_types => ["c1.medium", "m1.small"],
                                :product_description => "Linux/UNIX" ) #=>
  [{:product_description=>"Linux/UNIX",
    :timestamp=>"2010-02-04T05:44:36.000Z",
    :spot_price=>0.031,
    :instance_type=>"m1.small"},
   {:product_description=>"Linux/UNIX",
    :timestamp=>"2010-02-04T17:56:25.000Z",
    :spot_price=>0.058,
    :instance_type=>"c1.medium"}, ... ]



66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/ec2/right_ec2_spot_instances.rb', line 66

def describe_spot_price_history(options={})
  options = options.dup
  request_hash = {}
  request_hash['StartTime']          = AwsUtils::utc_iso8601(options[:start_time])     unless options[:start_time].blank?
  request_hash['EndTime']            = AwsUtils::utc_iso8601(options[:end_time])       unless options[:end_time].blank?
  request_hash['ProductDescription'] = options[:product_description]                   unless options[:product_description].blank?
  request_hash.merge!(amazonize_list('InstanceType', Array(options[:instance_types]))) unless options[:instance_types].blank?
  link = generate_request("DescribeSpotPriceHistory", request_hash)
  request_info(link, QEc2DescribeSpotPriceHistoryParser.new)
rescue Exception
  on_exception
end

#describe_subnets(*list_and_filters) ⇒ Object

Describe Subnet.

ec2.describe_subnets #=>
  [{:available_ip_address_count=>"251",
    :vpc_id=>"vpc-890ce2e0",
    :availability_zone=>"us-east-1a",
    :subnet_id=>"subnet-770de31e",
    :cidr_block=>"10.0.1.0/24",
    :state=>"available"}]



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/ec2/right_ec2_vpc.rb', line 106

def describe_subnets(*list_and_filters)
  list, filters = vpc__split_list_and_filters(list_and_filters)
  cache_for = (list.empty? && filters.empty?) ? :describe_subnets : nil
  request_hash = {}
  request_hash.merge!(amazonize_list('SubnetId', list))
  request_hash.merge!(amazonize_list(['Filter.?.Key','Filter.?.Value.?'], filters))
  link = generate_request("DescribeSubnets", request_hash)
  request_cache_or_info cache_for, link,  QEc2DescribeSubnetsParser, @@bench, cache_for
rescue Exception
  on_exception
end

#describe_volumes(*volumes) ⇒ 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       => "2008-06-18T08:19:28.000Z",
      :aws_status            => "in-use",
      :aws_id                => "vol-60957009",
      :aws_created_at        => "2008-06-18T08:19:20.000Z",
      :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,}, ... ]



52
53
54
55
56
57
58
 
# File 'lib/ec2/right_ec2_ebs.rb', line 52

def describe_volumes(*volumes)
  volumes = volumes.flatten
  link = generate_request("DescribeVolumes", amazonize_list('VolumeId', volumes))
  request_cache_or_info :describe_volumes, link,  QEc2DescribeVolumesParser, @@bench, volumes.blank?
rescue Exception
  on_exception
end

#describe_vpcs(*list_and_filters) ⇒ Object

Describe VPCs

ec2.describe_vpcs #=>
  [{:vpc_id=>"vpc-890ce2e0",
    :dhcp_options_id=>"default",
    :cidr_block=>"10.0.0.0/23",
    :state=>"available"}]

ec2.describe_vpcs("vpc-890ce2e0")



54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/ec2/right_ec2_vpc.rb', line 54

def describe_vpcs(*list_and_filters)
  list, filters = vpc__split_list_and_filters(list_and_filters)
  cache_for = (list.empty? && filters.empty?) ? :describe_vpcs : nil
  request_hash = {}
  request_hash.merge!(amazonize_list('VpcId', list))
  request_hash.merge!(amazonize_list(['Filter.?.Key','Filter.?.Value.?'], filters))
  link = generate_request("DescribeVpcs", request_hash)
  request_cache_or_info cache_for, link,  QEc2DescribeVpcsParser, @@bench, cache_for
rescue Exception
  on_exception
end

#describe_vpn_connections(*list_and_filters) ⇒ Object

Describe VPN connections.

ec2.describe_vpn_connections #=>
  [{:type=>"ipsec.1",
    :vpn_connection_id=>"vpn-a9a643c0",
    :customer_gateway_configuration=>
     "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<vpn_connection id=\"vpn-a9a643c0\">\n...</vpn_connection>\n",
    :state=>"available",
    :vpn_gateway_id=>"vgw-dfa144b6",
    :customer_gateway_id=>"cgw-81a643e8"}]



362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/ec2/right_ec2_vpc.rb', line 362

def describe_vpn_connections(*list_and_filters)
  list, filters = vpc__split_list_and_filters(list_and_filters)
  cache_for = (list.empty? && filters.empty?) ? :describe_vpn_connections : nil
  request_hash = {}
  request_hash.merge!(amazonize_list('VpnConnectionId', list))
  request_hash.merge!(amazonize_list(['Filter.?.Key','Filter.?.Value.?'], filters))
  link = generate_request("DescribeVpnConnections", request_hash)
  request_cache_or_info cache_for, link,  QEc2DescribeVpnConnectionsParser, @@bench, cache_for
rescue Exception
  on_exception
end

#describe_vpn_gateways(*list_and_filters) ⇒ Object

Describe VPN gateways.

ec2.describe_vpn_gateways #=>
  [{:type=>"ipsec.1",
    :availability_zone=>"us-east-1a",
    :attachments=>[{:vpc_id=>"vpc-890ce2e0", :state=>"attached"}],
    :vpn_gateway_id=>"vgw-dfa144b6"}]



282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/ec2/right_ec2_vpc.rb', line 282

def describe_vpn_gateways(*list_and_filters)
  list, filters = vpc__split_list_and_filters(list_and_filters)
  cache_for = (list.empty? && filters.empty?) ? :describe_vpn_gateways : nil
  request_hash = {}
  request_hash.merge!(amazonize_list('VpnGatewayId', list))
  request_hash.merge!(amazonize_list(['Filter.?.Key','Filter.?.Value.?'], filters))
  link = generate_request("DescribeVpnGateways", request_hash)
  request_cache_or_info cache_for, link,  QEc2DescribeVpnGatewaysParser, @@bench, cache_for
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"}



124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/ec2/right_ec2_ebs.rb', line 124

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

#detach_vpn_gateway(vpn_gateway_id, vpc_id) ⇒ Object

Detach VPN gateway.

ec2.detach_vpn_gateway('vgw-dfa144b6','vpc-890ce2e0') #=> true



328
329
330
331
332
333
334
 
# File 'lib/ec2/right_ec2_vpc.rb', line 328

def detach_vpn_gateway(vpn_gateway_id, vpc_id)
  link = generate_request("DetachVpnGateway", 'VpnGatewayId' => vpn_gateway_id,
                                              'VpcId'        => vpc_id )
  request_info(link, RightHttp2xxParser.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



240
241
242
243
244
245
246
 
# File 'lib/ec2/right_ec2.rb', line 240

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

Describe images helper params:

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



38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/ec2/right_ec2_images.rb', line 38

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, Array(list))
  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

#edit_security_group(action, group_name, params) ⇒ Object

Edit group permissions.

  action     - :authorize (or :grant) | :revoke (or :remove)
  group_name - security group name
  params     - a combination of options below:
    :source_group_owner => grantee id
    :source_group       => grantee group name
    :from_port          => from port
    :to_port            => to port
    :port               => set both :from_port and to_port with the same value
    :protocol           => :tcp | :udp | :icmp
    :cidr_ip            => '0.0.0.0/0'

ec2.edit_security_group( :grant,
                         'kd-sg-test',
                         :source_group       => "sketchy",
                         :source_group_owner => "600000000006",
                         :protocol           => 'tcp',
                         :port               => '80',
                         :cidr_ip            => '127.0.0.1/32') #=> true

P.S. setting both group based and port based ingresses is not supported by Amazon but by Eucalyptus.



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 176

def edit_security_group(action, group_name, params)
  hash = {}
  case action
  when :authorize, :grant then action = "AuthorizeSecurityGroupIngress"
  when :revoke, :remove   then action = "RevokeSecurityGroupIngress"
  else raise "Unknown action #{action.inspect}!"
  end
  hash['GroupName']                  = group_name
  hash['SourceSecurityGroupName']    = params[:source_group]                         unless params[:source_group].blank?
  hash['SourceSecurityGroupOwnerId'] = params[:source_group_owner].to_s.gsub(/-/,'') unless params[:source_group_owner].blank?
  hash['IpProtocol']                 = params[:protocol]                             unless params[:protocol].blank?
  unless params[:port].blank?
    hash['FromPort'] = params[:port]
    hash['ToPort']   = params[:port]
  end
  hash['FromPort']   = params[:from_port] unless params[:from_port].blank?
  hash['ToPort']     = params[:to_port]   unless params[:to_port].blank?
  hash['CidrIp']     = params[:cidr_ip]   unless params[:cidr_ip].blank?
  #
  link = generate_request(action, hash)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

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

:nodoc:



132
133
134
 
# File 'lib/ec2/right_ec2.rb', line 132

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



292
293
294
295
296
297
 
# File 'lib/ec2/right_ec2_instances.rb', line 292

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



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/ec2/right_ec2_instances.rb', line 32

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"



410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/ec2/right_ec2_instances.rb', line 410

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

#get_initial_password_v2(instance_id, private_key) ⇒ Object

Get Initial windows instance password using Amazon API call GetPasswordData.

puts ec2.get_initial_password_v2(my_awesome_instance[:aws_instance_id], my_awesome_key[:aws_material]) #=> "MhjWcgZuY6"

P.S. To say the truth there is absolutely no any speedup if to compare to the old get_initial_password method… ;(



428
429
430
431
432
433
434
435
436
437
438
439
 
# File 'lib/ec2/right_ec2_instances.rb', line 428

def get_initial_password_v2(instance_id, private_key)
  link = generate_request('GetPasswordData',
                          'InstanceId' => instance_id )
  response = request_info(link, QEc2GetPasswordDataParser.new(:logger => @logger))
  if response[:password_data].blank?
    raise AwsError.new("Initial password is not yet created for #{instance_id}")
  else
    OpenSSL::PKey::RSA.new(private_key).private_decrypt(Base64.decode64(response[:password_data]))
  end
rescue Exception
  on_exception
end

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

Launch new EC2 instances. Options: :image_id, :addressing_type, :min_count, max_count, :key_name, :kernel_id, :ramdisk_id, :availability_zone, :monitoring_enabled, :subnet_id, :disable_api_termination, :instance_initiated_shutdown_behavior, :block_device_mappings

Returns a list of launched instances or an exception.

ec2.launch_instances( 'ami-c2a3f5d4',
                      :min_count => 1,
                      :group_ids => 'default',
                      :user_data => 'Ohoho!',
                      :availability_zone => "us-east-1a",
                      :disable_api_termination => true,
                      :instance_initiated_shutdown_behavior => 'terminate',
                      :block_device_mappings => [ {:ebs_snapshot_id=>"snap-7360871a",
                                                   :ebs_delete_on_termination=>true,
                                                   :device_name => "/dev/sdk",
                                                   :virtual_name => "mystorage"} ] ) #=>
  [{:aws_image_id=>"ami-c2a3f5d4",
    :dns_name=>"",
    :aws_instance_type=>"m1.small",
    :aws_owner=>"826693181925",
    :root_device_name=>"/dev/sda1",
    :instance_class=>"elastic",
    :state_reason_code=>0,
    :aws_state=>"pending",
    :private_dns_name=>"",
    :aws_reason=>"",
    :aws_launch_time=>"2009-11-18T14:03:25.000Z",
    :aws_reservation_id=>"r-54d38542",
    :state_reason_message=>"pending",
    :aws_state_code=>0,
    :ami_launch_index=>"0",
    :aws_availability_zone=>"us-east-1a",
    :aws_groups=>["default"],
    :monitoring_state=>"disabled",
    :aws_product_codes=>[],
    :ssh_key_name=>"",
    :aws_instance_id=>"i-8ce84ae4"}]



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/ec2/right_ec2_instances.rb', line 193

def launch_instances(image_id, options={})
  @logger.info("Launching instance of image #{image_id} for #{@aws_access_key_id}, " +
               "key: #{options[:key_name]}, groups: #{Array(options[:group_ids]).join(',')}")
  options[:image_id]    = image_id
  options[:min_count] ||= 1
  options[:max_count] ||= options[:min_count]
  params = prepare_instance_launch_params(options)
  link = generate_request("RunInstances", params)
  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



208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/ec2/right_ec2_images.rb', line 208

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]))      if vars[:user_id]
  params.update(amazonize_list('UserGroup',   vars[:user_group]))   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



243
244
245
 
# File 'lib/ec2/right_ec2_images.rb', line 243

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

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

Grant image launch permissions to users. Parameter user_id 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



226
227
228
 
# File 'lib/ec2/right_ec2_images.rb', line 226

def modify_image_launch_perm_add_users(image_id, user_id=[])
  modify_image_attribute(image_id, 'launchPermission', 'add', :user_id => user_id)
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



251
252
253
 
# File 'lib/ec2/right_ec2_images.rb', line 251

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

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

Revokes image launch permissions for users. user_id 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



234
235
236
 
# File 'lib/ec2/right_ec2_images.rb', line 234

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

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

Add product code to image

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



259
260
261
 
# File 'lib/ec2/right_ec2_images.rb', line 259

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

#modify_instance_attribute(instance_id, attribute, value) ⇒ Object

Modify instance attribute. Attributes: :instance_type, :kernel, :ramdisk, :user_data, :disable_api_termination, :instance_initiated_shutdown_behavior, :root_device_name, :block_device_mapping

ec2.modify_instance_attribute(instance, :instance_initiated_shutdown_behavior, "stop") #=> true



370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/ec2/right_ec2_instances.rb', line 370

def modify_instance_attribute(instance_id, attribute, value)
  attribute = INSTANCE_ATTRIBUTE_MAPPING[attribute.to_s] || attribute.to_s
  params = { 'InstanceId' => instance_id,
             'Attribute'  => attribute }
  case attribute
  when "blockDeviceMapping"
    params.merge!(amazonize_block_device_mappings(value))
  when "userData"
    params['Value'] = Base64.encode64(value).delete("\n")
  else
    params['Value'] = value
  end
  link = generate_request('ModifyInstanceAttribute', params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#modify_snapshot_attribute(snapshot_id, attribute = 'createVolumePermission', operation_type = 'add', vars = {}) ⇒ Object

Modify snapshot attribute.

attribute      : currently, only 'createVolumePermission' is supported.
operation_type : currently, only 'add' & 'remove' are supported.
vars:
  :user_group  : currently, only 'all' is supported.
  :user_id     : an array of user ids



269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/ec2/right_ec2_ebs.rb', line 269

def modify_snapshot_attribute(snapshot_id, attribute='createVolumePermission', operation_type='add', vars = {})
  params =  {'SnapshotId'    => snapshot_id,
             'Attribute'     => attribute,
             'OperationType' => operation_type}
  params.update(amazonize_list('UserId',    Array(vars[:user_id])))    if vars[:user_id]
  params.update(amazonize_list('UserGroup', Array(vars[:user_group]))) if vars[:user_group]
  link = generate_request("ModifySnapshotAttribute", params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#modify_snapshot_attribute_create_volume_permission_add_groups(snapshot_id, *user_group) ⇒ Object

Grant create volume permission for user groups (currently only ‘all’ is supported).

ec2.modify_snapshot_attribute_create_volume_permission_add_groups('snap-36fe435f') #=> true



301
302
303
304
305
 
# File 'lib/ec2/right_ec2_ebs.rb', line 301

def modify_snapshot_attribute_create_volume_permission_add_groups(snapshot_id, *user_group)
  user_group.flatten!
  user_group = ['all'] if user_group.blank?
  modify_snapshot_attribute(snapshot_id, 'createVolumePermission', 'add', :user_group => user_group )
end

#modify_snapshot_attribute_create_volume_permission_add_users(snapshot_id, *user_id) ⇒ Object

Grant create volume permission for a list of users.

ec2.modify_snapshot_attribute_create_volume_permission_add_users('snap-36fe435f', '000000000000', '000000000001') #=> true



285
286
287
 
# File 'lib/ec2/right_ec2_ebs.rb', line 285

def modify_snapshot_attribute_create_volume_permission_add_users(snapshot_id, *user_id)
  modify_snapshot_attribute(snapshot_id, 'createVolumePermission', 'add', :user_id => user_id.flatten )
end

#modify_snapshot_attribute_create_volume_permission_remove_groups(snapshot_id, *user_group) ⇒ Object

Remove create volume permission for user groups (currently only ‘all’ is supported).

ec2.modify_snapshot_attribute_create_volume_permission_remove_groups('snap-36fe435f') #=> true



311
312
313
314
315
 
# File 'lib/ec2/right_ec2_ebs.rb', line 311

def modify_snapshot_attribute_create_volume_permission_remove_groups(snapshot_id, *user_group)
  user_group.flatten!
  user_group = ['all'] if user_group.blank?
  modify_snapshot_attribute(snapshot_id, 'createVolumePermission', 'remove', :user_group => user_group )
end

#modify_snapshot_attribute_create_volume_permission_remove_users(snapshot_id, *user_id) ⇒ Object

Revoke create volume permission for a list of users.

ec2.modify_snapshot_attribute_create_volume_permission_remove_users('snap-36fe435f', '000000000000', '000000000001') #=> true



293
294
295
 
# File 'lib/ec2/right_ec2_ebs.rb', line 293

def modify_snapshot_attribute_create_volume_permission_remove_users(snapshot_id, *user_id)
  modify_snapshot_attribute(snapshot_id, 'createVolumePermission', 'remove', :user_id => user_id.flatten )
end

#monitor_instances(*list) ⇒ Object

Enables monitoring for a running instances. For more information, refer to the Amazon CloudWatch Developer Guide.

ec2.monitor_instances('i-8437ddec') #=>
  {:instance_id=>"i-8437ddec", :monitoring_state=>"pending"}



33
34
35
36
37
38
 
# File 'lib/ec2/right_ec2_monitoring.rb', line 33

def monitor_instances(*list)
  link = generate_request("MonitorInstances", amazonize_list('InstanceId', list.flatten) )
  request_info(link, QEc2MonitorInstancesParser.new(:logger => @logger)).first
rescue Exception
  on_exception
end

#prepare_instance_launch_params(options = {}) ⇒ Object

:nodoc:



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/ec2/right_ec2_instances.rb', line 207

def prepare_instance_launch_params(options={}) # :nodoc:
  params = amazonize_list('SecurityGroup', Array(options[:group_ids]))
  params['InstanceType']                      = options[:instance_type] || DEFAULT_INSTANCE_TYPE
  params['ImageId']                           = options[:image_id]                             unless options[:image_id].blank?
  params['AddressingType']                    = options[:addressing_type]                      unless options[:addressing_type].blank?
  params['MinCount']                          = options[:min_count]                            unless options[:min_count].blank?
  params['MaxCount']                          = options[:max_count]                            unless options[:max_count].blank?
  params['KeyName']                           = options[:key_name]                             unless options[:key_name].blank?
  params['KernelId']                          = options[:kernel_id]                            unless options[:kernel_id].blank?
  params['RamdiskId']                         = options[:ramdisk_id]                           unless options[:ramdisk_id].blank?
  params['Placement.AvailabilityZone']        = options[:availability_zone]                    unless options[:availability_zone].blank?
  params['Monitoring.Enabled']                = options[:monitoring_enabled].to_s              if     options[:monitoring_enabled]
  params['SubnetId']                          = options[:subnet_id]                            unless options[:subnet_id].blank?
  params['AdditionalInfo']                    = options[:additional_info]                      unless options[:additional_info].blank?
  params['DisableApiTermination']             = options[:disable_api_termination].to_s         unless options[:disable_api_termination].nil?
  params['InstanceInitiatedShutdownBehavior'] = options[:instance_initiated_shutdown_behavior] unless options[:instance_initiated_shutdown_behavior].blank?
#     params['VolumeId']                          = options[:volume_id]                            unless options[:volume_id].blank?
#     params['RootDeviceName']                    = options[:root_device_name]                     unless options[:root_device_name].blank?
#     params['RootDeviceType']                    = options[:root_device_type]                     unless options[:root_device_type].blank?
  params.merge!(amazonize_block_device_mappings(options[:block_device_mappings]))
  unless options[:user_data].blank?
    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") unless options[:user_data].blank?
  end
  params
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'



100
101
102
103
104
105
106
 
# File 'lib/ec2/right_ec2_reserved_instances.rb', line 100

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

Reboot an EC2 instance. Returns true or an exception.

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



303
304
305
306
307
308
309
 
# File 'lib/ec2/right_ec2_instances.rb', line 303

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

#register_image(options) ⇒ Object

Register new image at Amazon. Options: :image_location, :name, :description, :architecture, :kernel_id, :ramdisk_id, :root_device_name, :block_device_mappings.

Returns new image id.

# Register S3 image
ec2.register_image('bucket_for_k_dzreyev/image_bundles/kd__CentOS_1_10_2009_10_21_13_30_43_MSD/image.manifest.xml') #=> 'ami-e444444d'

# or
image_reg_params = {  :image_location => 'bucket_for_k_dzreyev/image_bundles/kd__CentOS_1_10_2009_10_21_13_30_43_MSD/image.manifest.xml',
                      :name => 'my-test-one-1',
                      :description => 'My first test image' }
ec2.register_image(image_reg_params) #=> "ami-bca1f7aa"

# Register EBS image
image_reg_params = { :name        => 'my-test-image',
                     :description => 'My first test image',
                     :root_device_name => "/dev/sda1",
                     :block_device_mappings => [ { :ebs_snapshot_id=>"snap-7360871a",
                                                   :ebs_delete_on_termination=>true,
                                                   :device_name=>"/dev/sda1"} ] }
ec2.register_image(image_reg_params) #=> "ami-b2a1f7a4"



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/ec2/right_ec2_images.rb', line 136

def register_image(options)
  case
  when options.is_a?(String)
    options = { :image_location => options }
  when !options.is_a?(Hash)
    raise "Unsupported options type"
  end
  params = {}
  params['ImageLocation']  = options[:image_location]   if options[:image_location]
  params['Name']           = options[:name]             if options[:name]
  params['Description']    = options[:description]      if options[:description]
  params['Architecture']   = options[:architecture]     if options[:architecture]
  params['KernelId']       = options[:kernel_id]        if options[:kernel_id]
  params['RamdiskId']      = options[:ramdisk_id]       if options[:ramdisk_id]
  params['RootDeviceName'] = options[:root_device_name] if options[:root_device_name]
#      params['SnapshotId']     = options[:snapshot_id]      if options[:snapshot_id]
  params.merge!(amazonize_block_device_mappings(options[:block_device_mappings]))
  link = generate_request("RegisterImage", params)
  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



253
254
255
256
257
258
259
 
# File 'lib/ec2/right_ec2.rb', line 253

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



138
139
140
 
# File 'lib/ec2/right_ec2.rb', line 138

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

#request_spot_instances(options) ⇒ Object

Create a Spot Instance request.

Mandatory params: :image_id, :spot_price, :instance_type Optional params: :valid_from, :valid_until, :instance_count, :type, :launch_group, :availability_zone_group, :key_name, :user_data, :addressing_type, :kernel_id, :ramdisk_id, :subnet_id, :availability_zone, :monitoring_enabled, :groups, :block_device_mappings

ec2.request_spot_instances(
  :image_id => 'ami-08f41161',
  :spot_price => 0.01,
  :key_name => 'tim',
  :instance_count => 2,
  :groups => ['33','default'],
  :instance_type => 'c1.medium') #=>

  [{:product_description=>"Linux/UNIX",
    :type=>"one-time",
    :spot_instance_requestId=>"sir-7a893003",
    :monitoring_enabled=>false,
    :image_id=>"ami-08f41161",
    :state=>"open",
    :spot_price=>0.01,
    :groups=>["default", "33"],
    :key_name=>"tim",
    :create_time=>"2010-03-10T10:33:09.000Z",
    :instance_type=>"c1.medium"},
   {:product_description=>"Linux/UNIX",
    :type=>"one-time",
    :spot_instance_requestId=>"sir-13dc9a03",
    :monitoring_enabled=>false,
    :image_id=>"ami-08f41161",
    :state=>"open",
    :spot_price=>0.01,
    :groups=>["default", "33"],
    :key_name=>"tim",
    :create_time=>"2010-03-10T10:33:09.000Z",
    :instance_type=>"c1.medium"}]

ec2.request_spot_instances(
  :image_id => 'ami-08f41161',
  :spot_price => 0.01,
  :instance_type => 'm1.small',
  :valid_from => 10.minutes.since,
  :valid_until => 1.hour.since,
  :instance_count => 1,
  :key_name => 'tim',
  :groups => ['33','default'],
  :availability_zone => 'us-east-1a',
  :monitoring_enabled => true,
  :launch_group => 'lg1',
  :availability_zone_group => 'azg1',
  :block_device_mappings => [ { :device_name => '/dev/sdk',
                                :ebs_snapshot_id => 'snap-145cbc7d',
                                :ebs_delete_on_termination => true,
                                :ebs_volume_size => 3,
                                :virtual_name => 'ephemeral2'
                               } ] ) #=>

  [{:monitoring_enabled=>true,
    :type=>"one-time",
    :image_id=>"ami-08f41161",
    :launch_group=>"lg1",
    :state=>"open",
    :valid_until=>"2010-02-05T19:13:44.000Z",
    :create_time=>"2010-02-05T18:13:46.000Z",
    :availability_zone_group=>"azg1",
    :spot_price=>0.01,
    :block_device_mappings=>
     [{:ebs_delete_on_termination=>true,
       :ebs_volume_size=>3,
       :virtual_name=>"ephemeral2",
       :device_name=>"/dev/sdk",
       :ebs_snapshot_id=>"snap-145cbc7d"}],
    :instance_type=>"m1.small",
    :groups=>["default", "33"],
    :product_description=>"Linux/UNIX",
    :key_name=>"tim",
    :valid_from=>"2010-02-05T18:23:44.000Z",
    :availability_zone=>"us-east-1a",
    :spot_instance_request_id=>"sir-32da8a03"}]



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/ec2/right_ec2_spot_instances.rb', line 203

def request_spot_instances(options)
  options = options.dup
  request_hash = { 'SpotPrice'                        => options[:spot_price],
                   'LaunchSpecification.ImageId'      => options[:image_id],
                   'LaunchSpecification.InstanceType' => options[:instance_type]}
  request_hash['ValidFrom']                      = AwsUtils::utc_iso8601(options[:valid_from])  unless options[:valid_from].blank?
  request_hash['ValidUntil']                     = AwsUtils::utc_iso8601(options[:valid_until]) unless options[:valid_until].blank?
  request_hash['InstanceCount']                      = options[:instance_count]                 unless options[:instance_count].blank?
  request_hash['Type']                               = options[:type]                           unless options[:type].blank?
  request_hash['LaunchGroup']                        = options[:launch_group]                   unless options[:launch_group].blank?
  request_hash['AvailabilityZoneGroup']              = options[:availability_zone_group]        unless options[:availability_zone_group].blank?
  request_hash['LaunchSpecification.KeyName']        = options[:key_name]                       unless options[:key_name].blank?
  request_hash['LaunchSpecification.AddressingType'] = options[:addressing_type]                unless options[:addressing_type].blank?
  request_hash['LaunchSpecification.KernelId']       = options[:kernel_id]                      unless options[:kernel_id].blank?
  request_hash['LaunchSpecification.RamdiskId']      = options[:ramdisk_id]                     unless options[:ramdisk_id].blank?
  request_hash['LaunchSpecification.SubnetId']       = options[:subnet_id]                      unless options[:subnet_id].blank?
  request_hash['LaunchSpecification.Placement.AvailabilityZone'] = options[:availability_zone]  unless options[:availability_zone].blank?
  request_hash['LaunchSpecification.Monitoring.Enabled']         = options[:monitoring_enabled] unless options[:monitoring_enabled].blank?
  request_hash.merge!(amazonize_list('LaunchSpecification.SecurityGroup', options[:groups]))    unless options[:groups].blank?
  request_hash.merge!(amazonize_block_device_mappings(options[:block_device_mappings], 'LaunchSpecification.BlockDeviceMapping'))
  unless options[:user_data].blank?
    # See RightAws::Ec2#run_instances
    options[:user_data].strip!
    request_hash['LaunchSpecification.UserData'] = Base64.encode64(options[:user_data]).delete("\n") unless options[:user_data].blank?
  end
  link = generate_request("RequestSpotInstances", request_hash)
  request_info(link, QEc2DescribeSpotInstanceParser.new(:logger => @logger))
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



188
189
190
191
192
193
194
195
 
# File 'lib/ec2/right_ec2_images.rb', line 188

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

#reset_instance_attribute(instance_id, attribute) ⇒ Object

Describe instance attribute. Attributes: :kernel, :ramdisk

ec2.reset_instance_attribute(instance, :kernel) #=> true



355
356
357
358
359
360
361
362
363
 
# File 'lib/ec2/right_ec2_instances.rb', line 355

def reset_instance_attribute(instance_id, attribute)
  attribute = INSTANCE_ATTRIBUTE_MAPPING[attribute.to_s] || attribute.to_s
  link = generate_request('ResetInstanceAttribute',
                          'InstanceId' => instance_id,
                          'Attribute'  => attribute )
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#reset_snapshot_attribute(snapshot_id, attribute = 'createVolumePermission') ⇒ Object

Reset permission settings for the specified snapshot.

ec2.reset_snapshot_attribute('snap-cecd29a7') #=> true



252
253
254
255
256
257
258
259
 
# File 'lib/ec2/right_ec2_ebs.rb', line 252

def reset_snapshot_attribute(snapshot_id, attribute='createVolumePermission')
  link = generate_request("ResetSnapshotAttribute",
                          'SnapshotId' => snapshot_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



231
232
233
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 231

def revoke_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0')
  edit_security_group( :revoke, name, :from_port => from_port, :to_port => to_port, :protocol => protocol, :cidr_ip => cidr_ip )
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



214
215
216
 
# File 'lib/ec2/right_ec2_security_groups.rb', line 214

def revoke_security_group_named_ingress(name, owner, group)
  edit_security_group( :revoke, name, :source_group_owner => owner, :source_group => group)
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, monitoring_enabled = nil, subnet_id = nil, disable_api_termination = nil, instance_initiated_shutdown_behavior = 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"
   }]



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/ec2/right_ec2_instances.rb', line 130

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,
                  monitoring_enabled = nil, subnet_id = nil, disable_api_termination = nil,
                  instance_initiated_shutdown_behavior = 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,
                               :monitoring_enabled                   => monitoring_enabled,
                               :subnet_id                            => subnet_id,
                               :disable_api_termination              => disable_api_termination,
                               :instance_initiated_shutdown_behavior => instance_initiated_shutdown_behavior,
                               :block_device_mappings                =>  block_device_mappings
                             })
end

#start_instances(*instance_aws_ids) ⇒ Object

Start instances.

ec2.start_instances("i-36e84a5e") #=>
  [{:aws_prev_state_name=>"stopped",
    :aws_instance_id=>"i-36e84a5e",
    :aws_current_state_code=>16,
    :aws_current_state_name=>"running",
    :aws_prev_state_code=>80}]



247
248
249
250
251
 
# File 'lib/ec2/right_ec2_instances.rb', line 247

def start_instances(*instance_aws_ids)
 instance_aws_ids = instance_aws_ids.flatten
 link = generate_request("StartInstances", amazonize_list('InstanceId', instance_aws_ids))
 request_info(link, QEc2TerminateInstancesParser.new(:logger => @logger))
end

#stop_instances(*instance_aws_ids) ⇒ Object

Stop instances.

ec2.stop_instances("i-36e84a5e") #=>
  [{:aws_prev_state_code=>16,
    :aws_prev_state_name=>"running",
    :aws_instance_id=>"i-36e84a5e",
    :aws_current_state_code=>64,
    :aws_current_state_name=>"stopping"}]



262
263
264
265
266
 
# File 'lib/ec2/right_ec2_instances.rb', line 262

def stop_instances(*instance_aws_ids)
  instance_aws_ids = instance_aws_ids.flatten
  link = generate_request("StopInstances", amazonize_list('InstanceId', instance_aws_ids))
  request_info(link, QEc2TerminateInstancesParser.new(:logger => @logger))
end

#terminate_instances(*instance_aws_ids) ⇒ Object

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

ec2.terminate_instances(['i-cceb49a4']) #=>
  [{:aws_instance_id=>"i-cceb49a4",
    :aws_current_state_code=>32,
    :aws_current_state_name=>"shutting-down",
    :aws_prev_state_code=>16,
    :aws_prev_state_name=>"running"}]



277
278
279
280
281
282
283
 
# File 'lib/ec2/right_ec2_instances.rb', line 277

def terminate_instances(*instance_aws_ids)
  instance_aws_ids = instance_aws_ids.flatten
  link = generate_request("TerminateInstances", amazonize_list('InstanceId', instance_aws_ids))
  request_info(link, QEc2TerminateInstancesParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#try_create_snapshot(volume_id, connect_timeout = nil, read_timeout = nil, description = '') ⇒ 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', 'KD: WooHoo!!') #=>
  {:aws_volume_id=>"vol-e429db8d",
   :aws_started_at=>"2009-10-01T09:23:38.000Z",
   :aws_description=>"KD: WooHoo!!",
   :aws_owner=>"648770000000",
   :aws_progress=>"",
   :aws_status=>"pending",
   :aws_volume_size=>1,
   :aws_id=>"snap-3df54854"}



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/ec2/right_ec2_ebs.rb', line 205

def try_create_snapshot(volume_id, connect_timeout = nil, read_timeout = nil, description='')
  # 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,
                          "Description" => description)
  request_info(link, QEc2DescribeSnapshotsParser.new(:logger => @logger)).first

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

#unmonitor_instances(*list) ⇒ Object

Disables monitoring for a running instances. For more information, refer to the Amazon CloudWatch Developer Guide.

ec2.unmonitor_instances('i-8437ddec') #=>
  {:instance_id=>"i-8437ddec", :monitoring_state=>"disabling"}



45
46
47
48
49
50
 
# File 'lib/ec2/right_ec2_monitoring.rb', line 45

def unmonitor_instances(*list)
  link = generate_request("UnmonitorInstances", amazonize_list('InstanceId', list.flatten) )
  request_info(link, QEc2MonitorInstancesParser.new(:logger => @logger)).first
rescue Exception
  on_exception
end