aws-sdk 1.8.5 → 1.9.0

data/lib/aws/ec2/image_collection.rb

@@ -18,17 +18,16 @@ module AWS
     # 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", ...]
+    #     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")
+    #     ec2.images.create(:instance_id => "i-123", :name => "my-image")
     #
     class ImageCollection < Collection
 
@@ -49,7 +48,7 @@ module AWS
 
       # @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
+      #   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
@@ -60,9 +59,9 @@ module AWS
 
       # @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+
+      #   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
+      #   explicit launch permissions, or `:all` to return AMIs with
       #   public launch permissions.
       #
       # @param [Array of Strings] users The AWS account IDs by which
@@ -88,35 +87,34 @@ module AWS
 
       # 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].
+      # 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
+      #   `:name` is required, and you must also specify one of the
       #   following options:
       #
-      #   * +:instance_id+
-      #   * +:image_location+
-      #   * +:root_device_name+
+      #     * `: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+.
+      #   `: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
+      #   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
+      #   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+.
+      #   `:instance_id`.
       #
       # @option options [String] :image_location Full path to your
       #   AMI manifest in Amazon S3 storage.  This must be of the
@@ -125,24 +123,24 @@ module AWS
       # @option options [String] :architecture The architecture of
       #   the image.  Valid values:
       #
-      #   * +:i386+
-      #   * +:x86_64+
+      #     * `:i386`
+      #     * `:x86_64`
       #
-      #   *Note*: This option is only valid with +:image_location+
-      #   or +:root_device_name+
+      #   *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+
+      #   *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
+      #   Equivalent to passing `:kernel_id` with the ID of the
       #   image.
       #
-      #   *Note*: This option is only valid with +:image_location+
-      #   or +:root_device_name+
+      #   *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
@@ -151,15 +149,15 @@ module AWS
       #   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+
+      #   *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
+      #   Equivalent to passing `:ramdisk_id` with the ID of the
       #   image.
       #
-      #   *Note*: This option is only valid with +:image_location+
-      #   or +:root_device_name+
+      #   *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).
@@ -169,23 +167,17 @@ module AWS
       #   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.
+      #     * 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

data/lib/aws/ec2/instance.rb

@@ -25,11 +25,11 @@ module AWS
     #   The instance must be in a stopped state to change user data;
     #   for example:
     #
-    #     i.user_data             # => "HELLO"
-    #     i.status                # => :running
-    #     i.user_data = "GOODBYE" # raises an exception
-    #     i.stop; sleep 1 until i.status == :stopped
-    #     i.user_data = "GOODBYE" # => "GOODBYE"
+    #       i.user_data             # => "HELLO"
+    #       i.status                # => :running
+    #       i.user_data = "GOODBYE" # raises an exception
+    #       i.stop; sleep 1 until i.status == :stopped
+    #       i.user_data = "GOODBYE" # => "GOODBYE"
     #
     # @attr [String] instance_type The instance type,
     #   e.g. "m1.small".  The instance must be in a stopped state to
@@ -45,11 +45,10 @@ module AWS
     # @attr [String] instance_initiated_shutdown_behavior Valid
     #   values are:
     #
-    #   ["stop"] When the instance shuts down, it will go into a
-    #            "stopped" state.
-    #
-    #   ["terminate"] When the instance shuts down, it will be
-    #                 terminated.
+    #     * "stop"] When the instance shuts down, it will go into a
+    #       "stopped" state.
+    #     * "terminate"] When the instance shuts down, it will be
+    #       terminated.
     #
     # @attr_reader [String] image_id Image ID of the AMI used to
     #   launch the instance.
@@ -68,8 +67,9 @@ module AWS
     # @attr_reader [Symbol] root_device_type The root device type
     #   used by the AMI. The AMI can use an Amazon EBS or instance
     #   store root device.  Valid values:
-    #   * +:ebs+
-    #   * +:instance_store+
+    #
+    #     * `:ebs`
+    #     * `:instance_store`
     #
     # @attr_reader [String] root_device_name The name of the root
     #   device.
@@ -90,23 +90,25 @@ module AWS
     # @attr_reader [String] ip_address The IP address of the
     #   instance.
     #
