aws-sdk-v1 1.52.0

data/lib/aws/ec2/image.rb

@@ -0,0 +1,270 @@
+# Copyright 2011-2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  class EC2
+
+    # Represents an Amazon Machine Image (AMI).
+    #
+    # @attr_reader [String] name The name of the AMI that was provided
+    #   during image creation.
+    #
+    # @attr [String] description A description of the image.
+    #
+    # @attr_reader [String] location The location of the AMI.
+    #
+    # @attr_reader [Symbol] state Current state of the AMI. If the
+    #   state is `:available`, the image is successfully registered
+    #   and available for launching.  Valid values:
+    #
+    #     * `:available`
+    #     * `:pending`
+    #     * `:failed`
+    #
+    # @attr_reader [String] owner_id The AWS account ID of the image owner.
+    #
+    # @attr_reader [String] owner_alias The AWS account alias (e.g.,
+    #   `"amazon"`) or AWS account ID that owns the AMI.
+    #
+    # @attr_reader [Symbol] architecture The architecture of the
+    #   image (e.g. `:i386`).
+    #
+    # @attr_reader [Symbol] type The type of image.
+    #   Valid values are:
+    #
+    #     * `:machine`
+    #     * `:kernel`
+    #     * `:ramdisk`
+    #
+    # @attr_reader [String] kernel_id The kernel ID associated with
+    #   the image, if any. Only applicable for machine images.
+    #
+    # @attr_reader [String] ramdisk_id The RAM disk ID associated
+    #   with the image, if any. Only applicable for machine images.
+    #
+    # @attr_reader [String] platform Value is `windows` for Windows
+    #   AMIs; otherwise blank.
+    #
+    # @attr_reader [Object] state_reason The reason for the image's
+    #   most recent state change.  The return value is an object with
+    #   the following methods:
+    #
+    #     * `code` - Reason code for the state change.
+    #     * `message` - A textual description of the state change.
+    #
+    # @attr_reader [Symbol] root_device_type The root device type
+    #   used by the AMI. Possible values:
+    #
+    #     * `:ebs`
+    #     * `:instance_store`
+    #
+    # @attr_reader [String] root_device_name The root device name
+    #   (e.g., `"/dev/sda1"`, or `"xvda"`).
+    #
+    # @attr_reader [Symbol] virtualization_type The type of
+    #   virtualization of the AMI.  Possible values:
+    #
+    #     * `:paravirtual`
+    #     * `:hvm`
+    #
+    # @attr_reader [Symbol] hypervisor The image's hypervisor type.
+    #   Possible values are:
+    #
+    #     * `:ovm`
+    #     * `:xen`
+    #
+    # @attr_reader [Array<String>] product_codes Returns an array of
+    #   product codes attached to this instance.
+    #
+    class Image < Resource
+
+      include TaggedItem
+      include HasPermissions
+
+      # @param [String] image_id
+      def initialize image_id, options = {}
+        @image_id = image_id
+        super
+      end
+
+      # @return [String] The ID of the AMI.
+      attr_reader :image_id
+
+      alias_method :id, :image_id
+
+      attribute :name, :static => true
+
+      mutable_attribute :description
+
+      attribute :location, :from => :image_location, :static => true
+
+      attribute :state, :from => :image_state, :to_sym => true
+
+      attribute :owner_id, :from => :image_owner_id, :static => true
+
+      attribute :owner_alias, :from => :image_owner_alias, :static => true
+
+      attribute :architecture, :to_sym => true, :static => true
+
+      attribute :type, :from => :image_type, :to_sym => true, :static => true
+
+      attribute :kernel_id, :static => true
+
+      attribute :ramdisk_id, :static => true
+
+      attribute :platform, :static => true
+
+      attribute :state_reason
+
+      attribute :root_device_type, :to_sym => true, :static => true
+
+      attribute :root_device_name, :static => true
+
+      attribute :virtualization_type, :to_sym => true, :static => true
+
+      attribute :hypervisor, :to_sym => true, :static => true
+
+      attribute :block_device_mapping
+
+      protected :block_device_mapping
+
+      attribute :product_codes, :static => true do
+        translates_output do |list|
+          (list || []).collect{|item| item.product_code }
+        end
+      end
+
+      populates_from(:describe_images) do |resp|
+        resp.image_index[id]
+      end
+
+      alias_method :launch_permissions, :permissions
+
+      # @note This method will not return data for ephemeral volumes.
+      # @return [Hash] Returns a hash of block
+      #   device mappings for the image.  In each entry, the key is
+      #   the device name (e.g. `"/dev/sda1"`) and the value is an
+      #   hash with the following keys that return information
+      #   about the block device:
+      #
+      #     * `:snapshot_id` - The ID of the snapshot that will be used to
+      #       create this device (may be `nil`).
+      #     * `:volume_size` - The size of the volume, in GiBs.
+      #     * `:delete_on_termination` - True if the Amazon EBS volume is
+      #       deleted on instance termination.
+      #
+      # @see {#block_devices}
+      def block_device_mappings
+        (block_device_mapping || []).inject({}) do |h, mapping|
+          if ebs = mapping[:ebs]
+            h[mapping[:device_name]] = ebs
+          end
+          h
+        end
+      end
+
+      # @return [Array<Hash>] Returns a list of all block device mappings.
+      #   This list may contain ephemeral volumes.
+      def block_devices
+        block_device_mapping.to_a
+      end
+
+      # Deregisters this AMI. Once deregistered, the AMI cannot be
+      # used to launch new instances.
+      # @return [nil]
+      def deregister
+        client.deregister_image(:image_id => id)
+        nil
+      end
+
+      alias_method :delete, :deregister
+
+      # Runs a single instance of this image.
+      #
+      # @param [Hash] options
+      # @option (see InstanceCollection#create)
+      # @return (see InstanceCollection#create)
+      def run_instance options = {}
+        instances = InstanceCollection.new(:config => config)
+        instances.create(options.merge(:image => self))
+      end
+
+      # Runs multiple instances of this image.
+      #
+      # @param [Integer] count How many instances to request.  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
+      #   a time.
+      # @param [Hash] options
+      # @option (see InstanceCollection#create)
+      # @return [Array<Instance>] An array containing an {Instance} object for
+      #   each instance that was run.
+      def run_instances count, options = {}
+        run_instance(options.merge(:count => count))
+      end
+
+      # @return [Boolean] Returns `true` if the AMI exists (is returned by
+      #   the DescribeImages action).
+      def exists?
+        resp = client.describe_images(:filters => [
+          { :name => "image-id", :values => [id] }
+        ])
+        !resp.images_set.empty?
+      end
+
+      # @return [Image] The kernel associated with the image, if
+      #   any. Only applicable for machine images.
+      def kernel
+        if id = kernel_id
+          Image.new(id, :config => config)
+        end
+      end
+
+      # @return [Image] The RAM disk associated with the image, if
+      #   any. Only applicable for machine images.
+      def ramdisk
+        if id = ramdisk_id
+          Image.new(id, :config => config)
+        end
+      end
+
+      # Adds one or more product codes:
+      #
+      #     image.add_product_codes 'ABCXYZ', 'MNOPQR'
+      #
+      # You can also pass an array of product codes:
+      #
+      #     image.add_product_codes ['ABCXYZ', 'MNOPQR']
+      #
+      # @param [Array<String>] product_codes
+      #
+      # @return [nil]
+      #
+      def add_product_codes *product_codes
+        client_opts = {}
+        client_opts[:image_id] = self.id
+        client_opts[:product_codes] = product_codes.flatten
+        client.modify_image_attribute(client_opts)
+        nil
+      end
+
+      # @api private
+      def __permissions_attribute__
+        "launchPermission"
+      end
+
+    end
+
+  end
+end

data/lib/aws/ec2/image_collection.rb

@@ -0,0 +1,219 @@
+# Copyright 2011-2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  class EC2
+
+    # 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")
+    #
+    class ImageCollection < Collection
+
+      include TaggedCollection
+      include BlockDeviceMappings
+
+      # @api private
+      def initialize(options = {})
+        @owners = options[:owners] || []
+        @executable_users = options[:executable_users] || []
+        super(options)
+      end
+
+      # @return [Image] image_id The ID of the image.
+      def [] image_id
+        super
+      end
+
+      # @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.
+      def with_owner(*owners)
+        collection_with(:owners => @owners + owners)
+      end
+
+      # @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.
+      def executable_by(*users)
+        collection_with(:executable_users => @executable_users + users)
+      end
+
+      # @yield [image] Each image in the collection.
+      # @return [nil]
+      def each(opts = {}, &block)
+        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
+
+      # 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](http://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 `:image_location`
+      #   or `: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]
+      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
+
+      # @api private
+      protected
+      def member_class
+        Image
+      end
+
+      # @api private
+      protected
+      def preserved_options
+        super.merge(:owners => @owners, :executable_users => @executable_users)
+      end
+
+    end
+
+  end
+end