Class: AWS::EC2::InstanceCollection

Inherits:
Collection show all
Includes:
BlockDeviceMappings, TaggedCollection
Defined in:
lib/aws/ec2/instance_collection.rb

Overview

Represents a collection of EC2 instances. Typically you should get an instance of this class by calling #instances.

To run an instance:

ec2.instances.create(:image_id => "ami-8c1fece5")

To get an instance by ID:

i = ec2.instances["i-12345678"]
i.exists?

To get a map of instance IDs to instance status:

ec2.instances.inject({}) { |m, i| m[i.id] = i.status; m }
# => { "i-12345678" => :running, "i-87654321" => :shutting_down }

Instance Attribute Summary

Attributes included from Core::Model

#config

Instance Method Summary collapse

Methods included from TaggedCollection

#tagged, #tagged_values

Methods included from FilteredCollection

#filter, #filtered_request, #initialize

Methods included from Core::Model

#client, #config_prefix, #initialize, #inspect

Instance Method Details

#[](id) ⇒ Instance

Returns an object representing the EC2 instance with the given ID.

Returns:

  • (Instance) —

    Returns an object representing the EC2 instance with the given ID.



273
274
275
 
# File 'lib/aws/ec2/instance_collection.rb', line 273

def [] id
  super
end

#create(options = {}) ⇒ Instance or Array Also known as: run

Runs one or more EC2 instances.

sleep 1 while instances.any? {|i| i.status == :pending }

Examples:

Running a single instance

i = ec2.instances.create(:image_id => "ami-8c1fece5")
sleep 1 while i.status == :pending

Running multiple instances with the same parameters


instances = ec2.instances.create(
  :image_id => "ami-8c1fece5",
  :count => 10)

Specifying block device mappings


ec2.instances.create({
  :image_id => "ami-8c1fece5",
  :block_device_mappings => {
    "/dev/sda2" => {
      :volume_size => 15, # 15 GiB
      :delete_on_termination => true
    }
  }
})

Launching in an Amazon VPC subnet


ec2.instances.create(
  :image_id => "ami-8c1fece5",
  :subnet => "subnet-abc123ef")

Parameters:

  • options (Hash) (defaults to: {}) —

    Options for new instance. :image_id is the only required option.

Options Hash (options):

  • :count (Object) —

    How many instances to request. By default one instance is requested. You can specify this either as an integer or as a Range, to indicate the minimum and maximum number of instances to run. Note that for a new account you can request at most 20 instances at once.

  • :block_device_mappings (Hash) —

    This must be a hash; the keys are device names to map, and the value for each entry determines how that device is mapped. Valid values include:

    • A string, which is interpreted as a virtual device name.

    • The symbol :no_device, which overrides the default mapping for a device so that it is not mapped to anything.

    • A hash with any of the following options. One of :snapshot, :snapshot_id or :volume_size is required.

      :snapshot

      A snapshot to use when creating the block device.

      :snapshot_id

      The ID of a snapshot to use when creating the block device.

      :volume_size

      The size of volume to create, in gigabytes.

      :delete_on_termination

      Setting this to true causes EC2 to delete the volume when the instance is terminated.

  • :monitoring (Boolean) —

    Setting this to true enables CloudWatch monitoring on the instances once they are started.

  • :availability_zone (String) —

    Specifies the availability zone where the instance should run. Without this option, EC2 will choose an availability zone for you.

  • :image_id (String) —

    ID of the AMI you want to launch.

  • :key_name (String) —

    The name of the key pair to use. Note: Launching public images without a key pair ID will leave them inaccessible.

  • :security_groups (Array) —

    Security groups are used to determine network access rules for the instances.

    :security_groups can be a single value or an array of values. Values should be group name strings or SecurityGroup objects.

  • :security_group_ids (Array<String>) —

    Security groups are used to determine network access rules for the instances.

    :security_group_ids accepts a single ID or an array of security group IDs.

  • :user_data (String) —

    Arbitrary user data. You do not need to encode this value.

  • :instance_type (String) —

    The type of instance to launch, for example “m1.small”.

  • :kernel_id (String) —

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

  • :ramdisk_id (String) —

    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. To find kernel requirements, refer to the Resource Center and search for the kernel ID.

  • :disable_api_termination (Boolean) —

    Specifies whether you can terminate the instance using the EC2 API. A value of true means you can’t terminate the instance using the API (i.e., the instance is “locked”); a value of false means you can. If you set this to true, and you later want to terminate the instance, you must first enable API termination. For example:

    i = ec2.instances.create(:image_id => "ami-8c1fece5",
                         :disable_api_termination => true)
