Class: AWS::EC2::Base

Inherits:
Base
  • Object
show all
Defined in:
lib/AWS/EC2.rb,
lib/AWS/EC2/tags.rb,
lib/AWS/EC2/images.rb,
lib/AWS/EC2/devpay.rb,
lib/AWS/EC2/volumes.rb,
lib/AWS/EC2/console.rb,
lib/AWS/EC2/subnets.rb,
lib/AWS/EC2/keypairs.rb,
lib/AWS/EC2/products.rb,
lib/AWS/EC2/password.rb,
lib/AWS/EC2/snapshots.rb,
lib/AWS/EC2/instances.rb,
lib/AWS/EC2/elastic_ips.rb,
lib/AWS/EC2/spot_prices.rb,
lib/AWS/EC2/security_groups.rb,
lib/AWS/EC2/image_attributes.rb,
lib/AWS/EC2/availability_zones.rb,
lib/AWS/EC2/spot_instance_requests.rb

Instance Attribute Summary

Attributes inherited from Base

#port, #proxy_server, #server, #use_ssl

Instance Method Summary (collapse)

Methods inherited from Base

#extract_user_data, #initialize

Constructor Details

This class inherits a constructor from AWS::Base

Instance Method Details

- (Object) allocate_address

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



8
9
10
# File 'lib/AWS/EC2/elastic_ips.rb', line 8

def allocate_address
  return response_generator(:action => "AllocateAddress")
end

- (Object) api_version



20
21
22
# File 'lib/AWS/EC2.rb', line 20

def api_version
  API_VERSION
end

- (Object) associate_address(options = {})

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.

Options Hash (options):

  • :instance_id (String) — default: ''

    the instance ID to associate an IP with.

  • :public_ip (String) — default: ''

    the public IP to associate an instance with.

Raises:



22
23
24
25
26
27
28
29
30
31
# File 'lib/AWS/EC2/elastic_ips.rb', line 22

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

- (Object) attach_volume(options = {})

The AttachVolume operation attaches an Amazon EBS volume to an instance.

Options Hash (options):

  • :volume_id (String) — default: ''
  • :instance_id (String) — default: ''
  • :device (String) — default: ''

Raises:



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# File 'lib/AWS/EC2/volumes.rb', line 57

def attach_volume( options = {} )
  options = { :volume_id => '' }.merge(options)
  options = { :instance_id => '' }.merge(options)
  options = { :device => '' }.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?
  raise ArgumentError, "No :device provided" if options[:device].nil? || options[:device].empty?

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

- (Object) authorize_security_group_ingress(options = {})

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.

Options Hash (options):

  • :group_name (String) — default: ""
  • :ip_protocol (optional, String) — default: nil

    Required when authorizing CIDR IP permission

  • :from_port (optional, Integer) — default: nil

    Required when authorizing CIDR IP permission

  • :to_port (optional, Integer) — default: nil

    Required when authorizing CIDR IP permission

  • :cidr_ip (optional, String) — default: nil

    Required when authorizing CIDR IP permission

  • :source_security_group_name (optional, String) — default: nil

    Required when authorizing user group pair permissions

  • :source_security_group_user_id (optional, String) — default: nil

    Required when authorizing user group pair permissions

Raises:



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
# File 'lib/AWS/EC2/security_groups.rb', line 85

def authorize_security_group_ingress( options = {} )
  options = { :group_name => nil,
              :ip_protocol => nil,
              :from_port => nil,
              :to_port => nil,
              :cidr_ip => nil,
              :source_security_group_name => nil,
              :source_security_group_user_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],
             "IpPermissions.1.IpProtocol" => options[:ip_protocol],
             "IpPermissions.1.FromPort" => options[:from_port].to_s,
             "IpPermissions.1.ToPort" => options[:to_port].to_s,
             "IpPermissions.1.IpRanges.1" => options[:cidr_ip],
             "IpPermissions.1.Groups.1.GroupName" => options[:source_security_group_name],
             "IpPermissions.1.Groups.1.UserId" => options[:source_security_group_user_id]
           }

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

- (Object) cancel_spot_instance_requests(options = {})

Cancels one or more Spot Instance requests. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current spot instance requests. For conceptual information about Spot Instances, refer to the Amazon Elastic Compute Cloud Developer Guide or Amazon Elastic Compute Cloud User Guide.

NB: Canceling a Spot Instance request does not terminate running Spot Instances associated with the request.

Options Hash (options):

  • :spot_instance_request_id (Array) — default: []


98
99
100
101
102
103
# File 'lib/AWS/EC2/spot_instance_requests.rb', line 98

def cancel_spot_instance_requests( options = {} )
  options = { :spot_instance_request_id => []}.merge(options)
  params = pathlist( "SpotInstanceRequestId", options[:spot_instance_request_id] )

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

- (Object) confirm_product_instance(options = {})

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.

Options Hash (options):

  • :product_code (String) — default: ""
  • :instance_id (String) — default: ""

Raises:



10
11
12
# File 'lib/AWS/EC2/devpay.rb', line 10

def confirm_product_instance( options = {} )
  raise "Not yet implemented"
end

- (Object) create_image(options = {})

Creates an AMI that uses an Amazon EBS root device from a “running” or “stopped” instance.

AMIs that use an Amazon EBS root device boot faster than AMIs that use instance stores. They can be up to 1 TiB in size, use storage that persists on instance failure, and can be stopped and started.

Options Hash (options):

  • :instance_id (String) — default: ""

    The ID of the instance.

  • :name (String) — default: ""

    The name of the AMI that was provided during image creation. Constraints 3-128 alphanumeric characters, parenthesis (()), commas (,), slashes (/), dashes (-), or underscores(_)

  • :description (optional, String) — default: ""

    The description of the AMI that was provided during image creation.

  • :no_reboot (optional, Boolean) — default: false

    By default this property is set to false, which means Amazon EC2 attempts to cleanly shut down the instance before image creation and reboots the instance afterwards. When set to true, Amazon EC2 does not shut down the instance before creating the image. When this option is used, file system integrity on the created image cannot be guaranteed.

Raises:



17
18
19
20
21
22
23
24
25
26
27
28
29
30
# File 'lib/AWS/EC2/images.rb', line 17

