Class: AWS::EC2::InstanceCollection

Inherits:

Collection

• Object
• Collection
• AWS::EC2::InstanceCollection

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

• #[](id) ⇒ Instance

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

• #create(options = {}) ⇒ Instance or Array (also: #run)

  Runs one or more EC2 instances.

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

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.

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

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

# 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