Class: Awsum::Ec2

Inherits:
Object show all
Includes:
Requestable
Defined in:
lib/awsum/ec2.rb,
lib/awsum/ec2/image.rb,
lib/awsum/ec2/region.rb,
lib/awsum/ec2/volume.rb,
lib/awsum/ec2/address.rb,
lib/awsum/ec2/keypair.rb,
lib/awsum/ec2/instance.rb,
lib/awsum/ec2/snapshot.rb,
lib/awsum/ec2/security_group.rb,
lib/awsum/ec2/availability_zone.rb,
lib/awsum/ec2/reserved_instance.rb,
lib/awsum/ec2/parsers/image_parser.rb,
lib/awsum/ec2/parsers/region_parser.rb,
lib/awsum/ec2/parsers/volume_parser.rb,
lib/awsum/ec2/parsers/address_parser.rb,
lib/awsum/ec2/parsers/keypair_parser.rb,
lib/awsum/ec2/parsers/instance_parser.rb,
lib/awsum/ec2/parsers/snapshot_parser.rb,
lib/awsum/ec2/reserved_instances_offering.rb,
lib/awsum/ec2/parsers/register_image_parser.rb,
lib/awsum/ec2/parsers/security_group_parser.rb,
lib/awsum/ec2/parsers/availability_zone_parser.rb,
lib/awsum/ec2/parsers/reserved_instance_parser.rb,
lib/awsum/ec2/parsers/reserved_instances_offering_parser.rb,
lib/awsum/ec2/parsers/purchase_reserved_instances_offering_parser.rb

Overview

Handles all interaction with Amazon EC2

Getting Started

Create an Awsum::Ec2 object and begin calling methods on it.

require 'rubygems'
require 'awsum'
ec2 = Awsum::Ec2.new('your access id', 'your secret key')
images = ec2.my_images
...

All calls to EC2 can be done directly in this class, or through a more object oriented way through the various returned classes

Examples

ec2.image('ami-ABCDEF').run

ec2.instance('i-123456789').volumes.each do |vol|
  vol.create_snapsot
end

ec2.regions.each do |region|
  region.use
    images.each do |img|
      puts "#{img.id} - #{region.name}"
    end
  end
end

Errors

All methods will raise an Awsum::Error if an error is returned from Amazon

Missing Methods

  • ConfirmProductInstance

  • ModifyImageAttribute

  • DescribeImageAttribute

  • ResetImageAttribute

If you need any of this functionality, please consider getting involved and help complete this library.

Defined Under Namespace

Classes: Address, AddressParser, AvailabilityZone, AvailabilityZoneParser, Image, ImageParser, Instance, InstanceParser, KeyPair, KeyPairParser, PurchaseReservedInstancesOfferingParser, Region, RegionParser, RegisterImageParser, ReservedInstance, ReservedInstanceParser, ReservedInstancesOffering, ReservedInstancesOfferingParser, SecurityGroup, SecurityGroupParser, Snapshot, SnapshotParser, Volume, VolumeParser

Instance Method Summary collapse

Constructor Details

#initialize(access_key = nil, secret_key = nil) ⇒ Ec2

Create an new ec2 instance

The access_key and secret_key are both required to do any meaningful work.

If you want to get these keys from environment variables, you can do that in your code as follows:

ec2 = Awsum::Ec2.new(ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'])



60
61
62
63
 
# File 'lib/awsum/ec2.rb', line 60

def initialize(access_key = nil, secret_key = nil)
  @access_key = access_key
  @secret_key = secret_key
end

Instance Method Details

#address(public_ip) ⇒ Object

Get the Address with a specific public ip



401
402
403
 
# File 'lib/awsum/ec2.rb', line 401

def address(public_ip)
  addresses(public_ip)[0]
end

#addresses(*public_ips) ⇒ Object

List Addresses



388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/awsum/ec2.rb', line 388

def addresses(*public_ips)
  action = 'DescribeAddresses'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(public_ips, 'PublicIp'))

  response = send_query_request(params)
  parser = Awsum::Ec2::AddressParser.new(self)
  parser.parse(response.body)
end

#allocate_address ⇒ Object

Allocate Address

Will aquire an elastic ip address for use with your account



408
409
410
411
412
413
414
415
416
417
 
# File 'lib/awsum/ec2.rb', line 408

def allocate_address
  action = 'AllocateAddress'
  params = {
    'Action' => action
  }

  response = send_query_request(params)
  parser = Awsum::Ec2::AddressParser.new(self)
  parser.parse(response.body)[0]