def create_image( options = {} )
  options = { :instance_id => "", :name => "" }.merge(options)
  raise ArgumentError, "No :instance_id provided" if options.does_not_have? :instance_id
  raise ArgumentError, "No :name provided" if options.does_not_have? :name
  raise ArgumentError, "Invalid string length for :name provided" if options[:name] && options[:name].size < 3 || options[:name].size > 128
  raise ArgumentError, "Invalid string length for :description provided (too long)" if options[:description] && options[:description].size > 255
  raise ArgumentError, ":no_reboot option must be a Boolean" unless options[:no_reboot].nil? || [true, false].include?(options[:no_reboot])
  params = {}
  params["InstanceId"] = options[:instance_id].to_s
  params["Name"] = options[:name].to_s
  params["Description"] = options[:description].to_s
  params["NoReboot"] = options[:no_reboot].to_s
  return response_generator(:action => "CreateImage", :params => params)
end

- (Object) create_keypair(options = {})

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.

Options Hash (options):

  • :key_name (String) — default: ""

Raises:



11
12
13
14
15
16
# File 'lib/AWS/EC2/keypairs.rb', line 11

def create_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 => "CreateKeyPair", :params => params)
end

- (Object) create_security_group(options = {})

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.

Options Hash (options):

  • :group_name (String) — default: ""
  • :group_description (String) — default: ""

Raises:



16
17
18
19
20
21
22
23
24
25
26
27
# File 'lib/AWS/EC2/security_groups.rb', line 16

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

- (Object) create_snapshot(options = {})

The CreateSnapshot operation creates a snapshot of an Amazon EBS volume and stores it in Amazon S3. You can use snapshots for backups, to launch instances from identical snapshots, and to save data before shutting down an instance.

Options Hash (options):

  • :volume_id (String) — default: ''
  • :description (optional, String) — default: ''

    Description of the Amazon EBS snapshot.

Raises:



27
28
29
30
31
32
33
34
35
# File 'lib/AWS/EC2/snapshots.rb', line 27

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]
  }
  params["Description"] = options[:description] unless options[:description].nil?
  return response_generator(:action => "CreateSnapshot", :params => params)
end

- (Object) create_tags(options = {})

The CreateTags operation adds or overwrites tags for the specified resource(s).

Examples:

Tag instance i-123456789 with the name 'Test Instance'.

create_tags(:resource_id => 'i-123456789',
            :tag         => [{'Name' => 'Test Instance'}])

Options Hash (options):

  • :resource_id (Array) — default: []

    The ids of the resource(s) to tag

  • :tag (Array) — default: []

    An array of Hashes representing the tags as string name/value pairs. Use nil or empty string to get a tag without a value

Raises:



14
15
16
17
18
19
20
21
# File 'lib/AWS/EC2/tags.rb', line 14

def create_tags( options = {} )
  raise ArgumentError, "No :resource_id provided" if options[:resource_id].nil? || options[:resource_id].empty?
  raise ArgumentError, "No :tag provided" if options[:tag].nil? || options[:tag].empty?

  params = pathlist("ResourceId", options[:resource_id] )
  params.merge!(pathkvlist('Tag', options[:tag], 'Key', 'Value', {}))
  return response_generator(:action => "CreateTags", :params => params)
end

- (Object) create_volume(options = {})

The CreateVolume operation creates a new Amazon EBS volume that you can mount from any Amazon EC2 instance.

Options Hash (options):

  • :availability_zone (String) — default: ''
  • :size (optional, String) — default: ''
  • :snapshot_id (optional, String) — default: ''

Raises:



23
24
25
26
27
28
29
30
31
32
33
34
# File 'lib/AWS/EC2/volumes.rb', line 23

def create_volume( options = {} )
  options = { :availability_zone => '' }.merge(options)
  raise ArgumentError, "No :availability_zone provided" if options[:availability_zone].nil? || options[:availability_zone].empty?
  options = { :size => '' }.merge(options)
  options = { :snapshot_id => '' }.merge(options)
  params = {
    "AvailabilityZone" => options[:availability_zone],
    "Size" => options[:size],
    "SnapshotId" => options[:snapshot_id]
  }
  return response_generator(:action => "CreateVolume", :params => params)
end

- (Object) default_host



24
25
26
# File 'lib/AWS/EC2.rb', line 24

def default_host
  DEFAULT_HOST
end

- (Object) delete_keypair(options = {})

The DeleteKeyPair operation deletes a keypair.

Options Hash (options):

  • :key_name (String) — default: ""

Raises:



36
37
38
39
40
41
# File 'lib/AWS/EC2/keypairs.rb', line 36

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

- (Object) delete_security_group(options = {})

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.

Options Hash (options):

  • :group_name (String) — default: ""

Raises:



53
54
55
56
57
58
# File 'lib/AWS/EC2/security_groups.rb', line 53

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

- (Object) delete_snapshot(options = {})

The DeleteSnapshot operation deletes a snapshot of an Amazon EBS volume that is stored in Amazon S3.

Options Hash (options):

  • :snapshot_id (String) — default: ''

Raises:



42
43
44
45
46
47
48
49
# File 'lib/AWS/EC2/snapshots.rb', line 42

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

- (Object) delete_tags(options = {})

The DeleteTags operation deletes tags for the specified resource(s).

Examples:

Remove the name tag from instance i-123456789.

delete_tags(:resource_id => 'i-123456789',
            :tag         => [{'Name' => nil}])

Remove the name tag from instance i-123456789, but only if it's 'Test Instance'.

delete_tags(:resource_id => 'i-123456789',
            :tag         => [{'Name' => 'Test Instance'}])

Options Hash (options):

  • :resource_id (Array) — default: []

    The ids of the resource(s) to tag

  • :tag (Array) — default: []

    An array of Hashes representing the tags as string name/value pairs. If a value is given (instead of nil or an empty string), then the tag is only deleted if it has the specified value

Raises:



53
54
55
56
57
58
59
60
# File 'lib/AWS/EC2/tags.rb', line 53

def delete_tags( options = {} )
  raise ArgumentError, "No :resource_id provided" if options[:resource_id].nil? || options[:resource_id].empty?
  raise ArgumentError, "No :tag provided" if options[:tag].nil? || options[:tag].empty?

  params = pathlist("ResourceId", options[:resource_id] )
  params.merge!(pathkvlist('Tag', options[:tag], 'Key', 'Value', {}))
  return response_generator(:action => "DeleteTags", :params => params)
end

- (Object) delete_volume(options = {})

The DeleteVolume operation deletes an Amazon EBS volume.

Options Hash (options):

  • :volume_id (String) — default: ''

Raises:



