Class: EC2::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/EC2.rb,
lib/EC2/images.rb,
lib/EC2/console.rb,
lib/EC2/volumes.rb,
lib/EC2/keypairs.rb,
lib/EC2/products.rb,
lib/EC2/instances.rb,
lib/EC2/snapshots.rb,
lib/EC2/elastic_ips.rb,
lib/EC2/security_groups.rb,
lib/EC2/image_attributes.rb,
lib/EC2/availability_zones.rb

Overview

Introduction:

The library exposes one main interface class, ‘EC2::Base’. This class provides all the methods for using the EC2 service including the handling of header signing and other security issues . This class uses Net::HTTP to interface with the EC2 Query API interface.

Required Arguments:

:access_key_id => String (default : “”) :secret_access_key => String (default : “”)

Optional Arguments:

:use_ssl => Boolean (default : true) :server => String (default : ‘ec2.amazonaws.com’) :proxy_server => String (default : nil)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Base

Returns a new instance of Base.

Raises:



79
80
81
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
125
 
# File 'lib/EC2.rb', line 79

def initialize( options = {} )

  options = { :access_key_id => "",
              :secret_access_key => "",
              :use_ssl => true,
              :server => DEFAULT_HOST,
              :proxy_server => nil
              }.merge(options)

  @server = options[:server]
  @proxy_server = options[:proxy_server]
  @use_ssl = options[:use_ssl]

  raise ArgumentError, "No :access_key_id provided" if options[:access_key_id].nil? || options[:access_key_id].empty?
  raise ArgumentError, "No :secret_access_key provided" if options[:secret_access_key].nil? || options[:secret_access_key].empty?
  raise ArgumentError, "No :use_ssl value provided" if options[:use_ssl].nil?
  raise ArgumentError, "Invalid :use_ssl value provided, only 'true' or 'false' allowed" unless options[:use_ssl] == true || options[:use_ssl] == false
  raise ArgumentError, "No :server provided" if options[:server].nil? || options[:server].empty?


  # based on the :use_ssl boolean, determine which port we should connect to
  case @use_ssl
  when true
    # https
    @port = 443
  when false
    # http
    @port = 80
  end

  @access_key_id = options[:access_key_id]
  @secret_access_key = options[:secret_access_key]

  # Use proxy server if defined
  # Based on patch by Mathias Dalheimer.  20070217
  proxy = @proxy_server ? URI.parse(@proxy_server) : OpenStruct.new
  @http = Net::HTTP::Proxy( proxy.host,
                            proxy.port,
                            proxy.user,
                            proxy.password).new(options[:server], @port)

  @http.use_ssl = @use_ssl

  # Don't verify the SSL certificates.  Avoids SSL Cert warning in log on every GET.
  @http.verify_mode = OpenSSL::SSL::VERIFY_NONE

end

Instance Attribute Details

#port ⇒ Object (readonly)

Returns the value of attribute port.



77
78
79
 
# File 'lib/EC2.rb', line 77

def port
  @port
end

#proxy_server ⇒ Object (readonly)

Returns the value of attribute proxy_server.



77
78
79
 
# File 'lib/EC2.rb', line 77

def proxy_server
  @proxy_server
end

#server ⇒ Object (readonly)

Returns the value of attribute server.



77
78
79
 
# File 'lib/EC2.rb', line 77

def server
  @server
end

#use_ssl ⇒ Object (readonly)

Returns the value of attribute use_ssl.



77
78
79
 
# File 'lib/EC2.rb', line 77

def use_ssl
  @use_ssl
end

Instance Method Details

#allocate_address ⇒ Object

Amazon Developer Guide Docs:

The AllocateAddress operation acquires an elastic IP address for use with your account.

Required Arguments:

none

Optional Arguments:

none



28
29
30
31
32
 
# File 'lib/EC2/elastic_ips.rb', line 28

def allocate_address

  return response_generator(:action => "AllocateAddress")

end

#associate_address(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The AssociateAddress operation associates an elastic IP address with an instance.

If the IP address is currently assigned to another instance, the IP address is assigned to the new instance. This is an idempotent operation. If you enter it more than once, Amazon EC2 does not return an error.

Required Arguments:

:instance_id => String (default : ”) :public_ip => String (default : ”)

Optional Arguments:

none

Raises:



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/EC2/elastic_ips.rb', line 108