-    # @attr_reader [Symbol] status The instance status.  Valid values are:
-    #   * +:pending+
-    #   * +:running+
-    #   * +:shutting_down+
-    #   * +:terminated+
-    #   * +:stopping+
-    #   * +:stopped+
+    # @attr_reader [Symbol] status The instance status.
+    #   Valid values are:
+    #
+    #     * `:pending`
+    #     * `:running`
+    #     * `:shutting_down`
+    #     * `:terminated`
+    #     * `:stopping`
+    #     * `:stopped`
     #
     # @attr_reader [Integer] status_code The numeric instance status code.
     #
-    # @attr_reader [Symbol] architecture The architecture of the
-    #   image.
+    # @attr_reader [Symbol] architecture The architecture of the image.
     #
     # @attr_reader [Symbol] virtualization_type The instance's
     #   virtualization type.  Valid values:
-    #   * +:paravirtual+
-    #   * +:hvm+
+    #
+    #     * `:paravirtual`
+    #     * `:hvm`
     #
     # @attr_reader [String] reservation_id The ID of the reservation
     #   in which this instance was launched.
@@ -120,9 +122,10 @@ module AWS
     #
     # @attr_reader [Symbol] monitoring The status of CloudWatch
     #   monitoring for the instance.  Valid values:
-    #   * +:enabled+
-    #   * +:disabled+
-    #   * +:pending+
+    #
+    #     * `:enabled`
+    #     * `:disabled`
+    #     * `:pending`
     #
     # @attr_reader [String] state_transition_reason A string
     #   describing the reason for the last state transition.
@@ -135,8 +138,9 @@ module AWS
     #
     # @attr_reader [Symbol] hypervisor The instance's hypervisor
     #   type.  Valid values:
-    #   * +:ovm+
-    #   * +:xen+
+    #
+    #     * `:ovm`
+    #     * `:xen`
     #
     # @attr_reader [String] client_token Idempotency token you
     #   provided when you launched the instance.
@@ -458,22 +462,22 @@ module AWS
 
       # Returns a list of block device mappings.
       #
-      #   instance.block_devices
-      #   #=>
-      #   [
-      #     {
-      #       :device_name => "/dev/sda2",
-      #       :ebs => {
-      #         :volume_id => "vol-123",
-      #         :status => "attaching",
-      #         :attach_time => time,
-      #         :delete_on_termination => true
+      #     instance.block_devices
+      #     #=>
+      #     [
+      #       {
+      #         :device_name => "/dev/sda2",
+      #         :ebs => {
+      #           :volume_id => "vol-123",
+      #           :status => "attaching",
+      #           :attach_time => time,
+      #           :delete_on_termination => true
+      #         }
+      #       }, {
+      #         :device_name => "/dev/sdb",
+      #         :virtual_name => "ephemeral0",
       #       }
-      #     }, {
-      #       :device_name => "/dev/sdb",
-      #       :virtual_name => "ephemeral0",
-      #     }
-      #   ]
+      #     ]
       #
       # @return [Array<Hash>] Returns a list of block device mappings.  This
       #   list may contain ephemeral volumes.
@@ -502,7 +506,7 @@ module AWS
         state ? enable_monitoring : disable_monitoring
       end
 
-      # @return [Booelan] Returns +true+ if CloudWatch monitoring is
+      # @return [Booelan] Returns `true` if CloudWatch monitoring is
       #   enabled for this instance.
       def monitoring_enabled?
         monitoring == :enabled
@@ -550,17 +554,15 @@ module AWS
       #   parenthesis (()), commas (,), slashes (/), dashes (-), or
       #   underscores(_)
       #
-      # @param [Hash] options Additional options for creating the
-      #   image.
+      # @param [Hash] options Additional options for creating the image.
       #
-      # @option options [String] :description A description of the
-      #   new image.
+      # @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
+      #   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
+      #   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.
@@ -685,28 +687,28 @@ module AWS
       # virtualization environment and then writes the image to a
       # S3 bucket.
       #
-      # == Granting EC2 write access to your bucket
+      # ## Granting EC2 write access to your bucket
       #
       # Before you can export an image to an S3 bucket, you must modify
       # the bucket ACL.  You only need to do this once per bucket.
       #
-      #   s3.buckets['bucket-name'].acl.change do |acl|
-      #     acl.grant(:read_acp).to(:amazon_customer_email => 'vm-import-export@amazon.com')
-      #     acl.grant(:write).to(:amazon_customer_email => 'vm-import-export@amazon.com')
-      #   end
+      #     s3.buckets['bucket-name'].acl.change do |acl|
+      #       acl.grant(:read_acp).to(:amazon_customer_email => 'vm-import-export@amazon.com')
+      #       acl.grant(:write).to(:amazon_customer_email => 'vm-import-export@amazon.com')
+      #     end
       #