41
42
43
44
45
46
47
48
# File 'lib/AWS/EC2/volumes.rb', line 41

def delete_volume( 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 => "DeleteVolume", :params => params)
end

- (Object) deregister_image(options = {})

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

Options Hash (options):

  • :image_id (String) — default: ""

Raises:



38
39
40
41
42
43
# File 'lib/AWS/EC2/images.rb', line 38

def deregister_image( options = {} )
  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

- (Object) describe_addresses(options = {})

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

Options Hash (options):

  • :public_ip (Array) — default: []

    an IP address to be described



38
39
40
41
42
# File 'lib/AWS/EC2/elastic_ips.rb', line 38

def describe_addresses( options = {} )
  options = { :public_ip => [] }.merge(options)
  params = pathlist("PublicIp", options[:public_ip])
  return response_generator(:action => "DescribeAddresses", :params => params)
end

- (Object) describe_availability_zones(options = {})

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.

Options Hash (options):

  • :zone_name (optional, String) — default: []

    an Array of zone names



12
13
14
15
16
# File 'lib/AWS/EC2/availability_zones.rb', line 12

def describe_availability_zones( options = {} )
  options = { :zone_name => [] }.merge(options)
  params = pathlist("ZoneName", options[:zone_name] )
  return response_generator(:action => "DescribeAvailabilityZones", :params => params)
end

- (Object) describe_image_attribute(options = {})

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

Options Hash (options):

  • :image_id (String) — default: ""
  • :attribute (String) — default: "launchPermission"

    An attribute to describe, “launchPermission” or “productCodes”

Raises:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# File 'lib/AWS/EC2/image_attributes.rb', line 77

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

- (Object) describe_images(options = {})

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.

The results can be filtered using the filter argument. The EC2 API reference for a full description of filter types and arguments.

Examples:

@ec2.describe_images(:owner_id => ['self'], :filter => [{"tag:Role" => "App"}])

Options Hash (options):

  • :image_id (Array) — default: []
  • :owner_id (Array) — default: []
  • :executable_by (Array) — default: []
  • :filter (Array) — default: []


145
146
147
148
149
150
151
152
153
154
# File 'lib/AWS/EC2/images.rb', line 145

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] ))
  if options[:filter]
    params.merge!(pathkvlist('Filter', options[:filter], 'Name', 'Value', {}))
  end
  return response_generator(:action => "DescribeImages", :params => params)
end

- (Object) describe_instance_attribute(options = {})

Returns information about an attribute of an instance.

Options Hash (options):

  • :instance_id (String) — default: nil

    ID of the instance on which the attribute will be queried.

  • :attribute (String) — default: nil

    Specifies the attribute to query..

Raises:



102
103
104
105
106
107
108
109
110
111
# File 'lib/AWS/EC2/instances.rb', line 102

def describe_instance_attribute( options = {} )
  raise ArgumentError, "No :instance_id provided" if options[:instance_id].nil? || options[:instance_id].empty?
  raise ArgumentError, "No :attribute provided" if options[:attribute].nil? || options[:attribute].empty?
  valid_attributes = %w(instanceType kernel ramdisk userData disableApiTermination instanceInitiatedShutdownBehavior rootDevice blockDeviceMapping)
  raise ArgumentError, "Invalid :attribute provided" unless valid_attributes.include?(options[:attribute].to_s)
  params = {}
  params["InstanceId"] =  options[:instance_id]
  params["Attribute"] =  options[:attribute]
  return response_generator(:action => "DescribeInstanceAttribute", :params => params)
end

- (Object) describe_instances(options = {})

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

Options Hash (options):

  • :instance_id (Array) — default: []


90
91
92
93
94
# File 'lib/AWS/EC2/instances.rb', line 90

def describe_instances( options = {} )
  options = { :instance_id => [] }.merge(options)
  params = pathlist("InstanceId", options[:instance_id])
  return response_generator(:action => "DescribeInstances", :params => params)
end

- (Object) describe_keypairs(options = {})

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.

Options Hash (options):

  • :key_name (Array) — default: []


25
26
27
28
29
# File 'lib/AWS/EC2/keypairs.rb', line 25

def describe_keypairs( options = {} )
  options = { :key_name => [] }.merge(options)
  params = pathlist("KeyName", options[:key_name] )
  return response_generator(:action => "DescribeKeyPairs", :params => params)
end

- (Object) describe_regions(options = {})

TODO:

Implement this method

Not yet implemented



22
23
24
# File 'lib/AWS/EC2/availability_zones.rb', line 22

def describe_regions( options = {} )
  raise "Not yet implemented"
end

- (Object) describe_reserved_instances(options = {})

TODO:

Implement this method

Not yet implemented



237
238
239
# File 'lib/AWS/EC2/instances.rb', line 237

def describe_reserved_instances( options = {} )
  raise "Not yet implemented"
end

- (Object) describe_reserved_instances_offerings(options = {})

TODO:

Implement this method

Not yet implemented



246
247
248
# File 'lib/AWS/EC2/instances.rb', line 246

def describe_reserved_instances_offerings( options = {} )
  raise "Not yet implemented"
end

- (Object) describe_security_groups(options = {})

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 an exception is returned.

Options Hash (options):

  • :group_name (optional, Array) — default: []


39
40
41
42
43
# File 'lib/AWS/EC2/security_groups.rb', line 39

def describe_security_groups( options = {} )
  options = { :group_name => [] }.merge(options)
  params = pathlist("GroupName", options[:group_name] )
  return response_generator(:action => "DescribeSecurityGroups", :params => params)
end

- (Object) describe_snapshot_attribute(options = {})

The DescribeSnapshotAttribute operation returns information about an attribute of a snapshot. Only one attribute can be specified per call.

Options Hash (options):

  • :attribute (String) — default: 'createVolumePermission'

    Attribute to modify.

  • :snapshot_id (optional, Array) — default: []

    The ID of the Amazon EBS snapshot.



57
58
59
60
61
# File 'lib/AWS/EC2/snapshots.rb', line 57

def describe_snapshot_attribute( options = {} )
  params = { "Attribute" =>  options[:attribute] || 'createVolumePermission' }
  params.merge!(pathlist("SnapshotId", options[:snapshot_id] )) unless options[:snapshot_id].nil? || options[:snapshot_id] == []
  return response_generator(:action => "DescribeSnapshotAttribute", :params => params)
end

- (Object) describe_snapshots(options = {})

