Class: AWS::EC2::InstanceCollection

Inherits:
Collection show all
Includes:
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-1b814f72")

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 Method Summary collapse

Methods included from TaggedCollection

#tagged, #tagged_values

Methods included from FilteredCollection

#filter, #initialize

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.



299
300
301
# File 'lib/aws/ec2/instance_collection.rb', line 299

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 10 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 (Integer)

    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.

  • :iam_instance_profile (String)

    The name or ARN of an IAM instance profile. This provides credentials to the EC2 instance(s) via the instance metadata service.

  • :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_enabled (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.

  • :key_pair (KeyPair)

    A KeyPair that should be used when launching an instance.

  • :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).

  • :ebs_optimized (Boolean) — default: false

    EBS-Optimized instances enable Amazon EC2 instances to fully utilize the IOPS provisioned on an EBS volume. EBS-optimized instances deliver dedicated throughput between Amazon EC2 and Amazon EBS, with options between 500 Mbps and 1000 Mbps depending on the instance type used. When attached to EBS-Optimized instances, Provisioned IOPS volumes are designed to deliver within 10% of their provisioned performance 99.9% of the time. NOTE: EBS Optimized instances incur an additional service charge. This optional is only valid for certain instance types.

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.



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
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
# File 'lib/aws/ec2/instance_collection.rb', line 210

def create options = {}

  if profile = options.delete(:iam_instance_profile)
    profile = case profile
    when /^arn:aws:iam::/ then { :arn => profile }
    when String then { :name => profile }
    when Hash then profile
    else
      msg = "expected a name or ARN string for :iam_instance_profile"
    end
    options[:iam_instance_profile] = profile
  end

  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 {|i| self[i[:instance_id]] }
  end
end

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

Yields:

  • (Instance)

    Yields each instance in the collection.



288
289
290
291
292
293
294
295
# File 'lib/aws/ec2/instance_collection.rb', line 288

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