def associate_address( options = {} )

  options = { :instance_id => '', :public_ip => '' }.merge(options)

  raise ArgumentError, "No ':instance_id' provided" if options[:instance_id].nil? || options[:instance_id].empty?
  raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?

  params = {
    "InstanceId" => options[:instance_id],
    "PublicIp" => options[:public_ip]
  }

  return response_generator(:action => "AssociateAddress", :params => params)

end

#attach_volumes(options = {}) ⇒ Object

Raises:



12
13
14
15
16
17
18
19
 
# File 'lib/EC2/volumes.rb', line 12

def attach_volumes( options = {} )
  options = { :volume_id => '', :instance_id => '' }.merge(options)
  raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:volume_id].empty?
  raise ArgumentError, "No ':instance_id' provided" if options[:instance_id].nil? || options[:instance_id].empty?

  params = { "VolumeId" => options[:volume_id], "InstanceId" => options[:instance_id] }
  return response_generator(:action => "AttachVolume", :params => params)
end

#authorize_security_group_ingress(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The AuthorizeSecurityGroupIngress operation adds permissions to a security group.

Permissions are specified in terms of the IP protocol (TCP, UDP or ICMP), the source of the request (by IP range or an Amazon EC2 user-group pair), source and destination port ranges (for TCP and UDP), and ICMP codes and types (for ICMP). When authorizing ICMP, -1 may be used as a wildcard in the type and code fields.

Permission changes are propagated to instances within the security group being modified as quickly as possible. However, a small delay is likely, depending on the number of instances that are members of the indicated group.

When authorizing a user/group pair permission, GroupName, SourceSecurityGroupName and SourceSecurityGroupOwnerId must be specified. When authorizing a CIDR IP permission, GroupName, IpProtocol, FromPort, ToPort and CidrIp must be specified. Mixing these two types of parameters is not allowed.

Required Arguments:

:group_name => String (default : “”)

Optional Arguments:

:ip_protocol => String (default : nil) : Required when authorizing CIDR IP permission :from_port => Integer (default : nil) : Required when authorizing CIDR IP permission :to_port => Integer (default : nil) : Required when authorizing CIDR IP permission :cidr_ip => String (default : nil): Required when authorizing CIDR IP permission :source_security_group_name => String (default : nil) : Required when authorizing user group pair permissions :source_security_group_owner_id => String (default : nil) : Required when authorizing user group pair permissions

Raises:



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
165
166
 
# File 'lib/EC2/security_groups.rb', line 140

def authorize_security_group_ingress( options = {} )

  # defaults
  options = { :group_name => nil,
              :ip_protocol => nil,
              :from_port => nil,
              :to_port => nil,
              :cidr_ip => nil,
              :source_security_group_name => nil,
              :source_security_group_owner_id => nil }.merge(options)

  # lets not validate the rest of the possible permutations of required params and instead let
  # EC2 sort it out on the server side.  We'll only require :group_name as that is always needed.
  raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?

  params = { "GroupName" => options[:group_name],
             "IpProtocol" => options[:ip_protocol],
             "FromPort" => options[:from_port].to_s,
             "ToPort" => options[:to_port].to_s,
             "CidrIp" => options[:cidr_ip],
             "SourceSecurityGroupName" => options[:source_security_group_name],
             "SourceSecurityGroupOwnerId" => options[:source_security_group_owner_id]
             }

  return response_generator(:action => "AuthorizeSecurityGroupIngress", :params => params)

end

#confirm_product_instance(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The ConfirmProductInstance operation returns true if the given product code is attached to the instance with the given instance id. False is returned if the product code is not attached to the instance.

Required Arguments:

:product_code => String (default : “”) :instance_id => String (default : “”)

Optional Arguments:

none

Raises:



29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/EC2/products.rb', line 29

def confirm_product_instance( options ={} )

  options = {:product_code => "", :instance_id => ""}.merge(options)

  raise ArgumentError, "No product code provided" if options[:product_code].nil? || options[:product_code].empty?
  raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?

  params = { "ProductCode" => options[:product_code], "InstanceId" => options[:instance_id] }

  return response_generator(:action => "ConfirmProductInstance", :params => params)

end

#create_keypair(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The CreateKeyPair operation creates a new 2048 bit RSA keypair and returns a unique ID that can be used to reference this keypair when launching new instances.

Required Arguments:

:key_name => String (default : “”)

Optional Arguments:

none

Raises:



29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/EC2/keypairs.rb', line 29