The DescribeSnapshots operation describes the status of Amazon EBS snapshots.

Options Hash (options):

  • :snapshot_id (optional, Array) — default: []

    The ID of the Amazon EBS snapshot.

  • :owner (optional, String) — default: ''

    Returns snapshots owned by the specified owner. Multiple owners can be specified. Valid values self | amazon | AWS Account ID

  • :restorable_by (optional, String) — default: ''

    Account ID of a user that can create volumes from the snapshot.



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

def describe_snapshots( options = {} )
  params = {}
  params.merge!(pathlist("SnapshotId", options[:snapshot_id] )) unless options[:snapshot_id].nil? || options[:snapshot_id] == []
  params["RestorableBy"] = options[:restorable_by] unless options[:restorable_by].nil?
  params["Owner"] = options[:owner] unless options[:owner].nil?
  return response_generator(:action => "DescribeSnapshots", :params => params)
end

- (Object) describe_spot_instance_requests(options = {})

Describes Spot Instance requests. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current spot instance requests. For conceptual information about Spot Instances, refer to the Amazon Elastic Compute Cloud Developer Guide or Amazon Elastic Compute Cloud User Guide.

Options Hash (options):

  • :spot_instance_request_id (Array) — default: []


81
82
83
84
85
86
# File 'lib/AWS/EC2/spot_instance_requests.rb', line 81

def describe_spot_instance_requests( options = {} )
  options = { :spot_instance_request_id => []}.merge(options)
  params = pathlist( "SpotInstanceRequestId", options[:spot_instance_request_id] )

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

- (Object) describe_spot_price_history(options = {})

This method returns historical information about spot prices.

Amazon periodically sets the spot price for each instance type based on available capacity and current spot instance requests.

Options Hash (options):

  • :start_time (Time) — default: nil
  • :end_time (Time) — default: nil
  • :instance_type (String) — default: nil
  • :product_description (String) — default: nil

Raises:



16
17
18
19
20
21
22
23
24
25
26
27
28
29
# File 'lib/AWS/EC2/spot_prices.rb', line 16

def describe_spot_price_history( options = {} )
  raise ArgumentError, ":start_time must be a Time object" unless options[:start_time].nil? || options[:start_time].kind_of?(Time)
  raise ArgumentError, ":end_time must be a Time object" unless options[:end_time].nil? || options[:end_time].kind_of?(Time)
  raise ArgumentError, ":instance_type must specify a valid instance type" unless options[:instance_type].nil? || ["t1.micro", "m1.small", "m1.large", "m1.xlarge", "m2.xlarge", "c1.medium", "c1.xlarge", "m2.2xlarge", "m2.4xlarge", "cc1.4xlarge", "cg1.4xlarge"].include?(options[:instance_type])
  raise ArgumentError, ":product_description must be 'Linux/UNIX' or 'Windows'" unless options[:product_description].nil? || ["Linux/UNIX", "Windows"].include?(options[:product_description])

  params = {}
  params.merge!("StartTime" => options[:start_time].iso8601) if options[:start_time]
  params.merge!("EndTime" => options[:end_time].iso8601) if options[:end_time]
  params.merge!("InstanceType" => options[:instance_type]) if options[:instance_type]
  params.merge!("ProductDescription" => options[:product_description]) if options[:product_description]

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

- (Object) describe_subnets(options = {})

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

Options Hash (options):

  • :subnet_id (Array) — default: []


11
12
13
14
15
# File 'lib/AWS/EC2/subnets.rb', line 11

def describe_subnets( options = {} )
  options = { :subnet_id => [] }.merge(options)
  params = pathlist("SubnetId", options[:subnet_id] )
  return response_generator(:action => "DescribeSubnets", :params => params)
end

- (Object) describe_tags(options = {})

The DescribeTags operation lists the tags. If you do not specify any filters, all tags will be returned.

Examples:

Find any instances tagged with the name 'Test Instance'.

describe_tags(:filter => [{'resource-type' => ['instance']},
                          {'key'           => ['Name']},
                          {'value'         => ['Test Instance']}])

Options Hash (options):

  • :filter (optional, Array) — default: []

    An array of Hashes representing the filters. Note that the values in the hashes have to be arrays



32
33
34
35
36
37
38
# File 'lib/AWS/EC2/tags.rb', line 32

def describe_tags( options = {} )
  params = {}
  if options[:filter]
    params.merge!(pathkvlist('Filter', options[:filter], 'Name', 'Value', {:resource_id => 'resource-id', :resource_type => 'resource-type' }))
  end
  return response_generator(:action => "DescribeTags", :params => params)
end

- (Object) describe_volumes(options = {})

The DescribeVolumes operation lists one or more Amazon EBS volumes that you own, If you do not specify any volumes, Amazon EBS returns all volumes that you own.

Options Hash (options):

  • :volume_id (optional, String) — default: []


10
11
12
13
14
# File 'lib/AWS/EC2/volumes.rb', line 10

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

- (Object) detach_volume(options = {})

The DetachVolume operation detaches an Amazon EBS volume from an instance.

Options Hash (options):

  • :volume_id (String) — default: ''
  • :instance_id (optional, String) — default: ''
  • :device (optional, String) — default: ''
  • :force (optional, Boolean) — default: ''

Raises:



81
82
83
84
85
86
87
88
89
90
91
92
93
94
# File 'lib/AWS/EC2/volumes.rb', line 81

def detach_volume( options = {} )
  options = { :volume_id => '' }.merge(options)
  raise ArgumentError, "No :volume_id provided" if options[:volume_id].nil? || options[:volume_id].empty?
  options = { :instance_id => '' }.merge(options)
  options = { :device => '' }.merge(options)
  options = { :force => '' }.merge(options)
  params = {
    "VolumeId" => options[:volume_id],
    "InstanceId" => options[:instance_id],
    "Device" => options[:device],
    "Force" => options[:force].to_s
  }
  return response_generator(:action => "DetachVolume", :params => params)
end

- (Object) disassociate_address(options = {})

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.

Options Hash (options):

  • :public_ip (String) — default: ''

    the public IP to be dis-associated.

Raises:



52
53
54
55
56
57
# File 'lib/AWS/EC2/elastic_ips.rb', line 52

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

- (Object) get_console_output(options = {})

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.

Options Hash (options):

  • :instance_id (String) — default: ""

    an Instance ID

Raises:



14
15
16
17
18
19
# File 'lib/AWS/EC2/console.rb', line 14

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

