class AWS::EC2::ImageCollection

Represents a collection of EC2 images. You can use this to find out which images exist with the characteristics you are interested in:

ec2 = EC2.new
all_images = ec2.images
amazon_owned_images = all_images.with_owner('amazon')
my_images = all_images.with_owner('self')
tagged_amis = all_images.tagged('mytag')
tagged_amis.map(&:id)   # => ["ami-123", ...]

You can also use it to create new images. For example:

ec2.images.create(:instance_id => "i-123", :name => "my-image")

Public Class Methods

new(options = {}) click to toggle source

@api private

Calls superclass method AWS::EC2::FilteredCollection.new
# File lib/aws/ec2/image_collection.rb, line 38
def initialize(options = {})
  @owners = options[:owners] || []
  @executable_users = options[:executable_users] || []
  super(options)
end

Public Instance Methods

[](image_id) click to toggle source

@return [Image] image_id The ID of the image.

Calls superclass method AWS::EC2::Collection#[]
# File lib/aws/ec2/image_collection.rb, line 45
def [] image_id
  super
end
create(options = {}) click to toggle source

Creates an AMI. There are several ways to create an AMI using this method; for detailed information on each strategy see [the EC2 Developer Guide](docs.amazonwebservices.com/AWSEC2/latest/UserGuide/creating-an-ami.html).

@param [Hash] options Options for creating the image.

`:name` is required, and you must also specify one of the
following options:

  * `:instance_id`
  * `:image_location`
  * `:root_device_name`

@option options [String] :instance_id The ID of a running

instance.  This instance will be rebooted unless
`:no_reboot` is set to `true`.

@option options [String] :description A description of the

new image.

@option options [Boolean] :no_reboot By default this

option is set to `false`, which means Amazon EC2
attempts to cleanly shut down the instance before image
creation and reboots the instance afterwards. When the
option is set to `true`, Amazon EC2 does not shut down
the instance before creating the image. When this option
is used, file system integrity on the created image cannot
be guaranteed.

*Note*: This option is only valid when used with
`:instance_id`.

@option options [String] :image_location Full path to your

AMI manifest in Amazon S3 storage.  This must be of the
form "bucket_name/key".

@option options [String] :architecture The architecture of

the image.  Valid values:

  * `:i386`
  * `:x86_64`

*Note*: This option is only valid with `:image_location`
or `:root_device_name`

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

select.

*Note*: This option is only valid with `:image_location`
or `:root_device_name`

@option options [Image] :kernel The kernel image to use.

Equivalent to passing `:kernel_id` with the ID of the
image.

*Note*: This option is only valid with `:image_location`
or `:root_device_name`

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

*Note*: This option is only valid with %x:image_location`
or %x:root_device_name`

@option options [Image] :ramdisk The ramdisk image to use.

Equivalent to passing `:ramdisk_id` with the ID of the
image.

*Note*: This option is only valid with `:image_location`
or `:root_device_name`

@option options [String] :root_device_name The root device

name (e.g., /dev/sda1, or xvda).

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

@return [Image]

# File lib/aws/ec2/image_collection.rb, line 182
def create options = {}
  resp = case
  when options[:instance_id]
    client.create_image(options)
  when options[:image_location] || options[:root_device_name]
    if kernel = options.delete(:kernel)
      options[:kernel_id] = kernel.id
    end
    if ramdisk = options.delete(:ramdisk)
      options[:ramdisk_id] = ramdisk.id
    end
    options[:block_device_mappings] =
      translate_block_device_mappings(options[:block_device_mappings]) if
      options[:block_device_mappings]
    client.register_image(options)
  else
    raise(ArgumentError,
          "expected instance_id, image_location, " +
          "or root_device_name")
  end
  Image.new(resp.image_id, :config => config)
end
each() { |image| ... } click to toggle source

@yield [image] Each image in the collection. @return [nil]

# File lib/aws/ec2/image_collection.rb, line 75
def each &block
  opts = {}
  opts[:owners] = @owners.map { |id| id.to_s } unless @owners.empty?
  opts[:executable_users] = @executable_users.map { |id| id.to_s } unless
    @executable_users.empty?
  response = filtered_request(:describe_images, opts)
  response.images_set.each do |i|
    image = Image.new_from(:describe_images, i, i.image_id, :config => config)
    yield(image)
  end
  nil
end
executable_by(*users) click to toggle source

@return [ImageCollection] A new collection that only includes

images for which the specified user ID has explicit launch
permissions. The user ID can be an AWS account ID, `:self`
to return AMIs for which the sender of the request has
explicit launch permissions, or `:all` to return AMIs with
public launch permissions.

@param [Array of Strings] users The AWS account IDs by which

the new collection should be filtered.
# File lib/aws/ec2/image_collection.rb, line 69
def executable_by(*users)
  collection_with(:executable_users => @executable_users + users)
end
with_owner(*owners) click to toggle source

@return [ImageCollection] A new collection that only includes

images owned by one or more of the specified AWS accounts.
The IDs `:amazon` and `:self` can be used to include AMIs
owned by Amazon or AMIs owned by you, respectively.

@param [Array of Strings] owners The AWS account IDs by

which the new collection should be filtered.
# File lib/aws/ec2/image_collection.rb, line 56
def with_owner(*owners)
  collection_with(:owners => @owners + owners)
end

Protected Instance Methods

member_class() click to toggle source

@api private

# File lib/aws/ec2/image_collection.rb, line 207
def member_class
  Image
end
preserved_options() click to toggle source

@api private

# File lib/aws/ec2/image_collection.rb, line 213
def preserved_options
  super.merge(:owners => @owners, :executable_users => @executable_users)
end