def create_keypair( options = {} )

  # defaults
  options = { :key_name => "" }.merge(options)

  raise ArgumentError, "No :key_name provided" if options[:key_name].nil? || options[:key_name].empty?

  params = { "KeyName" => options[:key_name] }

  return response_generator(:action => "CreateKeyPair", :params => params)

end

#create_security_group(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The CreateSecurityGroup operation creates a new security group. Every instance is launched in a security group. If none is specified as part of the launch request then instances are launched in the default security group. Instances within the same security group have unrestricted network access to one another. Instances will reject network access attempts from other instances in a different security group. As the owner of instances you may grant or revoke specific permissions using the AuthorizeSecurityGroupIngress and RevokeSecurityGroupIngress operations.

Required Arguments:

:group_name => String (default : “”) :group_description => String (default : “”)

Optional Arguments:

none

Raises:



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/EC2/security_groups.rb', line 34

def create_security_group( options = {} )

  options = {:group_name => "",
             :group_description => ""
             }.merge(options)

  raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?
  raise ArgumentError, "No :group_description provided" if options[:group_description].nil? || options[:group_description].empty?

  params = {
    "GroupName" => options[:group_name],
    "GroupDescription" => options[:group_description]
  }

  return response_generator(:action => "CreateSecurityGroup", :params => params)

end

#create_snapshot(options = {}) ⇒ Object

Raises:



4
5
6
7
8
9
10
 
# File 'lib/EC2/snapshots.rb', line 4

def create_snapshot( options = {} )
  options = { :volume_id => '' }.merge(options)
  raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:volume_id].empty?

  params = { "VolumeId" => options[:volume_id] }
  return response_generator(:action => "CreateSnapshot", :params => params)      
end

#delete_keypair(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DeleteKeyPair operation deletes a keypair.

Required Arguments:

:key_name => String (default : “”)

Optional Arguments:

none

Raises:



80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/EC2/keypairs.rb', line 80

def delete_keypair( options = {} )

  options = { :key_name => "" }.merge(options)

  raise ArgumentError, "No :key_name provided" if options[:key_name].nil? || options[:key_name].empty?

  params = { "KeyName" => options[:key_name] }

  return response_generator(:action => "DeleteKeyPair", :params => params)

end

#delete_security_group(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DeleteSecurityGroup operation deletes a security group.

If an attempt is made to delete a security group and any instances exist that are members of that group a fault is returned.

Required Arguments:

:group_name => String (default : “”)

Optional Arguments:

none

Raises:



96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/EC2/security_groups.rb', line 96

def delete_security_group( options = {} )

  options = { :group_name => "" }.merge(options)

  raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?

  params = { "GroupName" => options[:group_name] }

  return response_generator(:action => "DeleteSecurityGroup", :params => params)

end

#delete_snapshot(options = {}) ⇒ Object

Raises:



19
20
21
22
23
24
25
 
# File 'lib/EC2/snapshots.rb', line 19

def delete_snapshot( options = {} )
  options = { :snapshot_id => '' }.merge(options)
  raise ArgumentError, "No ':snapshot_id' provided" if options[:snapshot_id].nil? || options[:snapshot_id].empty?

  params = { "SnapshotId" => options[:snapshot_id] }
  return response_generator(:action => "DeleteSnapshot", :params => params)      
end

#delete_volume(options = {}) ⇒ Object

Raises:



21
22
23
24
25
26
27
 
# File 'lib/EC2/volumes.rb', line 21

def delete_volume( options = {} )
  options = { :volume_id => '' }.merge(options)
  raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:v].empty?

  params = { "VolumeId" => options[:volume_id] }
  return response_generator(:action => "DeleteVolume", :params => params)      
end

#deregister_image(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DeregisterImage operation deregisters an AMI. Once deregistered, instances of the AMI may no longer be launched.

Required Arguments:

:image_id => String (default : “”)

Optional Arguments:

none

Raises:



119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/EC2/images.rb', line 119

def deregister_image( options = {} )

  # defaults
  options = { :image_id => "" }.merge(options)

  raise ArgumentError, "No :image_id provided" if options[:image_id].nil? || options[:image_id].empty?

  params = { "ImageId" => options[:image_id] }

  return response_generator(:action => "DeregisterImage", :params => params)

end

#describe_addresses(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DescribeAddresses operation lists elastic IP addresses assigned to your account.

Required Arguments:

:public_ip => Array (default : [], can be empty)

Optional Arguments:

none



46
47
48
49
50
51
52
53
54
 