- (Object) get_password_data(options = {})

The GetPasswordData operation retrieves the encrypted administrator password for the instances running Window.

Options Hash (options):

  • :instance_id (String) — default: ""

    an Instance ID

Raises:



10
11
12
13
14
15
# File 'lib/AWS/EC2/password.rb', line 10

def get_password_data( 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 => "GetPasswordData", :params => params)
end

- (Object) modify_image_attribute(options = {})

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.

Options Hash (options):

  • :image_id (String) — default: ""
  • :attribute (String) — default: "launchPermission"

    An attribute to modify, “launchPermission” or “productCodes”

  • :operation_type (String) — default: ""
  • :user_id (optional, Array) — default: []
  • :group (optional, Array) — default: []
  • :product_code (optional, Array) — default: []

Raises:



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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
# File 'lib/AWS/EC2/image_attributes.rb', line 22

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

- (Object) modify_instance_attribute(options = {})

Modifies an attribute of an instance.

Options Hash (options):

  • :instance_id (String) — default: nil

    ID of the instance on which the attribute will be modified.

  • :attribute (String) — default: nil

    Specifies the attribute to modify.

  • :value (String) — default: nil

    The value of the attribute being modified.

Raises:



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

def modify_instance_attribute( options = {} )
  raise ArgumentError, "No :instance_id provided" if options[:instance_id].nil? || options[:instance_id].empty?
  raise ArgumentError, "No :attribute provided" if options[:attribute].nil? || options[:attribute].empty?
  raise ArgumentError, "No :value provided" if options[:value].nil?
  valid_attributes = %w(instanceType kernel ramdisk userData disableApiTermination instanceInitiatedShutdownBehavior rootDevice blockDeviceMapping)
  raise ArgumentError, "Invalid :attribute provided" unless valid_attributes.include?(options[:attribute].to_s)
  params = {}
  params["InstanceId"] =  options[:instance_id]
  params["Attribute"] =  options[:attribute]
  params["Value"] =  options[:value].to_s
  return response_generator(:action => "ModifyInstanceAttribute", :params => params)
end

- (Object) modify_snapshot_attribute(options = {})

The ModifySnapshotAttribute operation adds or remove permission settings for the specified snapshot.

Options Hash (options):

  • :snapshot_id (String) — default: ''

    The ID of the Amazon EBS snapshot.

  • :attribute (String) — default: 'createVolumePermission'

    Attribute to modify.

  • :operation_type (String) — default: ''

    Operation to perform on the attribute.

  • :user_id (optional, String) — default: ''

    Account ID of a user that can create volumes from the snapshot.

  • :user_group (optional, String) — default: ''

    Group that is allowed to create volumes from the snapshot.

Raises:



72
73
74
75
76
77
78
79
80
81
82
83
84
85
# File 'lib/AWS/EC2/snapshots.rb', line 72

def modify_snapshot_attribute( options = {} )
  options = { :snapshot_id => '' }.merge(options)
  raise ArgumentError, "No :snapshot_id provided" if options[:snapshot_id].nil? || options[:snapshot_id].empty?
  options = { :operation_type => '' }.merge(options)
  raise ArgumentError, "No :operation_type provided" if options[:snapshot_id].nil? || options[:snapshot_id].empty?
 params = {
    "Attribute" =>  options[:attribute] || 'createVolumePermission',
    "SnapshotId" => options[:snapshot_id],
    "OperationType" => options[:operation_type]
  }
  params["UserId"] = options[:user_id] unless options[:user_id].nil?
  params["UserGroup"] = options[:user_group] unless options[:user_group].nil?
  return response_generator(:action => "ModifySnapshotAttribute", :params => params)
end

- (Object) monitor_instances(options = {})

The MonitorInstances operation tells Cloudwatch to begin logging metrics from one or more EC2 instances

Options Hash (options):

  • :instance_id (Array) — default: []

Raises:



213
214
215
216
217
218
# File 'lib/AWS/EC2/instances.rb', line 213

def monitor_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 => "MonitorInstances", :params => params)
end

- (Object) purchase_reserved_instances_offering(options = {})

TODO:

Implement this method

Not yet implemented



255
256
257
# File 'lib/AWS/EC2/instances.rb', line 255

def purchase_reserved_instances_offering( options = {} )
  raise "Not yet implemented"
end

- (Object) reboot_instances(options = {})

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.

Options Hash (options):

  • :instance_id (Array) — default: []

Raises:



186
187
188
189
190
191
# File 'lib/AWS/EC2/instances.rb', line 186

def reboot_instances( options = {} )
  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

- (Object) register_image(options = {})

Registers an AMI with Amazon EC2. Images must be registered before they can be launched. To launch instances, use the RunInstances operation. Each AMI is associated with an unique ID which is provided by the Amazon EC2 service through this operation. If needed, you can deregister an AMI at any time.

AMIs backed by Amazon EBS are automatically registered when you create the image. However, you can use this to register a snapshot of an instance backed by Amazon EBS.

Amazon EBS snapshots are not guaranteed to be bootable. For information on creating AMIs backed by Amazon EBS, go to the Amazon Elastic Compute Cloud Developer Guide or Amazon Elastic Compute Cloud User Guide.

Any modifications to an AMI backed by Amazon S3 invalidates this registration. If you make changes to an image, deregister the previous image and register the new image.

If an :image_location is specified then an old-style S3-backed AMI is created. If the other parameters are used then a new style EBS-backed AMI is created from a pre-existing snapshot.

Options Hash (options):

  • :image_location (optional, String) — default: ""

    S3 URL for the XML manifest

  • :name (optional, String) — default: ""

    Name of EBS image

  • :description (optional, String) — default: ""

    Description of EBS image

  • :architecture (optional, String) — default: ""

    Architecture of EBS image, currently 'i386' or 'x86_64'

  • :kernel_id (optional, String) — default: ""

    Kernel ID of EBS image

  • :ramdisk_id (optional, String) — default: ""

    Ramdisk ID of EBS image

  • :root_device_name (optional, String) — default: ""

    Root device name of EBS image, eg '/dev/sda1'

  • :block_device_mapping (optional, Array) — default: []

    An array of Hashes representing the elements of the block device mapping. e.g. [=> '/dev/sdh', :virtual_name => '', :ebs_snapshot_id => '', :ebs_volume_size => '', :ebs_delete_on_termination => '',{},…]



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
# File 'lib/AWS/EC2/images.rb', line 73