end

#associate_address(instance_id, public_ip) ⇒ Object

Associate Address

Will link an allocated elastic ip address to an Instance

NOTE: If the ip address is already associated with another instance, it will be associated with the new instance.

You can run this command more than once and it will not return an error.



426
427
428
429
430
431
432
433
434
435
436
 
# File 'lib/awsum/ec2.rb', line 426

def associate_address(instance_id, public_ip)
  action = 'AssociateAddress'
  params = {
    'Action'     => action,
    'InstanceId' => instance_id,
    'PublicIp'   => public_ip
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#attach_volume(volume_id, instance_id, device = '/dev/sdh') ⇒ Object

Attach a volume to an instance



263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/awsum/ec2.rb', line 263

def attach_volume(volume_id, instance_id, device = '/dev/sdh')
  action = 'AttachVolume'
  params = {
    'Action'     => action,
    'VolumeId'   => volume_id,
    'InstanceId' => instance_id,
    'Device'     => device
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#authorize_security_group_ingress(group_name, options = {}) ⇒ Object

Authorize access on a specific security group

Options:

User/Group access

  • :source_security_group_name - Name of the security group to authorize access to when operating on a user/group pair

  • :source_security_group_owner_id - Owner of the security group to authorize access to when operating on a user/group pair

CIDR IP access

  • :ip_protocol - IP protocol to authorize access to when operating on a CIDR IP (tcp, udp or icmp) (default: tcp)

  • :from_port - Bottom of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.

  • :to_port - Top of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.

  • :cidr_ip - CIDR IP range to authorize access to when operating on a CIDR IP. (default: 0.0.0.0/0)

Raises:

  • (ArgumentError) 


586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
 
# File 'lib/awsum/ec2.rb', line 586

def authorize_security_group_ingress(group_name, options = {})
  got_at_least_one_user_group_option = !options[:source_security_group_name].nil? || !options[:source_security_group_owner_id].nil?
  got_user_group_options = !options[:source_security_group_name].nil? && !options[:source_security_group_owner_id].nil?
  got_at_least_one_cidr_option = !options[:ip_protocol].nil? || !options[:from_port].nil? || !options[:to_port].nil? || !options[:cidr_ip].nil?
  #Add in defaults
  options = {:cidr_ip => '0.0.0.0/0'}.merge(options) if got_at_least_one_cidr_option
  options = {:ip_protocol => 'tcp'}.merge(options) if got_at_least_one_cidr_option
  got_cidr_options = !options[:ip_protocol].nil? && !options[:from_port].nil? && !options[:to_port].nil? && !options[:cidr_ip].nil?
  raise ArgumentError.new('Can only authorize user/group or CIDR IP, not both') if got_at_least_one_user_group_option && got_at_least_one_cidr_option
  raise ArgumentError.new('Need all user/group options when authorizing user/group access') if got_at_least_one_user_group_option && !got_user_group_options
  raise ArgumentError.new('Need all CIDR IP options when authorizing CIDR IP access') if got_at_least_one_cidr_option && !got_cidr_options
  raise ArgumentError.new('ip_protocol can only be one of tcp, udp or icmp') if got_at_least_one_cidr_option && !%w(tcp udp icmp).detect{|p| p == options[:ip_protocol] }

  action = 'AuthorizeSecurityGroupIngress'
  params = {
    'Action'    => action,
    'GroupName' => group_name
  }
  params['SourceSecurityGroupName'] = options[:source_security_group_name] unless options[:source_security_group_name].nil?
  params['SourceSecurityGroupOwnerId'] = options[:source_security_group_owner_id] unless options[:source_security_group_owner_id].nil?
  params['IpProtocol'] = options[:ip_protocol] unless options[:ip_protocol].nil?
  params['FromPort'] = options[:from_port] unless options[:from_port].nil?
  params['ToPort'] = options[:to_port] unless options[:to_port].nil?
  params['CidrIp'] = options[:cidr_ip] unless options[:cidr_ip].nil?

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#availability_zones(*zone_names) ⇒ Object

List all AvailabilityZone(s)



352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/awsum/ec2.rb', line 352

def availability_zones(*zone_names)
  action = 'DescribeAvailabilityZones'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(zone_names, 'ZoneName'))

  response = send_query_request(params)
  parser = Awsum::Ec2::AvailabilityZoneParser.new(self)
  parser.parse(response.body)
end

#create_key_pair(key_name) ⇒ Object

Create a new KeyPair



508
509
510
511
512
513
514
515
516
517
518
 
# File 'lib/awsum/ec2.rb', line 508

def create_key_pair(key_name)
  action = 'CreateKeyPair'
  params = {
    'Action'  => action,
    'KeyName' => key_name
  }

  response = send_query_request(params)
  parser = Awsum::Ec2::KeyPairParser.new(self)
  parser.parse(response.body)[0]
end

#create_security_group(name, description) ⇒ Object

Create a new SecurityGroup



551
552
553
554
555
556
557
558
559
560
561
 
# File 'lib/awsum/ec2.rb', line 551

def create_security_group(name, description)
  action = 'CreateSecurityGroup'
  params = {
    'Action'           => action,
    'GroupName'        => name,
    'GroupDescription' => description
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#create_snapshot(volume_id) ⇒ Object

Create a Snapshot of a Volume



309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/awsum/ec2.rb', line 309

def create_snapshot(volume_id)
  action = 'CreateSnapshot'
  params = {
    'Action'   => action,
    'VolumeId' => volume_id
  }

  response = send_query_request(params)
  parser = Awsum::Ec2::SnapshotParser.new(self)
  parser.parse(response.body)[0]
end

#create_volume(availability_zone, options = {}) ⇒ Object

Create a new volume

Options:

  • :size - The size of the volume to be created (in GB) (NOTE: Required if you are not creating from a snapshot)

  • :snapshot_id - The snapshot id from which to create the volume

Raises:

  • (ArgumentError) 


246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/awsum/ec2.rb', line 246

def create_volume(availability_zone, options = {})
  raise ArgumentError.new('You must specify a size if not creating a volume from a snapshot') if options[:snapshot_id].blank? && options[:size].blank?

  action = 'CreateVolume'
  params = {
    'Action'           => action,
    'AvailabilityZone' => availability_zone
  }
  params['Size'] = options[:size] unless options[:size].blank?
  params['SnapshotId'] = options[:snapshot_id] unless options[:snapshot_id].blank?

  response = send_query_request(params)
  parser = Awsum::Ec2::VolumeParser.new(self)
  parser.parse(response.body)[0]
end

#delete_key_pair(key_name) ⇒ Object

Delete a KeyPair



521
522
523
524
525
526
527
528
529
530
 
# File 'lib/awsum/ec2.rb', line 521

def delete_key_pair(key_name)
  action = 'DeleteKeyPair'
  params = {
    'Action'  => action,
    'KeyName' => key_name
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#delete_security_group(group_name) ⇒ Object

Delete a SecurityGroup



564
565
566
567
568
569
570
571
572
573
 
# File 'lib/awsum/ec2.rb', line 564

def delete_security_group(group_name)
  action = 'DeleteSecurityGroup'
  params = {
    'Action'  => action,
    'GroupName' => group_name
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#delete_snapshot(snapshot_id) ⇒ Object

Delete a Snapshot



340
341
342
343
344
345
346
347
348
349
 
# File 'lib/awsum/ec2.rb', line 340

def delete_snapshot(snapshot_id)
  action = 'DeleteSnapshot'
  params = {
    'Action'     => action,
    'SnapshotId' => snapshot_id
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#delete_volume(volume_id) ⇒ Object

Delete a volume



297
298
299
300
301
302
303
304
305
306
 
# File 'lib/awsum/ec2.rb', line 297

def delete_volume(volume_id)
  action = 'DeleteVolume'
  params = {
    'Action'     => action,
    'VolumeId'   => volume_id
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#deregister_image(image_id) ⇒ Object

Deregister an Image. Once deregistered, you can no longer launch the Image



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/awsum/ec2.rb', line 111

def deregister_image(image_id)
  action = 'DeregisterImage'
  params = {
      'Action'  => action,
      'ImageId' => image_id
    }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#detach_volume(volume_id, options = {}) ⇒ Object

Detach a volume from an instance

Options

  • :instance_id - The ID of the instance from which the volume will detach

  • :device - The device name

  • :force - Whether to force the detachment. NOTE: If forced you may have data corruption issues.



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

def detach_volume(volume_id, options = {})
  action = 'DetachVolume'
  params = {
    'Action'     => action,
    'VolumeId'   => volume_id
  }
  params['InstanceId'] = options[:instance_id] unless options[:instance_id].blank?
  params['Device'] = options[:device] unless options[:device].blank?
  params['Force'] = options[:force] unless options[:force].blank?

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#disassociate_address(public_ip) ⇒ Object

Disassociate Address

Will disassociate an allocated elastic ip address from the Instance it’s allocated to

NOTE: You can run this command more than once and it will not return an error.



443
444
445
446
447
448
449
450
451
452
 
# File 'lib/awsum/ec2.rb', line 443

def disassociate_address(public_ip)
  action = 'DisassociateAddress'
  params = {
    'Action'     => action,
    'PublicIp'   => public_ip
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#host ⇒ Object

The host to make all requests against



733
734
735
 
# File 'lib/awsum/ec2.rb', line 733

def host
  @host ||= 'ec2.amazonaws.com'
end

#host=(host) ⇒ Object 



737
738
739
 
# File 'lib/awsum/ec2.rb', line 737

def host=(host)
  @host = host
end

#image(image_id) ⇒ Object

Retrieve a single Image



93
94
95
 
# File 'lib/awsum/ec2.rb', line 93

def image(image_id)
  images(:image_ids => [image_id])[0]
end

#images(options = {}) ⇒ Object

Retrieve a list of available Images

Options:

  • :image_ids - array of Image id’s, default: []

  • :owners - array of owner id’s, default: []

  • :executable_by - array of user id’s who have executable permission, default: []



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/awsum/ec2.rb', line 71

def images(options = {})
  options = {:image_ids => [], :owners => [], :executable_by => []}.merge(options)
  action = 'DescribeImages'
  params = {
      'Action' => action
    }
  #Add options
  params.merge!(array_to_params(options[:image_ids], "ImageId"))
  params.merge!(array_to_params(options[:owners], "Owner"))
  params.merge!(array_to_params(options[:executable_by], "ExecutableBy"))

  response = send_query_request(params)
  parser = Awsum::Ec2::ImageParser.new(self)
  parser.parse(response.body)
end

#instance(instance_id) ⇒ Object

Retrieve the information on a single Instance



181
182
183
 
# File 'lib/awsum/ec2.rb', line 181

def instance(instance_id)
  instances([instance_id])[0]
end

#instances(*instance_ids) ⇒ Object

Retrieve the information on a number of Instance(s)



168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/awsum/ec2.rb', line 168

def instances(*instance_ids)
  action = 'DescribeInstances'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(instance_ids, 'InstanceId'))

  response = send_query_request(params)
  parser = Awsum::Ec2::InstanceParser.new(self)
  parser.parse(response.body)
end

#key_pair(key_name) ⇒ Object

Get a single KeyPair



503
504
505
 
# File 'lib/awsum/ec2.rb', line 503

def key_pair(key_name)
  key_pairs(key_name)[0]
end

#key_pairs(*key_names) ⇒ Object

List KeyPair(s)



490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/awsum/ec2.rb', line 490

def key_pairs(*key_names)
  action = 'DescribeKeyPairs'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(key_names, 'KeyName'))

  response = send_query_request(params)
  parser = Awsum::Ec2::KeyPairParser.new(self)
  parser.parse(response.body)
end

#me ⇒ Object

Retrieves the currently running Instance This should only be run on a running EC2 instance



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

def me
  require 'open-uri'
  begin
    instance_id = open('http://169.254.169.254/latest/meta-data/instance-id').read
    instance instance_id
  rescue OpenURI::HTTPError => e
    nil
  end
end

#my_images ⇒ Object

Retrieve all Image(s) owned by you



88
89
90
 
# File 'lib/awsum/ec2.rb', line 88

def my_images
  images :owners => 'self'
end

#purchase_reserved_instances_offering(reserved_instances_offering_ids, instance_counts = 1) ⇒ Object

Purchase reserved instances

Options:

  • :reserved_instances_offering_ids - A single reserved instance offering id (or an array of instance ids)

  • :instance_counts - A number of reserved instances to purchase (or an array of counts per instance in the reserved_instances_offering_ids array)

Example

ec2.purchase_reserved_instances_offering('reservation-123456', 1)
or
ec2.purchase_reserved_instances_offering(['reservation-123456', 'reservation-654321'], [1, 2])



696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
 
# File 'lib/awsum/ec2.rb', line 696

def purchase_reserved_instances_offering(reserved_instances_offering_ids, instance_counts = 1)
  action = 'PurchaseReservedInstancesOffering'
  params = {
    'Action'        => action,
  }
  params.merge!(array_to_params([instance_counts].flatten, 'InstanceCount'))
  params.merge!(array_to_params([reserved_instances_offering_ids].flatten, 'ReservedInstancesOfferingId'))

  response = send_query_request(params)
  parser = Awsum::Ec2::PurchaseReservedInstancesOfferingParser.new(self)
  result = parser.parse(response.body)
  if reserved_instances_offering_ids.is_a?(Array)
    reserved_instances(*result)
  else
    reserved_instance(result)
  end
end

#region(region_name, &block) ⇒ Object

List a Region



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

def region(region_name, &block)
  region = regions(region_name)[0]
  if block_given?
    region.use(&block)
  else
    region
  end
end

#regions(*region_names) ⇒ Object

List all Region(s)



365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/awsum/ec2.rb', line 365

def regions(*region_names)
  action = 'DescribeRegions'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(region_names, 'RegionName'))

  response = send_query_request(params)
  parser = Awsum::Ec2::RegionParser.new(self)
  parser.parse(response.body)
end

#register_image(image_location) ⇒ Object

Register an Image



98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/awsum/ec2.rb', line 98

def register_image(image_location)
  action = 'RegisterImage'
  params = {
      'Action'        => action,
      'ImageLocation' => image_location
    }

  response = send_query_request(params)
  parser = Awsum::Ec2::RegisterImageParser.new(self)
  parser.parse(response.body)
end

#release_address(public_ip) ⇒ Object

Releases an associated Address

NOTE: This is not a direct call to the Amazon web service. This is a safe operation that will first check to see if the address is allocated to an instance and fail if it is To ensure an address is released whether associated or not, use #release_address!



458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/awsum/ec2.rb', line 458

def release_address(public_ip)
  address = address(public_ip)

  if address.instance_id.nil?
    action = 'ReleaseAddress'
    params = {
      'Action'   => action,
      'PublicIp' => public_ip
    }

    response = send_query_request(params)
    response.is_a?(Net::HTTPSuccess)
  else
    raise 'Address is currently allocated' #FIXME: Add a proper Awsum error here
  end
end

#release_address!(public_ip) ⇒ Object

Releases an associated Address

NOTE: This will disassociate an address automatically if it is associated with an instance



478
479
480
481
482
483
484
485
486
487
 
# File 'lib/awsum/ec2.rb', line 478

def release_address!(public_ip)
  action = 'ReleaseAddress'
  params = {
    'Action'   => action,
    'PublicIp' => public_ip
  }

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#reserved_instance(reserved_instance_id) ⇒ Object

Retrieve a single reserved instance by id



727
728
729
 
# File 'lib/awsum/ec2.rb', line 727

def reserved_instance(reserved_instance_id)
  reserved_instances(reserved_instance_id)[0]
end

#reserved_instances(*reserved_instances_ids) ⇒ Object 



714
715
716
717
718
719
720
721
722
723
724
 
# File 'lib/awsum/ec2.rb', line 714

def reserved_instances(*reserved_instances_ids)
  action = 'DescribeReservedInstances'
  params = {
    'Action'        => action
  }
  params.merge!(array_to_params(reserved_instances_ids, 'ReservedInstanceId'))

  response = send_query_request(params)
  parser = Awsum::Ec2::ReservedInstanceParser.new(self)
  parser.parse(response.body)
end

#reserved_instances_offering(id) ⇒ Object

Get a single reserved instances offering by id



682
683
684
 
# File 'lib/awsum/ec2.rb', line 682

def reserved_instances_offering(id)
  reserved_instances_offerings(:reserved_instances_offering_ids => id)[0]
end

#reserved_instances_offerings(options = {}) ⇒ Object

List all reserved instance offerings that are available for purchase

Options:

  • :reserved_instances_offering_ids - Display the reserved instance offerings with the specified ids. Can be an individual id or an array of ids

  • :instance_type - Display available reserved instance offerings of the specific instance type, can be one of [m1.small, m1.large, m1.xlarge, c1.medium, c1.xlarge], default is all

  • :availability_zone - Display the reserved instance offerings within the specified availability zone

  • :product_description - Display the reserved instance offerings with the specified product description

Example

#To get all offerings for m1.small instances in availability zone us-east-1a
ec2.reserved_instances_offerings(:instance_type => 'm1.small', :availability_zone => 'us-east-1a')



666
667
668
669
670
671
672
673
674
675
676
677
678
679
 
# File 'lib/awsum/ec2.rb', line 666

def reserved_instances_offerings(options = {})
  action = 'DescribeReservedInstancesOfferings'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(options[:reserved_instances_offering_ids], 'ReservedInstancesOfferingId')) if options[:reserved_instances_offering_ids]
  params['InstanceType'] = options[:instance_type] if options[:instance_type]
  params['AvailabilityZone'] = options[:availability_zone] if options[:availability_zone]
  params['ProductDescription'] = options[:product_description] if options[:product_description]

  response = send_query_request(params)
  parser = Awsum::Ec2::ReservedInstancesOfferingParser.new(self)
  parser.parse(response.body)
end

#revoke_security_group_ingress(group_name, options = {}) ⇒ Object

Revoke access on a specific SecurityGroup

Options:

User/Group access

  • :source_security_group_name - Name of the security group to authorize access to when operating on a user/group pair

  • :source_security_group_owner_id - Owner of the security group to authorize access to when operating on a user/group pair

CIDR IP access

  • :ip_protocol - IP protocol to authorize access to when operating on a CIDR IP (tcp, udp or icmp) (default: tcp)

  • :from_port - Bottom of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.

  • :to_port - Top of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.

  • :cidr_ip - CIDR IP range to authorize access to when operating on a CIDR IP. (default: 0.0.0.0/0)

Raises:

  • (ArgumentError) 


626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
 
# File 'lib/awsum/ec2.rb', line 626

def revoke_security_group_ingress(group_name, options = {})
  got_at_least_one_user_group_option = !options[:source_security_group_name].nil? || !options[:source_security_group_owner_id].nil?
  got_user_group_options = !options[:source_security_group_name].nil? && !options[:source_security_group_owner_id].nil?
  got_at_least_one_cidr_option = !options[:ip_protocol].nil? || !options[:from_port].nil? || !options[:to_port].nil? || !options[:cidr_ip].nil?
  #Add in defaults
  options = {:cidr_ip => '0.0.0.0/0'}.merge(options) if got_at_least_one_cidr_option
  options = {:ip_protocol => 'tcp'}.merge(options) if got_at_least_one_cidr_option
  got_cidr_options = !options[:ip_protocol].nil? && !options[:from_port].nil? && !options[:to_port].nil? && !options[:cidr_ip].nil?
  raise ArgumentError.new('Can only authorize user/group or CIDR IP, not both') if got_at_least_one_user_group_option && got_at_least_one_cidr_option
  raise ArgumentError.new('Need all user/group options when revoking user/group access') if got_at_least_one_user_group_option && !got_user_group_options
  raise ArgumentError.new('Need all CIDR IP options when revoking CIDR IP access') if got_at_least_one_cidr_option && !got_cidr_options
  raise ArgumentError.new('ip_protocol can only be one of tcp, udp or icmp') if got_at_least_one_cidr_option && !%w(tcp udp icmp).detect{|p| p == options[:ip_protocol] }

  action = 'RevokeSecurityGroupIngress'
  params = {
    'Action'    => action,
    'GroupName' => group_name
  }
  params['SourceSecurityGroupName'] = options[:source_security_group_name] unless options[:source_security_group_name].nil?
  params['SourceSecurityGroupOwnerId'] = options[:source_security_group_owner_id] unless options[:source_security_group_owner_id].nil?
  params['IpProtocol'] = options[:ip_protocol] unless options[:ip_protocol].nil?
  params['FromPort'] = options[:from_port] unless options[:from_port].nil?
  params['ToPort'] = options[:to_port] unless options[:to_port].nil?
  params['CidrIp'] = options[:cidr_ip] unless options[:cidr_ip].nil?

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#run_instances(image_id, options = {}) ⇒ Object Also known as: launch_instances

Launch an ec2 Instance

Options:

  • :min - The minimum number of instances to launch. Default: 1

  • :max - The maximum number of instances to launch. Default: 1

  • :key_name - The name of the key pair with which to launch instances

  • :security_groups - The names of security groups to associate launched instances with

  • :user_data - User data made available to instances (Note: Must be 16K or less, will be base64 encoded by Awsum)

  • :instance_type - The size of the instances to launch, can be one of [m1.small, m1.large, m1.xlarge, c1.medium, c1.xlarge], default is m1.small

  • :availability_zone - The name of the availability zone to launch this Instance in

  • :kernel_id - The ID of the kernel with which to launch instances

  • :ramdisk_id - The ID of the RAM disk with which to launch instances

  • :block_device_map - A ‘hash’ of mappings. E.g. => ‘sdb’



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/awsum/ec2.rb', line 135

def run_instances(image_id, options = {})
  options = {:min => 1, :max => 1}.merge(options)
  action = 'RunInstances'
  params = {
    'Action'                     => action,
    'ImageId'                    => image_id,
    'MinCount'                   => options[:min],
    'MaxCount'                   => options[:max],
    'KeyName'                    => options[:key_name],
    'UserData'                   => options[:user_data].nil? ? nil : Base64::encode64(options[:user_data]).gsub(/\n/, ''),
    'InstanceType'               => options[:instance_type],
    'Placement.AvailabilityZone' => options[:availability_zone],
    'KernelId'                   => options[:kernel_id],
    'RamdiskId'                  => options[:ramdisk_id]
  }
  if options[:block_device_map].respond_to?(:keys)
    map = options[:block_device_map]
    map.keys.each_with_index do |key, i|
      params["BlockDeviceMapping.#{i+1}.VirtualName"] = key
      params["BlockDeviceMapping.#{i+1}.DeviceName"] = map[key]
    end
  else
    raise ArgumentError.new("options[:block_device_map] - must be a key => value map") unless options[:block_device_map].nil?
  end
  params.merge!(array_to_params(options[:security_groups], "SecurityGroup"))

  response = send_query_request(params)
  parser = Awsum::Ec2::InstanceParser.new(self)
  parser.parse(response.body)
end

#security_group(group_name) ⇒ Object

Get a single SecurityGroup



546
547
548
 
# File 'lib/awsum/ec2.rb', line 546

def security_group(group_name)
  security_groups(group_name)[0]
end

#security_groups(*group_names) ⇒ Object

List SecurityGroup(s)



533
534
535
536
537
538
539
540
541
542
543
 
# File 'lib/awsum/ec2.rb', line 533

def security_groups(*group_names)
  action = 'DescribeSecurityGroups'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(group_names, 'GroupName'))

  response = send_query_request(params)
  parser = Awsum::Ec2::SecurityGroupParser.new(self)
  parser.parse(response.body)
end

#snapshot(snapshot_id) ⇒ Object

Get the information about a Snapshot



335
336
337
 
# File 'lib/awsum/ec2.rb', line 335

def snapshot(snapshot_id)
  snapshots(snapshot_id)[0]
end

#snapshots(*snapshot_ids) ⇒ Object

List Snapshot(s)



322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/awsum/ec2.rb', line 322

def snapshots(*snapshot_ids)
  action = 'DescribeSnapshots'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(snapshot_ids, 'SnapshotId'))

  response = send_query_request(params)
  parser = Awsum::Ec2::SnapshotParser.new(self)
  parser.parse(response.body)
end

#terminate_instances(*instance_ids) ⇒ Object

Terminates the Instance(s)

Returns true if the terminations succeeds, false otherwise



211
212
213
214
215
216
217
218
219
220
 
# File 'lib/awsum/ec2.rb', line 211

def terminate_instances(*instance_ids)
  action = 'TerminateInstances'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(instance_ids, 'InstanceId'))

  response = send_query_request(params)
  response.is_a?(Net::HTTPSuccess)
end

#user_data ⇒ Object

Retreives the user-data supplied when starting the currently running Instance This should only be run on a running EC2 instance



199
200
201
202
203
204
205
206
 
# File 'lib/awsum/ec2.rb', line 199

def user_data
  require 'open-uri'
  begin
    open('http://169.254.169.254/latest/user-data').read
  rescue OpenURI::HTTPError => e
    nil
  end
end

#volume(volume_id) ⇒ Object

Retreive information on a Volume



236
237
238
 
# File 'lib/awsum/ec2.rb', line 236

def volume(volume_id)
  volumes(volume_id)[0]
end

#volumes(*volume_ids) ⇒ Object

Retrieve the information on a number of Volume(s)



223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/awsum/ec2.rb', line 223

def volumes(*volume_ids)
  action = 'DescribeVolumes'
  params = {
    'Action' => action
  }
  params.merge!(array_to_params(volume_ids, 'VolumeId'))

  response = send_query_request(params)
  parser = Awsum::Ec2::VolumeParser.new(self)
  parser.parse(response.body)
end