# File 'lib/EC2/elastic_ips.rb', line 46

def describe_addresses( options = {} )

  options = { :public_ip => [] }.merge(options)

  params = pathlist("PublicIp", options[:public_ip])

  return response_generator(:action => "DescribeAddresses", :params => params)

end

#describe_availability_zones(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DescribeAvailabilityZones operation describes availability zones that are currently available to the account and their states.

An optional list of zone names can be passed.

Required Arguments:

none

Optional Arguments:

:zone_name => Array (default : [])



31
32
33
34
35
36
37
38
39
 
# File 'lib/EC2/availability_zones.rb', line 31

def describe_availability_zones( options = {} )

  options = { :zone_name => [] }.merge(options)

  params = pathlist("ZoneName", options[:zone_name] )

  return response_generator(:action => "DescribeAvailabilityZones", :params => params)

end

#describe_image_attribute(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DescribeImageAttribute operation returns information about an attribute of an AMI.

Required Arguments:

:image_id => String (default : “”) :attribute => String (“launchPermission” or “productCodes”, default : “launchPermission”)

Optional Arguments:

none

Raises:



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/image_attributes.rb', line 102

def describe_image_attribute( options = {} )

  # defaults
  options = {:image_id => "",
             :attribute => "launchPermission"
             }.merge(options)

  raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
  raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?

  params = { "ImageId" => options[:image_id], "Attribute" => options[:attribute] }

  # test options provided and make sure they are valid
  case options[:attribute]
  when "launchPermission", "productCodes"
    # these args are ok
  else
    raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known attribute."
  end

  return response_generator(:action => "DescribeImageAttribute", :params => params)

end

#describe_images(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DescribeImages operation returns information about AMIs available for use by the user. This includes both public AMIs (those available for any user to launch) and private AMIs (those owned by the user making the request and those owned by other users that the user making the request has explicit launch permissions for).

The list of AMIs returned can be modified via optional lists of AMI IDs, owners or users with launch permissions. If all three optional lists are empty all AMIs the user has launch permissions for are returned. Launch permissions fall into three categories:

Launch Permission Description

public - The all group has launch permissions for the AMI. All users have launch permissions for these AMIs. explicit - The owner of the AMIs has granted a specific user launch permissions for the AMI. implicit - A user has implicit launch permissions for all AMIs he or she owns.

If one or more of the lists are specified the result set is the intersection of AMIs matching the criteria of the individual lists.

Providing the list of AMI IDs requests information for those AMIs only. If no AMI IDs are provided, information of all relevant AMIs will be returned. If an AMI is specified that does not exist a fault is returned. If an AMI is specified that exists but the user making the request does not have launch permissions for, then that AMI will not be included in the returned results.

Providing the list of owners requests information for AMIs owned by the specified owners only. Only AMIs the user has launch permissions for are returned. The items of the list may be account ids for AMIs owned by users with those account ids, amazon for AMIs owned by Amazon or self for AMIs owned by the user making the request.

The executable list may be provided to request information for AMIs that only the specified users have launch permissions for. The items of the list may be account ids for AMIs owned by the user making the request that the users with the specified account ids have explicit launch permissions for, self for AMIs the user making the request has explicit launch permissions for or all for public AMIs.

Deregistered images will be included in the returned results for an unspecified interval subsequent to deregistration.

Required Arguments:

none

Optional Arguments:

:image_id => Array (default : []) :owner_id => Array (default : []) :executable_by => Array (default : [])



94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/EC2/images.rb', line 94

def describe_images( options = {} )

  options = { :image_id => [], :owner_id => [], :executable_by => [] }.merge(options)

  params = pathlist( "ImageId", options[:image_id] )
  params.merge!(pathlist( "Owner", options[:owner_id] ))
  params.merge!(pathlist( "ExecutableBy", options[:executable_by] ))

  return response_generator(:action => "DescribeImages", :params => params)

end

#describe_instances(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DescribeInstances operation returns information about instances owned by the user making the request.

An optional list of instance IDs may be provided to request information for those instances only. If no instance IDs are provided, information of all relevant instances information will be returned. If an instance is specified that does not exist a fault is returned. If an instance is specified that exists but is not owned by the user making the request, then that instance will not be included in the returned results.

Recently terminated instances will be included in the returned results for a small interval subsequent to their termination. This interval is typically of the order of one hour

Required Arguments:

none

Optional Arguments:

:instance_id => Array (default : [])