def register_image( options = {} )
  params = {}
  if options.does_not_have?(:image_location) && options.does_not_have?(:root_device_name)
    raise ArgumentError, "No :image_location or :root_device_name"
  end
  params["ImageLocation"] = options[:image_location].to_s unless options[:image_location].nil?
  params["Name"] = options[:name].to_s unless options[:name].nil?
  params["Description"] = options[:description].to_s unless options[:description].nil?
  params["Architecture"] = options[:architecture].to_s unless options[:architecture].nil?
  params["KernelId"] = options[:kernel_id].to_s unless options[:kernel_id].nil?
  params["RamdiskId"] = options[:ramdisk_id].to_s unless options[:ramdisk_id].nil?
  params["RootDeviceName"] = options[:root_device_name].to_s unless options[:root_device_name].nil?
  if options[:block_device_mapping]
    params.merge!(pathhashlist("BlockDeviceMapping", options[:block_device_mapping].flatten, {
      :device_name => "DeviceName",
      :virtual_name => "VirtualName",
      :ebs_snapshot_id => "Ebs.SnapshotId",
      :ebs_volume_size => "Ebs.VolumeSize",
      :ebs_delete_on_termination => "Ebs.DeleteOnTermination"
    }))
  end
  return response_generator(:action => "RegisterImage", :params => params)
end

- (Object) release_address(options = {})

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.

Options Hash (options):

  • :public_ip (String) — default: ''

    an IP address to be released.

Raises:



75
76
77
78
79
80
# File 'lib/AWS/EC2/elastic_ips.rb', line 75

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

- (Object) request_spot_instances(options = {})

Creates a Spot Instance request. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current spot instance requests. For conceptual information about Spot Instances, refer to the Amazon Elastic Compute Cloud Developer Guide or Amazon Elastic Compute Cloud User Guide.

Options Hash (options):

  • :spot_price (String) — default: nil

    Specifies the maximum hourly price for any Spot Instance launched to fulfill the request.

  • :instance_count (optional, Integer) — default: 1

    The maximum number of Spot Instances to launch.

  • :type (optional, String) — default: nil

    Specifies the Spot Instance type.

  • :valid_from (optional, Date) — default: nil

    Start date of the request. If this is a one-time request, the request becomes active at this date and time and remains active until all instances launch, the request expires, or the request is canceled. If the request is persistent, the request becomes active at this date and time and remains active until it expires or is canceled.

  • :valid_until (optional, Date) — default: nil

    End date of the request. If this is a one-time request, the request remains active until all instances launch, the request is canceled, or this date is reached. If the request is persistent, it remains active until it is canceled or this date and time is reached.

  • :launch_group (optional, String) — default: nil

    Specifies the instance launch group. Launch groups are Spot Instances that launch together and terminate together.

  • :availability_zone_group (optional, String) — default: ""

    Specifies the Availability Zone group. If you specify the same Availability Zone group for all Spot Instance requests, all Spot Instances are launched in the same Availability Zone.

  • :image_id (optional, String) — default: nil

    The AMI ID.

  • :key_name (optional, String) — default: nil

    The name of the key pair.

  • :security_group (optional, Array of Strings or String) — default: nil

    Name of the security group(s).

  • :user_data (optional, String) — default: nil

    MIME, Base64-encoded user data.

  • :instance_type (optional, String) — default: "m1.small"

    Specifies the instance type.

  • :kernel_id (optional, String) — default: nil

    The ID of the kernel to select.

  • :ramdisk_id (optional, String) — default: nil

    The ID of the RAM disk to select. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk and search for the kernel ID.

  • :subnet_id (optional, String) — default: nil

    Specifies the Amazon VPC subnet ID within which to launch the instance(s) for Amazon Virtual Private Cloud.

  • :availability_zone (optional, String) — default: nil

    Specifies the placement constraints (Availability Zones) for launching the instances.

  • :block_device_mapping (optional, Array) — default: []

    An array of Hashes representing the elements of the block device mapping. e.g. [=> '/dev/sdh', :virtual_name => '', :ebs_snapshot_id => '', :ebs_volume_size => '', :ebs_delete_on_termination => '',{},…]

  • :monitoring_enabled (optional, Boolean) — default: false

    Enables monitoring for the instance.

  • :base64_encoded (optional, Boolean) — default: false

Raises:



32
33
34
35
36
37
38
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
# File 'lib/AWS/EC2/spot_instance_requests.rb', line 32

def request_spot_instances( options = {} )
  options = { :instance_count => 1,
              :instance_type => 'm1.small',
              :base64_encoded => false }.merge(options)

  raise ArgumentError, ":addressing_type has been deprecated." if options[:addressing_type]
  raise ArgumentError, ":spot_price must be provided" if options[:spot_price].nil? || options[:spot_price].empty?
  raise ArgumentError, ":base64_encoded must be 'true' or 'false'" unless [true, false].include?(options[:base64_encoded])
  raise ArgumentError, ":instance_type must specify a valid instance type" unless options[:instance_type].nil? || ["t1.micro", "m1.small", "m1.large", "m1.xlarge", "m2.xlarge", "c1.medium", "c1.xlarge", "m2.2xlarge", "m2.4xlarge", "cc1.4xlarge"].include?(options[:instance_type])

  user_data = extract_user_data(options)

  params = {}

  if options[:security_group]
    params.merge!(pathlist("LaunchSpecification.SecurityGroup", options[:security_group]))
  end

  if options[:block_device_mapping]
    params.merge!(pathhashlist('LaunchSpecification.BlockDeviceMapping', options[:block_device_mapping].flatten, {:device_name => 'DeviceName', :virtual_name => 'VirtualName', :ebs_snapshot_id => 'Ebs.SnapshotId', :ebs_volume_size => 'Ebs.VolumeSize', :ebs_delete_on_termination => 'Ebs.DeleteOnTermination' }))
  end

  params["SpotPrice"]                                             = options[:spot_price]
  params["InstanceCount"]                                         = options[:instance_count].to_s
  params["Type"]                                                  = options[:type] unless options[:type].nil?
  params["ValidFrom"]                                             = options[:valid_from].to_s unless options[:valid_from].nil?
  params["ValidUntil"]                                            = options[:valid_until].to_s unless options[:valid_until].nil?
  params["LaunchGroup"]                                           = options[:launch_group] unless options[:launch_group].nil?
  params["AvailabilityZoneGroup"]                                 = options[:availability_zone_group] unless options[:availability_zone_group].nil?
  params["LaunchSpecification.ImageId"]                           = options[:image_id] unless options[:image_id].nil?
  params["LaunchSpecification.KeyName"]                           = options[:key_name] unless options[:key_name].nil?
  params["LaunchSpecification.UserData"]                          = user_data unless user_data.nil?
  params["LaunchSpecification.InstanceType"]                      = options[:instance_type] unless options[:instance_type].nil?
  params["LaunchSpecification.KernelId"]                          = options[:kernel_id] unless options[:kernel_id].nil?
  params["LaunchSpecification.RamdiskId"]                         = options[:ramdisk_id] unless options[:ramdisk_id].nil?
  params["LaunchSpecification.SubnetId"]                          = options[:subnet_id] unless options[:subnet_id].nil?
  params["LaunchSpecification.Placement.AvailabilityZone"]        = options[:availability_zone] unless options[:availability_zone].nil?
  params["LaunchSpecification.Monitoring.Enabled"]                = options[:monitoring_enabled].to_s unless options[:monitoring_enabled].nil?

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

