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