Class AWS::EC2::InstanceCollection
In: lib/aws/ec2/instance_collection.rb
Parent: Collection

Represents a collection of EC2 instances. Typically you should get an instance of this class by calling {EC2#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 }

Methods

[]   create   each   member_class   run  

Included Modules

TaggedCollection BlockDeviceMappings

Public Instance methods

[](id)

@return [Instance] Returns an object representing the EC2 instance 

  with the given ID.
create(options = {})

Runs one or more EC2 instances.

@example Running a single instance 

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

@example Running multiple instances with the same parameters 

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

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

@example 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
      }
    }
  })

@param [Hash] options Options for new instance. +:image_id+ is 

  the only required option.

@option options :count 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.

@option options [Hash] :block_device_mappings 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.

@option options [Boolean] :monitoring Setting this to true 

  enables CloudWatch monitoring on the instances once they
  are started.

@option options [String] :availability_zone Specifies the 

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

@option options [String] :image_id ID of the AMI you want to 

  launch.

@option options [String] :key_name The name of the key pair to 

  use.  Note: Launching public images without a key pair ID
  will leave them inaccessible.

@option options [Array] :security_groups The names of the 

  security groups that will be used to determine network
  access rules for the instances.  You may pass instances of
  {SecurityGroup} as well.

@option options [String] :user_data Arbitrary user data. You 

  do not need to encode this value.

@option options [String] :instance_type The type of instance to 

  launch, for example "m1.small".

@option options [String] :kernel_id The ID of the kernel with 

  which to launch the instance.

@option options [String] :ramdisk_id 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.

@option options [Boolean] :disable_api_termination 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

@option options [String] :instance_initiated_shutdown_behavior 

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

@return [Instance or Array] If a single instance is being created, 

  this returns an {EC2::Instance} to represent the newly
  created instance.  Otherwise it returns an array of instance
  objects.
run(options = {})

Alias for create

Protected Instance methods

[Validate]