142
143
144
145
146
147
148
149
150
 
# File 'lib/EC2/instances.rb', line 142

def describe_instances( options = {} )

  options = { :instance_id => [] }.merge(options)

  params = pathlist("InstanceId", options[:instance_id])

  return response_generator(:action => "DescribeInstances", :params => params)

end

#describe_keypairs(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DescribeKeyPairs operation returns information about keypairs available for use by the user making the request. Selected keypairs may be specified or the list may be left empty if information for all registered keypairs is required.

Required Arguments:

:key_name => Array (default : [])

Optional Arguments:

none



57
58
59
60
61
62
63
64
65
 
# File 'lib/EC2/keypairs.rb', line 57

def describe_keypairs( options = {} )

  options = { :key_name => [] }.merge(options)

  params = pathlist("KeyName", options[:key_name] )

  return response_generator(:action => "DescribeKeyPairs", :params => params)

end

#describe_security_groups(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DescribeSecurityGroups operation returns information about security groups owned by the user making the request.

An optional list of security group names may be provided to request information for those security groups only. If no security group names are provided, information of all security groups will be returned. If a group is specified that does not exist a fault is returned.

Required Arguments:

none

Optional Arguments:

:group_name => Array (default : [])



70
71
72
73
74
75
76
77
78
 
# File 'lib/EC2/security_groups.rb', line 70

def describe_security_groups( options = {} )

  options = { :group_name => [] }.merge(options)

  params = pathlist("GroupName", options[:group_name] )

  return response_generator(:action => "DescribeSecurityGroups", :params => params)

end

#describe_snapshots(options = {}) ⇒ Object 



12
13
14
15
16
17
 
# File 'lib/EC2/snapshots.rb', line 12

def describe_snapshots( options = {} )
  options = { :snapshot_id => [] }.merge(options)
  params = pathlist("SnapshotId", options[:snapshot_id])

  return response_generator(:action => "DescribeSnapshots", :params => params)
end

#describe_volumes(options = {}) ⇒ Object 



5
6
7
8
9
10
 
# File 'lib/EC2/volumes.rb', line 5

def describe_volumes( options = {} )
  options = { :volume_id => [] }.merge(options)
  params = pathlist("VolumeId", options[:volume_id])

  return response_generator(:action => "DescribeVolumes", :params => params)
end

#detach_volumes(options = {}) ⇒ Object

Raises:



29
30
31
32
33
34
35
 
# File 'lib/EC2/volumes.rb', line 29

def detach_volumes( options = {} )
  options = { :volume_id => '', :instance_id => '', :device => '', :force => false }.merge(options)
  raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:volume_id].empty?

  params = { "VolumeId" => options[:volume_id], "InstanceId" => options[:instance_id], 'Device' => options[:device], 'Force' => options[:force] }
  return response_generator(:action => "DetachVolume", :params => params)
end

#disassociate_address(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The DisassociateAddress operation disassociates the specified elastic IP address from the instance to which it is assigned. This is an idempotent operation. If you enter it more than once, Amazon EC2 does not return an error.

Required Arguments:

:public_ip => String (default : ”)

Optional Arguments:

none

Raises:



139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/EC2/elastic_ips.rb', line 139

def disassociate_address( options = {} )

  options = { :public_ip => '' }.merge(options)

  raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?

  params = { "PublicIp" => options[:public_ip] }

  return response_generator(:action => "DisassociateAddress", :params => params)

end

#get_console_output(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The GetConsoleOutput operation retrieves console output that has been posted for the specified instance.

Instance console output is buffered and posted shortly after instance boot, reboot and once the instance is terminated. Only the most recent 64 KB of posted output is available. Console output is available for at least 1 hour after the most recent post.

Required Arguments:

:instance_id => String (default : “”)

Optional Arguments:

none

Raises:



31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/EC2/console.rb', line 31

def get_console_output( options ={} )

  options = {:instance_id => ""}.merge(options)

  raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?

  params = { "InstanceId" => options[:instance_id] }

  return response_generator(:action => "GetConsoleOutput", :params => params)

end

#modify_image_attribute(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The ModifyImageAttribute operation modifies an attribute of an AMI. The following attributes may currently be modified:

‘launchPermission’ : Controls who has permission to launch the AMI. Launch permissions can be granted to specific users by adding userIds. The AMI can be made public by adding the ‘all’ group.