- (Object) reset_image_attribute(options = {})

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

Options Hash (options):

  • :image_id (String) — default: ""
  • :attribute (String) — default: "launchPermission"

    An attribute to reset

Raises:



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# File 'lib/AWS/EC2/image_attributes.rb', line 107

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

- (Object) reset_instance_attribute(options = {})

Resets an attribute of an instance to its default value.

Options Hash (options):

  • :instance_id (String) — default: nil

    ID of the instance on which the attribute will be reset.

  • :attribute (String) — default: nil

    The instance attribute to reset to the default value.

Raises:



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

def reset_instance_attribute( options = {} )
  raise ArgumentError, "No :instance_id provided" if options[:instance_id].nil? || options[:instance_id].empty?
  raise ArgumentError, "No :attribute provided" if options[:attribute].nil? || options[:attribute].empty?
  valid_attributes = %w(kernel ramdisk)
  raise ArgumentError, "Invalid :attribute provided" unless valid_attributes.include?(options[:attribute].to_s)
  params = {}
  params["InstanceId"] =  options[:instance_id]
  params["Attribute"] =  options[:attribute]
  return response_generator(:action => "ResetInstanceAttribute", :params => params)
end

- (Object) reset_snapshot_attribute(options = {})

The ResetSnapshotAttribute operation resets permission settings for the specified snapshot.

Options Hash (options):

  • :snapshot_id (optional, Array) — default: []

    The ID of the Amazon EBS snapshot.

  • :attribute (String) — default: 'createVolumePermission'

    Attribute to reset.

Raises:



93
94
95
96
97
98
99
# File 'lib/AWS/EC2/snapshots.rb', line 93

def reset_snapshot_attribute( options = {} )
  options = { :snapshot_id => '' }.merge(options)
  raise ArgumentError, "No :snapshot_id provided" if options[:snapshot_id].nil? || options[:snapshot_id].empty?
  params = { "Attribute" =>  options[:attribute] || 'createVolumePermission' }
  params["SnapshotId"] = options[:snapshot_id] unless options[:snapshot_id].nil? || options[:snapshot_id].empty?
  return response_generator(:action => "ResetSnapshotAttribute", :params => params)
end

- (Object) revoke_security_group_ingress(options = {})

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.

Options Hash (options):

  • :group_name (String) — default: ""
  • :ip_protocol (optional, String) — default: nil

    Required when revoking CIDR IP permission

  • :from_port (optional, Integer) — default: nil

    Required when revoking CIDR IP permission

  • :to_port (optional, Integer) — default: nil

    Required when revoking CIDR IP permission

  • :cidr_ip (optional, String) — default: nil

    Required when revoking CIDR IP permission

  • :source_security_group_name (optional, String) — default: nil

    Required when revoking user group pair permissions

  • :source_security_group_user_id (optional, String) — default: nil

    Required when revoking user group pair permissions

Raises:



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
# File 'lib/AWS/EC2/security_groups.rb', line 137

def revoke_security_group_ingress( options = {} )
  options = { :group_name => nil,
              :ip_protocol => nil,
              :from_port => nil,
              :to_port => nil,
              :cidr_ip => nil,
              :source_security_group_name => nil,
              :source_security_group_user_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],
             "IpPermissions.1.IpProtocol" => options[:ip_protocol],
             "IpPermissions.1.FromPort" => options[:from_port].to_s,
             "IpPermissions.1.ToPort" => options[:to_port].to_s,
             "IpPermissions.1.IpRanges.1" => options[:cidr_ip],
             "IpPermissions.1.Groups.1.GroupName" => options[:source_security_group_name],
             "IpPermissions.1.Groups.1.UserId" => options[:source_security_group_user_id]
           }

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

- (Object) run_instances(options = {})

Launches a specified number of instances of an AMI for which you have permissions.

Amazon API Docs : HTML

Options Hash (options):

  • :image_id (String) — default: ""

    Unique ID of a machine image.

  • :min_count (Integer) — default: 1

    Minimum number of instances to launch. If the value is more than Amazon EC2 can launch, no instances are launched at all.

  • :max_count (Integer) — default: 1

    Maximum number of instances to launch. If the value is more than Amazon EC2 can launch, the largest possible number above minCount will be launched instead.

  • :key_name (optional, String) — default: nil

    The name of the key pair.

  • :security_group (optional, Array) — default: nil

    Name of the security group(s). Array of Strings or String.

  • :additional_info (optional, String) — default: nil

    Specifies additional information to make available to the instance(s).

  • :user_data (optional, String) — default: nil

    MIME, Base64-encoded user data.

  • :instance_type (optional, String) — default: nil

    Specifies the instance type.

  • :availability_zone (optional, String) — default: nil

    Specifies the placement constraints (Availability Zones) for launching the instances.

  • :kernel_id (optional, String) — default: nil

    The ID of the kernel with which to launch the instance.

  • :ramdisk_id (optional, String) — default: nil

    The ID of the RAM disk with which to launch the instance. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk. To find kernel requirements, go to the Resource Center and search for the kernel ID.

  • :block_device_mapping (optional, Array) — default: []

    An array of Hashes representing the elements of the block device mapping. e.g. [=> '/dev/sdh', :virtual_name => '', :ebs_snapshot_id => '', :ebs_volume_size => '', :ebs_delete_on_termination => '',{},…]

  • :monitoring_enabled (optional, Boolean) — default: false

    Enables monitoring for the instance.

  • :subnet_id (optional, String) — default: nil

    Specifies the Amazon VPC subnet ID within which to launch the instance(s) for Amazon Virtual Private Cloud.

  • :disable_api_termination (optional, Boolean) — default: true

    Specifies whether the instance can be terminated using the APIs. You must modify this attribute before you can terminate any “locked” instances from the APIs.

  • :instance_initiated_shutdown_behavior (optional, String) — default: 'stop'

    Specifies whether the instance's Amazon EBS volumes are stopped or terminated when the instance is shut down. Valid values : 'stop', 'terminate'

  • :base64_encoded (optional, Boolean) — default: false
  • :client_token (optional, String) — default: nil

    Unique, case-sensitive identifier you provide to ensure idempotency of the request