-      # == Performing the export
+      # ## Performing the export
       #
       # Simply call #export_to_s3 on your instance.   Only instances
       # derived from your own ImportInstance tasks may be exported.
       #
-      #    task = ec2.instances['i-12345678'].export_to_s3('bucket-name')
+      #      task = ec2.instances['i-12345678'].export_to_s3('bucket-name')
       #
-      # == Downloading the results
+      # ## Downloading the results
       #
       # Given a completed export task you can download the final image:
       #
-      #   File.open('image.ova', 'w') {|f| f.write(task.s3_object.read) }
+      #     File.open('image.ova', 'w') {|f| f.write(task.s3_object.read) }
       #
       # @param [S3::Bucket,String] bucket The destination bucket.  May
       #   be the name of the bucket (string) or a {S3::Bucket} object. The
@@ -720,13 +722,13 @@ module AWS
       #   and 'microsoft'.
       #
       # @option options [String] :disk_image_format The format for the exported
-      #    image.  Defaults to 'vmdk' if +:target_environemnt+ is 'vmware',
+      #    image.  Defaults to 'vmdk' if `:target_environemnt` is 'vmware',
       #    otherwise, 'vhd'.
       #
       # @option options [String] :container_format The container format used to
       #   combine disk images with metadata (such as OVF). If absent, only
       #   the disk image will be exported.  Defaults to 'ova' if
-      #   +:target_environment+ is 'vmware', otherwise ommited.
+      #   `:target_environment` is 'vmware', otherwise ommited.
       #
       # @option options [String] :description Description of the conversion
       #   task or the resource being exported.
@@ -734,7 +736,7 @@ module AWS
       # @option options [String] :prefix (nil) The image is written to a
       #   single object in the bucket at the key:
       #
-      #     "#{prefix}#{export_task_id}.#{disk_image_format}"
+      #       "#{prefix}#{export_task_id}.#{disk_image_format}"
       #
       # @return [ExportTask]
       #

data/lib/aws/ec2/instance_collection.rb

@@ -17,24 +17,23 @@ require 'uuidtools'
 module AWS
   class EC2
 
-    ##
     # 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")
+    #     ec2.instances.create(:image_id => "ami-1b814f72")
     #
     # To get an instance by ID:
     #
-    #   i = ec2.instances["i-12345678"]
-    #   i.exists?
+    #     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 }
+    #      ec2.instances.inject({}) { |m, i| m[i.id] = i.status; m }
+    #     # => { "i-12345678" => :running, "i-87654321" => :shutting_down }
     #
     class InstanceCollection < Collection
 
@@ -53,7 +52,7 @@ module AWS
       #     :image_id => "ami-8c1fece5",
       #     :count => 10)
       #
-      #  sleep 1 while instances.any? {|i| i.status == :pending }
+      #   sleep 1 while instances.any? {|i| i.status == :pending }
       #
       # @example Specifying block device mappings
       #
@@ -73,7 +72,7 @@ module AWS
       #     :image_id => "ami-8c1fece5",
       #     :subnet => "subnet-abc123ef")
       #
-      # @param [Hash] options Options for new instance.  +:image_id+ is
+      # @param [Hash] options Options for new instance.  `:image_id` is
       #   the only required option.
       #
       # @option options [Integer] :count How many instances to request.  By
@@ -87,34 +86,31 @@ module AWS
       #   ARN of an IAM instance profile.  This provides credentials
       #   to the EC2 instance(s) via the instance metadata service.
       #
-      # @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 [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
+      #   `true` enables CloudWatch monitoring on the instances once they
       #   are started.
       #
       # @option options [String] :availability_zone Specifies the
@@ -133,12 +129,12 @@ module AWS
       #
       # @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.
+      #   `: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
+      #   `:security_group_ids` accepts a single ID or an array of security
       #   group IDs.
       #
       # @option options [String] :user_data Arbitrary user data.  You
@@ -165,12 +161,12 @@ module AWS
       #   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
+      #       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
@@ -192,13 +188,13 @@ module AWS
       #   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 
+      # @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. 
+      #   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.
       #
@@ -242,9 +238,10 @@ module AWS
         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]
+        if options[:block_device_mappings].is_a?(Hash)
+          options[:block_device_mappings] =
+            translate_block_device_mappings(options[:block_device_mappings])
+        end
 
         options[:monitoring] = { :enabled => true } if
           options[:monitoring_enabled]