‘productCodes’ : Associates product codes with AMIs. This allows a developer to charge a user extra for using the AMIs. productCodes is a write once attribute - once it has been set it can not be changed or removed. Currently only one product code is supported per AMI.

Required Arguments:

:image_id => String (default : “”) :attribute => String (‘launchPermission’ or ‘productCodes’, default : “launchPermission”) :operation_type => String (default : “”)

Optional Arguments:

:user_id => Array (default : []) :group => Array (default : []) :product_code => Array (default : [])

Raises:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/EC2/image_attributes.rb', line 39

def modify_image_attribute( options = {} )

  # defaults
  options = { :image_id => "",
              :attribute => "launchPermission",
              :operation_type => "",
              :user_id => [],
              :group => [],
              :product_code => [] }.merge(options)

  raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
  raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?

  # OperationType is not required if modifying a product code.
  unless options[:attribute] == 'productCodes'
    raise ArgumentError, "No ':operation_type' provided" if options[:operation_type].nil? || options[:operation_type].empty?
  end

  params = {
    "ImageId" => options[:image_id],
    "Attribute" => options[:attribute],
    "OperationType" => options[:operation_type]
  }

  # test options provided and make sure they are valid
  case options[:attribute]
  when "launchPermission"

    unless options[:operation_type] == "add" || options[:operation_type] == "remove"
      raise ArgumentError, ":operation_type was #{options[:operation_type].to_s} but must be either 'add' or 'remove'"
    end

    if (options[:user_id].nil? || options[:user_id].empty?) && (options[:group].nil? || options[:group].empty?)
      raise ArgumentError, "Option :attribute=>'launchPermission' requires ':user_id' or ':group' options to also be specified"
    end
    params.merge!(pathlist("UserId", options[:user_id])) unless options[:user_id].nil?
    params.merge!(pathlist("Group", options[:group])) unless options[:group].nil?
  when "productCodes"
    if (options[:product_code].nil? || options[:product_code].empty?)
      raise ArgumentError, "Option :attribute=>'productCodes' requires ':product_code' to be specified"
    end
    params.merge!(pathlist("ProductCode", options[:product_code])) unless options[:product_code].nil?
  else
    raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known attribute."
  end

  return response_generator(:action => "ModifyImageAttribute", :params => params)

end

#reboot_instances(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The RebootInstances operation requests a reboot of one or more instances. This operation is asynchronous; it only queues a request to reboot the specified instance(s). The operation will succeed provided the instances are valid and belong to the user. Terminated instances will be ignored.

Required Arguments:

:instance_id => Array (default : [])

Optional Arguments:

none

Raises:



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

def reboot_instances( options = {} )

  # defaults
  options = { :instance_id => [] }.merge(options)

  raise ArgumentError, "No instance IDs provided" if options[:instance_id].nil? || options[:instance_id].empty?

  params = pathlist("InstanceId", options[:instance_id])

  return response_generator(:action => "RebootInstances", :params => params)

end

#register_image(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The RegisterImage operation registers an AMI with Amazon EC2. Images must be registered before they can be launched. Each AMI is associated with an unique ID which is provided by the EC2 service via the Registerimage operation. As part of the registration process, Amazon EC2 will retrieve the specified image manifest from Amazon S3 and verify that the image is owned by the user requesting image registration. The image manifest is retrieved once and stored within the Amazon EC2 network. Any modifications to an image in Amazon S3 invalidate this registration. If you do have to make changes and upload a new image deregister the previous image and register the new image.

Required Arguments:

:image_location => String (default : “”)

Optional Arguments:

none

Raises:



34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/EC2/images.rb', line 34

def register_image( options = {} )

  options = {:image_location => ""}.merge(options)

  raise ArgumentError, "No :image_location provided" if options[:image_location].nil? || options[:image_location].empty?

  params = { "ImageLocation" => options[:image_location] }

  return response_generator(:action => "RegisterImage", :params => params)

end

#release_address(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The ReleaseAddress operation releases an elastic IP address associated with your account.

If you run this operation on an elastic IP address that is already released, the address might be assigned to another account which will cause Amazon EC2 to return an error.

Note : Releasing an IP address automatically disassociates it from any instance with which it is associated. For more information, see DisassociateAddress.

Important! After releasing an elastic IP address, it is released to the IP address pool and might no longer be available to your account. Make sure to update your DNS records and any servers or devices that communicate with the address.

Required Arguments:

:public_ip => String (default : ”)

Optional Arguments:

none

Raises:



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/EC2/elastic_ips.rb', line 79

