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-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 }

Methods

[]   create   each   member_class   run  

Included Modules

TaggedCollection BlockDeviceMappings

Public Instance methods

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

  with the given ID.

Runs one or more EC2 instances.

@example Running a single instance

  i = ec2.instances.create(:image_id => "ami-8c1fece5")
  sleep 10 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 => [{
      :device_name => "/dev/sda2",
      :ebs => {
        :volume_size => 15, # 15 GiB
        :delete_on_termination => true
      }
    }]
  })

@example Launching in an Amazon VPC subnet

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

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

  the only required option.

@option options [Integer] :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 [String] :iam_instance_profile The name or

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

@option options [Array<Hash>] :block_device_mappings Specifies how block

  devices are exposed to the instance. Each mapping is made up of a
  virtualName and a deviceName.

    * `:virtual_name` - (String) Specifies the virtual device name.
    * `:device_name` - (String) Specifies the device name (e.g.,
      /dev/sdh).
    * `:ebs` - (Hash) Specifies parameters used to automatically setup
      Amazon EBS volumes when the instance is launched.
      * `:snapshot_id` - (String) The ID of the snapshot from which the
        volume will be created.
      * `:volume_size` - (Integer) The size of the volume, in
        gigabytes.
      * `:delete_on_termination` - (Boolean) Specifies whether the
        Amazon EBS volume is deleted on instance termination.
      * `:volume_type` - (String) Valid values include:
        * `standard`
        * `io1`
      * `:iops` - (Integer)
    * `:no_device` - (String) Specifies the device name to suppress
      during instance launch.

@option options [Boolean] :monitoring_enabled 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 [KeyPair] :key_pair A {KeyPair} that should

  be used when launching an instance.

@option options [Array] :security_groups 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.

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

@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.

@option options [Subnet,String] :subnet (nil) The VPC Subnet (or

  subnet id string) to launch the instance in.

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

@option options [Boolean] :dedicated_tenancy (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).

@option options [Boolean] :ebs_optimized (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.

@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

@api private

[Validate]