Raises:



28
29
30
31
32
33
34
35
36
37
38
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
# File 'lib/AWS/EC2/instances.rb', line 28

def run_instances( options = {} )
  options = { :image_id => "",
              :min_count => 1,
              :max_count => 1,
              :base64_encoded => false }.merge(options)

  raise ArgumentError, ":addressing_type has been deprecated." if options[:addressing_type]
  raise ArgumentError, ":group_id has been deprecated." if options[:group_id]

  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 or must be >= :min_count" unless options[:max_count].to_i > 0 && options[:max_count].to_i >= options[:min_count].to_i
  raise ArgumentError, ":instance_type must specify a valid instance type" unless options[:instance_type].nil? || ["t1.micro", "m1.small", "m1.large", "m1.xlarge", "m2.xlarge", "c1.medium", "c1.xlarge", "m2.2xlarge", "m2.4xlarge", "cc1.4xlarge"].include?(options[:instance_type])
  raise ArgumentError, ":monitoring_enabled must be 'true' or 'false'" unless options[:monitoring_enabled].nil? || [true, false].include?(options[:monitoring_enabled])
  raise ArgumentError, ":disable_api_termination must be 'true' or 'false'" unless options[:disable_api_termination].nil? || [true, false].include?(options[:disable_api_termination])
  raise ArgumentError, ":instance_initiated_shutdown_behavior must be 'stop' or 'terminate'" unless options[:instance_initiated_shutdown_behavior].nil? || ["stop", "terminate"].include?(options[:instance_initiated_shutdown_behavior])
  raise ArgumentError, ":base64_encoded must be 'true' or 'false'" unless [true, false].include?(options[:base64_encoded])

  user_data = extract_user_data(options)

  params = {}

  if options[:security_group]
    params.merge!(pathlist("SecurityGroup", options[:security_group]))
  end

  if options[:block_device_mapping]
    params.merge!(pathhashlist('BlockDeviceMapping', options[:block_device_mapping].flatten, {:device_name => 'DeviceName', :virtual_name => 'VirtualName', :ebs_snapshot_id => 'Ebs.SnapshotId', :ebs_volume_size => 'Ebs.VolumeSize', :ebs_delete_on_termination => 'Ebs.DeleteOnTermination' }))
  end

  params["ImageId"]                           = options[:image_id]
  params["MinCount"]                          = options[:min_count].to_s
  params["MaxCount"]                          = options[:max_count].to_s
  params["KeyName"]                           = options[:key_name] unless options[:key_name].nil?
  params["AdditionalInfo"]                    = options[:additional_info] unless options[:additional_info].nil?
  params["UserData"]                          = user_data unless user_data.nil?
  params["InstanceType"]                      = options[:instance_type] unless options[:instance_type].nil?
  params["Placement.AvailabilityZone"]        = options[:availability_zone] unless options[:availability_zone].nil?
  params["KernelId"]                          = options[:kernel_id] unless options[:kernel_id].nil?
  params["RamdiskId"]                         = options[:ramdisk_id] unless options[:ramdisk_id].nil?
  params["Monitoring.Enabled"]                = options[:monitoring_enabled].to_s unless options[:monitoring_enabled].nil?
  params["SubnetId"]                          = options[:subnet_id] unless options[:subnet_id].nil?
  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].nil?
  params["ClientToken"]                       = options[:client_token].to_s unless options[:client_token].nil?

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

- (Object) start_instances(options = {})

Starts an instance that uses an Amazon EBS volume as its root device.

Options Hash (options):

  • :instance_id (Array) — default: []

    Array of unique instance ID's of stopped instances.

Raises:



155
156
157
158
159
160
161
# File 'lib/AWS/EC2/instances.rb', line 155

def start_instances( options = {} )
  options = { :instance_id => [] }.merge(options)
  raise ArgumentError, "No :instance_id provided" if options[:instance_id].nil? || options[:instance_id].empty?
  params = {}
  params.merge!(pathlist("InstanceId", options[:instance_id]))
  return response_generator(:action => "StartInstances", :params => params)
end

- (Object) stop_instances(options = {})

Stops an instance that uses an Amazon EBS volume as its root device.

Options Hash (options):

  • :instance_id (Array) — default: []

    Unique instance ID of a running instance.

  • :force (optional, Boolean) — default: false

    Forces the instance to stop. The instance will not have an opportunity to flush file system caches nor file system meta data. If you use this option, you must perform file system check and repair procedures. This option is not recommended for Windows instances.

Raises:



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

def stop_instances( options = {} )
  options = { :instance_id => [] }.merge(options)
  raise ArgumentError, "No :instance_id provided" if options[:instance_id].nil? || options[:instance_id].empty?
  raise ArgumentError, ":force must be 'true' or 'false'" unless options[:force].nil? || [true, false].include?(options[:force])
  params = {}
  params.merge!(pathlist("InstanceId", options[:instance_id]))
  params["Force"] = options[:force].to_s unless options[:force].nil?
  return response_generator(:action => "StopInstances", :params => params)
end

- (Object) terminate_instances(options = {})

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.

Options Hash (options):

  • :instance_id (Array) — default: []

Raises:



201
202
203
204
205
206
# File 'lib/AWS/EC2/instances.rb', line 201

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

- (Object) unmonitor_instances(options = {})

The UnmonitorInstances operation tells Cloudwatch to stop logging metrics from one or more EC2 instances

Options Hash (options):

  • :instance_id (Array) — default: []

Raises:



225
226
227
228
229
230
# File 'lib/AWS/EC2/instances.rb', line 225

def unmonitor_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 => "UnmonitorInstances", :params => params)
end