def release_address( options = {} )

  options = { :public_ip => '' }.merge(options)

  raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?

  params = { "PublicIp" => options[:public_ip] }

  return response_generator(:action => "ReleaseAddress", :params => params)

end

#reset_image_attribute(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The ResetImageAttribute operation resets an attribute of an AMI to its default value.

Required Arguments:

:image_id => String (default : “”) :attribute => String (default : “launchPermission”)

Optional Arguments:

none

Raises:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/EC2/image_attributes.rb', line 140

def reset_image_attribute( options = {} )

  # defaults
  options = {:image_id => "",
             :attribute => "launchPermission"}.merge(options)

  raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
  raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?

  params = {"ImageId" => options[:image_id],
            "Attribute" => options[:attribute] }

  # test options provided and make sure they are valid
  case options[:attribute]
  when "launchPermission"
    # these args are ok
  else
    raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known attribute."
  end

  return response_generator(:action => "ResetImageAttribute", :params => params)

end

#revoke_security_group_ingress(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The RevokeSecurityGroupIngress operation revokes existing permissions that were previously granted to a security group. The permissions to revoke must be specified using the same values originally used to grant the permission.

Permissions are specified in terms of the IP protocol (TCP, UDP or ICMP), the source of the request (by IP range or an Amazon EC2 user-group pair), source and destination port ranges (for TCP and UDP), and ICMP codes and types (for ICMP). When authorizing ICMP, -1 may be used as a wildcard in the type and code fields.

Permission changes are propagated to instances within the security group being modified as quickly as possible. However, a small delay is likely, depending on the number of instances that are members of the indicated group.

When revoking a user/group pair permission, GroupName, SourceSecurityGroupName and SourceSecurityGroupOwnerId must be specified. When authorizing a CIDR IP permission, GroupName, IpProtocol, FromPort, ToPort and CidrIp must be specified. Mixing these two types of parameters is not allowed.

Required Arguments:

:group_name => String (default : “”)

Optional Arguments:

:ip_protocol => String (default : nil) : Required when revoking CIDR IP permission :from_port => Integer (default : nil) : Required when revoking CIDR IP permission :to_port => Integer (default : nil) : Required when revoking CIDR IP permission :cidr_ip => String (default : nil): Required when revoking CIDR IP permission :source_security_group_name => String (default : nil) : Required when revoking user group pair permissions :source_security_group_owner_id => String (default : nil) : Required when revoking user group pair permissions

Raises:



202
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
 
# File 'lib/EC2/security_groups.rb', line 202

def revoke_security_group_ingress( options = {} )

  # defaults
  options = { :group_name => nil,
              :ip_protocol => nil,
              :from_port => nil,
              :to_port => nil,
              :cidr_ip => nil,
              :source_security_group_name => nil,
              :source_security_group_owner_id => nil }.merge(options)

  # lets not validate the rest of the possible permutations of required params and instead let
  # EC2 sort it out on the server side.  We'll only require :group_name as that is always needed.
  raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?

  params = { "GroupName" => options[:group_name],
             "IpProtocol" => options[:ip_protocol],
             "FromPort" => options[:from_port].to_s,
             "ToPort" => options[:to_port].to_s,
             "CidrIp" => options[:cidr_ip],
             "SourceSecurityGroupName" => options[:source_security_group_name],
             "SourceSecurityGroupOwnerId" => options[:source_security_group_owner_id]
             }

  return response_generator(:action => "RevokeSecurityGroupIngress", :params => params)

end

#run_instances(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The RunInstances operation launches a specified number of instances.

Note : The Query version of RunInstances only allows instances of a single AMI to be launched in one call. This is different from the SOAP API call of the same name but similar to the ec2-run-instances command line tool.

If Amazon EC2 cannot launch the minimum number AMIs you request, no instances launch. If there is insufficient capacity to launch the maximum number of AMIs you request, Amazon EC2 launches as many as possible to satisfy the requested maximum values.

Every instance is launched in a security group. If you do not specify a security group at launch, the instances start in the default security group.

An optional instance type can be specified. Currently supported types are ‘m1.small’, ‘m1.large’, ‘m1.xlarge’ and the high CPU types ‘c1.medium’ and ‘c1.xlarge’. ‘m1.small’ is the default if no instance_type is specified.