i.api_termination_disabled?        # => true
i.terminate                        # raises an exception
i.api_termination_disabled = false
i.terminate                        # terminates the instance
  • :instance_initiated_shutdown_behavior (String) —

    Determines whether the instance stops or terminates on instance-initiated shutdown.

  • :subnet (Subnet, String) — default: nil —

    The VPC Subnet (or subnet id string) to launch the instance in.

  • :private_ip_address (String) — default: nil —

    If you’re using VPC, you can optionally use this option to assign the instance a specific available IP address from the subnet (e.g., ‘10.0.0.25’). This option is not valid for instances launched outside a VPC (i.e. those launched without the :subnet option).

  • :dedicated_tenancy (Boolean) — default: false —

    Instances with dedicated tenancy will not share physical hardware with instances outside their VPC. NOTE: Dedicated tenancy incurs an additional service charge. This option is not valid for instances launched outside a VPC (e.g. those launched without the :subnet option).

Returns:

  • (Instance or Array) —

    If a single instance is being created, this returns an AWS::EC2::Instance to represent the newly created instance. Otherwise it returns an array of instance objects.



193
194
195
196
197
198
199
200
201
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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/aws/ec2/instance_collection.rb', line 193

def create options = {}

  if image = options.delete(:image)
    options[:image_id] = image.id
  end

  if kernel = options.delete(:kernel)
    options[:kernel_id] = kernel.id
  end

  if ramdisk = options.delete(:ramdisk)
    options[:ramdisk_id] = ramdisk.id
  end

  if key_pair = options.delete(:key_pair)
    options[:key_name] = key_pair.name
  end

  options = count_options(options).merge(options)
  options.delete(:count)

  options[:user_data] = Base64.encode64(options[:user_data]).strip if
    options[:user_data]

  options[:block_device_mappings] =
    translate_block_device_mappings(options[:block_device_mappings]) if
    options[:block_device_mappings]

  options[:monitoring] = { :enabled => true } if
    options[:monitoring_enabled]
  options.delete(:monitoring_enabled)

  placement = {}

  if options[:availability_zone]
    placement[:availability_zone] = options[:availability_zone].to_s
    options.delete(:availability_zone)
  end

  if options[:dedicated_tenancy]
    placement[:tenancy] = 'dedicated' 
    options.delete(:dedicated_tenancy)
  end

  options[:placement] = placement unless placement.empty?

  if subnet_id = subnet_id_option(options)
    options[:subnet_id] = subnet_id
  end

  security_group_opts(options)

  options[:client_token] = UUIDTools::UUID.timestamp_create.to_s

  resp = client.run_instances(options)

  if options[:min_count] == options[:max_count] and
      options[:min_count] == 1
    self[resp.instances_set.first.instance_id]
  else
    resp.instances_set.map do |i|
      self[i.instance_id]
    end
  end
end

#each {|Instance| ... } ⇒ Object

Yields:

  • (Instance) —

    Yields each instance in the collection.



262
263
264
265
266
267
268
269
 
# File 'lib/aws/ec2/instance_collection.rb', line 262

def each(&block)
  response = filtered_request(:describe_instances)
  response.reservation_set.each do |reservation|
    reservation.instances_set.each do |i|
      yield(Instance.new(i.instance_id, :config => config))
    end
  end
end