You can provide an optional key pair ID for each image in the launch request. All instances that are created from images that use this key pair will have access to the associated public key at boot. You can use this key to provide secure access to an instance of an image on a per-instance basis. Amazon EC2 public images use this feature to provide secure access without passwords.

Important! Launching public images without a key pair ID will leave them inaccessible.

The public key material is made available to the instance at boot time by placing it in a file named openssh_id.pub on a logical device that is exposed to the instance as /dev/sda2 (the ephemeral store). The format of this file is suitable for use as an entry within ~/.ssh/authorized_keys (the OpenSSH format). This can be done at boot time (as part of rclocal, for example) allowing for secure password-less access.

Optional user data can be provided in the launch request. All instances comprising the launch request have access to this data (see Instance Metadata for details).

If any of the AMIs have product codes attached for which the user has not subscribed, the RunInstances call will fail.

Required Arguments:

:image_id => String (Default : “”) :min_count => Integer (default : 1 ) :max_count => Integer (default : 1 )

Optional Arguments:

:key_name => String (default : nil) :group_id => Array (default : []) :user_data => String (default : nil) :addressing_type => String (default : “public”) :instance_type => String (default : “m1.small”) :availability_zone => String (default : nil) :base64_encoded => Boolean (default : false)

Raises:



70
71
72
73
74
75
76
77
78
79
80
81
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
 
# File 'lib/EC2/instances.rb', line 70

def run_instances( options = {} )

  options = { :image_id => "",
              :min_count => 1,
              :max_count => 1,
              :key_name => nil,
              :group_id => [],
              :user_data => nil,
              :addressing_type => "public",
              :instance_type => "m1.small",
              :availability_zone => nil,
              :base64_encoded => false }.merge(options)

  # Do some validation on the arguments provided
  raise ArgumentError, ":image_id must be provided" if options[:image_id].nil? || options[:image_id].empty?
  raise ArgumentError, ":min_count is not valid" unless options[:min_count].to_i > 0
  raise ArgumentError, ":max_count is not valid" unless options[:max_count].to_i > 0
  raise ArgumentError, ":addressing_type must be 'direct' or 'public'" unless options[:addressing_type] == "public" || options[:addressing_type] == "direct"
  raise ArgumentError, ":instance_type must be 'm1.small', 'm1.large', 'm1.xlarge', 'c1.medium', or 'c1.xlarge'" unless options[:instance_type] == "m1.small" || options[:instance_type] == "m1.large" || options[:instance_type] == "m1.xlarge" || options[:instance_type] == "c1.medium" || options[:instance_type] == "c1.xlarge"
  raise ArgumentError, ":base64_encoded must be 'true' or 'false'" unless options[:base64_encoded] == true || options[:base64_encoded] == false

  # If :user_data is passed in then URL escape and Base64 encode it
  # as needed.  Need for URL Escape + Base64 encoding is determined
  # by :base64_encoded param.
  if options[:user_data]
    if options[:base64_encoded]
      user_data = options[:user_data]
    else
      user_data = Base64.encode64(options[:user_data]).gsub(/\n/,"").strip()
    end
  else
    user_data = nil
  end

  params = {
    "ImageId"  => options[:image_id],
    "MinCount" => options[:min_count].to_s,
    "MaxCount" => options[:max_count].to_s,
  }.merge(pathlist("SecurityGroup", options[:group_id]))

  params["KeyName"] = options[:key_name] unless options[:key_name].nil?
  params["UserData"] = user_data unless user_data.nil?
  params["AddressingType"] = options[:addressing_type]
  params["InstanceType"] = options[:instance_type]
  params["Placement.AvailabilityZone"] = options[:availability_zone] unless options[:availability_zone].nil?

  return response_generator(:action => "RunInstances", :params => params)

end

#terminate_instances(options = {}) ⇒ Object

Amazon Developer Guide Docs:

The TerminateInstances operation shuts down one or more instances. This operation is idempotent and terminating an instance that is in the process of shutting down (or already terminated) will succeed. Terminated instances remain visible for a short period of time (approximately one hour) after termination, after which their instance ID is invalidated.

Required Arguments:

:instance_id => Array (default : [])

Optional Arguments:

none

Raises:



196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/EC2/instances.rb', line 196

def terminate_instances( options = {} )

  options = { :instance_id => [] }.merge(options)

  raise ArgumentError, "No :instance_id provided" if options[:instance_id].nil? || options[:instance_id].empty?

  params = pathlist("InstanceId", options[:instance_id])

  return response_generator(:action => "TerminateInstances", :params => params)

end