aws-sdk 1.5.4 → 1.5.5

data/lib/aws/ec2/export_task_collection.rb

@@ -0,0 +1,67 @@
+# Copyright 2011-2012 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
+
+    # = Getting Export Tasks
+    #
+    # Allows you to enumerate export tasks.
+    #
+    #   ec2.export_tasks.each do |task|
+    #     # yield ExportTask objects
+    #   end
+    #
+    # You can also get an export task by id
+    #
+    #   task = ec2.export_tasks['export-task-id']
+    #
+    # = Creating Export Tasks
+    #
+    # To create an export task you start with the {Instance}:
+    #
+    #   task = ec2.instances['i-12345678'].export_to_s3('bucket-name')
+    #
+    # See {Instance#export_to_s3} for more options.
+    # 
+    class ExportTaskCollection < Collection
+
+      include Core::Collection::Simple
+
+      # @param [String] export_task_id
+      # @return [ExportTask] Returns reference to the export task with the
+      #   given export task id.
+      def [] export_task_id
+        ExportTask.new(export_task_id, :config => config)
+      end
+
+      protected
+
+      def _each_item options = {}, &block
+        resp = filtered_request(:describe_export_tasks, options, &block)
+        resp.data[:export_task_set].each do |details|
+          
+          task = ExportTask.new_from(
+            :describe_export_tasks, 
+            details,
+            details[:export_task_id], 
+            :config => config)
+
+          yield(task)
+
+        end
+      end
+
+    end
+  end
+end

data/lib/aws/ec2/instance.rb

@@ -647,6 +647,87 @@ module AWS
         instance_action :stop
       end
 
+      # This produces an image of an EC2 instance for use in another
+      # virtualization environment and then writes the image to a
+      # S3 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
+      #
+      # == 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')
+      #
+      # == 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) }
+      #
+      # @param [S3::Bucket,String] bucket The destination bucket.  May
+      #   be the name of the bucket (string) or a {S3::Bucket} object. The 
+      #   bucket must exist and grant write permissiosn to the AWS account
+      #   'vm-import-export@amazon.com.'.
+      #
+      # @param [Hash] options
+      #
+      # @option options [String] :target_environment ('vmware') The target 
+      #   virtualization environment.  Valid values include: 'vmware', 'citrix'
+      #   and 'microsoft'.
+      #
+      # @option options [String] :disk_image_format The format for the exported
+      #    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.
+      #
+      # @option options [String] :description Description of the conversion 
+      #   task or the resource being exported.
+      #
+      # @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}"
+      #
+      # @return [ExportTask]
+      #
+      def export_to_s3 bucket, options = {}
+
+        bucket_name = bucket.is_a?(S3::Bucket) ? bucket.name : bucket.to_s
+
+        opts = {}
+        opts[:instance_id] = instance_id
+        opts[:description] = options[:description] if options[:description]
+        opts[:target_environment] = options[:target_environment] || 'vmware'
+        opts[:export_to_s3] = {}
+        opts[:export_to_s3][:s3_bucket] = bucket_name
+        [:disk_image_format, :container_format, :s3_prefix].each do |opt|
+          opts[:export_to_s3][opt] = options[opt] if options.key?(opt)
+        end
+
+        resp = client.create_instance_export_task(opts)
+
+        ExportTask.new_from(
+          :create_instance_export_task, 
+          resp[:export_task],
+          resp[:export_task][:export_task_id], 
+          :config => config)
+
+      end
+
       protected
 
       def find_in_response resp

data/lib/aws/ec2/region.rb

@@ -77,6 +77,7 @@ module AWS
         :vpn_gateways,
         :dhcp_options,
         :vpn_connections,
+        :export_tasks,
       ]
 
       PROXIED_METHODS.each do |method|

data/lib/aws/record/model.rb

@@ -27,7 +27,7 @@ module AWS
     #
     #     string_attr :title
     #     string_attr :author
-    #     integer :number_of_pages
+    #     integer_attr :number_of_pages
     #
     #     timestamps # adds a :created_at and :updated_at pair of timestamps
     #

data/lib/aws/s3.rb

@@ -97,6 +97,7 @@ module AWS
     AWS.register_autoloads(self) do
       autoload :AccessControlList,            'access_control_list'
       autoload :ACLObject,                    'acl_object'
+      autoload :ACLOptions,                   'acl_options'
       autoload :Bucket,                       'bucket'
       autoload :BucketCollection,             'bucket_collection'
       autoload :BucketLifecycleConfiguration, 'bucket_lifecycle_configuration'

data/lib/aws/s3/access_control_list.rb

@@ -98,13 +98,17 @@ module AWS
       class Grantee
         include ACLObject
 
-        SIGNAL_ATTRIBUTES = [:amazon_customer_email,
-                             :canonical_user_id,
-                             :group_uri]
+        SIGNAL_ATTRIBUTES = [
+          :amazon_customer_email,
+          :canonical_user_id,
+          :group_uri,
+          :uri,
+        ]
 
         string_attr "EmailAddress", :method_name => "amazon_customer_email"
         string_attr "ID", :method_name => "canonical_user_id"
         string_attr "URI", :method_name => "group_uri"
+        string_attr "URI", :method_name => "uri"
         string_attr "DisplayName"
 
         # (see ACLObject#validate!)
@@ -133,9 +137,12 @@ module AWS
 
         # @private
         def type_for_attr(attr)
-          { :amazon_customer_email => "AmazonCustomerByEmail",
+          { 
+            :amazon_customer_email => "AmazonCustomerByEmail",
             :canonical_user_id => "CanonicalUser",
-            :group_uri => "Group" }[attr]
+            :group_uri => "Group",
+            :uri => "Group",
+          }[attr]
         end
 
       end

data/lib/aws/s3/acl_options.rb

@@ -0,0 +1,204 @@
+# Copyright 2011-2012 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.
+
+require 'rexml/document'
+
+module AWS
+  class S3
+
+    # Provides a method to {Bucket} and {S3Object} that parses a wide
+    # range of ACL options.
+    # @private
+    module ACLOptions
+
+      protected
+
+      # @param [Symbol,String,Hash,AccessControlList] acl Accepts an ACL 
+      #   description in one of the following formats:
+      #
+      #   ==== Canned ACL
+      #
+      #   S3 supports a number of canned ACLs for buckets and
+      #   objects.  These include:
+      #
+      #   * +:private+
+      #   * +:public_read+
+      #   * +:public_read_write+
+      #   * +:authenticated_read+
+      #   * +:bucket_owner_read+ (object-only)
+      #   * +:bucket_owner_full_control+ (object-only)
+      #   * +:log_delivery_write+ (bucket-only)
+      #
+      #   Here is an example of providing a canned ACL to a bucket:
+      # 
+      #     s3.buckets['bucket-name'].acl = :public_read
+      #
+      #   ==== ACL Grant Hash
+      #
+      #   You can provide a hash of grants.  The hash is composed of grants (keys)
+      #   and grantees (values).  Accepted grant keys are:
+      #
+      #   * +:grant_read+
+      #   * +:grant_write+
+      #   * +:grant_read_acp+
+      #   * +:grant_write_acp+
+      #   * +:grant_full_control+
+      #
+      #   Grantee strings (values) should be formatted like some of the 
+      #   following examples:
+      #
+      #     id="8a6925ce4adf588a4532142d3f74dd8c71fa124b1ddee97f21c32aa379004fef"
+      #     uri="http://acs.amazonaws.com/groups/global/AllUsers"
+      #     emailAddress="xyz@amazon.com"
+      #
+      #   You can provide a comma delimited list of multiple grantees in a single
+      #   string.  Please note the use of quotes inside the grantee string.
+      #   Here is a simple example:
+      #
+      #     {
+      #       :grant_full_control => "emailAddress=\"foo@bar.com\", id=\"abc..mno\""
+      #     }
+      #
+      #   See the S3 API documentation for more information on formatting
+      #   grants.
+      #
+      #   ==== AcessControlList Object
+      #
+      #   You can build an ACL using the {AccessControlList} class and 
+      #   pass this object.
+      #
+      #     acl = AWS::S3::AccessControlList.new
+      #     acl.grant(:full_control).to(:canonical_user_id => "8a6...fef")
+      #     acl #=> this is acceptible
+      #
+      #   ==== ACL XML String
+      #
+      #   Lastly you can build your own ACL XML document and pass it as a string.
+      #
+      #     <<-XML
+      #       <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+      #         <Owner>
+      #           <ID>8a6...fef</ID>
+      #           <DisplayName>owner-display-name</DisplayName>
+      #         </Owner>
+      #         <AccessControlList>
+      #           <Grant>
+      #             <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Canonical User">
+      #               <ID>8a6...fef</ID>
+      #               <DisplayName>owner-display-name</DisplayName>
+      #             </Grantee>
+      #             <Permission>FULL_CONTROL</Permission>
+      #           </Grant>
+      #         </AccessControlList>
+      #       </AccessControlPolicy> 
+      #     XML
+      #
+      # @return [Hash] Returns a hash of options suitable for
+      #   passing to {Client#put_bucket_acl} and {Client#put_object_acl}
+      #   with a mixture of ACL options.
+      #
+      def acl_options acl
+        case acl
+        when Symbol
+          { :acl => acl.to_s.tr('_', '-') }
+        when String
+          # Strings are either access control policies (xml strings)
+          # or they are canned acls
+          xml?(acl) ?
+            { :access_control_policy => acl } :
+            { :acl => acl }
+        when AccessControlList
+            { :access_control_policy => acl.to_xml }
+        when Hash
+          # Hashes are either grant hashes or constructor args for an
+          # access control list (deprecated)
+          grant_hash?(acl) ?
+            format_grants(acl) :
+            { :access_control_policy => AccessControlList.new(acl).to_xml }
+        else
+          # failed to parse the acl option
+          msg = "expected a canned ACL, AccessControlList object, ACL "
+                "XML string or a grants hash"
+          raise ArgumentError, msg
+        end
+      end
+
+      # @param [Hash] acl_hash
+      # @return [Boolean] Retursn +true+ if this hash is a hash of grants.
+      def grant_hash? acl_hash
+        grant_keys = [
+          :grant_read,
+          :grant_write,
+          :grant_read_acp,
+          :grant_write_acp,
+          :grant_full_control,
+        ]
+        acl_hash.keys.all?{|key| grant_keys.include?(key) }
+      end
+
+      # @param [String] acl_string
+      # @return [Boolean] Returns +true+ if this string is an xml document.
+      def xml? acl_string
+        begin
+          REXML::Document.new(acl_string).has_elements?
+        rescue
+          false
+        end
+      end
+
+      # @param [Hash] acl_hash
+      # @return [Hash] Returns a hash of grant options suitable for
+      #   passing to the various S3 client methods that accept ACL grants.
+      def format_grants acl_hash
+        grants = {}
+        acl_hash.each_pair do |grant,grantees|
+          grantees = [grantees] unless grantees.is_a?(Array)
+          grants[grant] = grantees.map{|g| format_grantee(g) }.join(', ')
+        end
+        grants
+      end
+
+      def format_grantee grantee
+        case grantee
+        when String then grantee
+        when Hash
+
+          if grantee.keys.count != 1
+            msg = "grantee hashes must have exactly 1 key"
+            raise ArgumentError, msg
+          end
+
+          # A granee hash looks like:
+          #   { :id => 'abc...fec' }
+          #   { :uri => 'http://abc.com/foo' }
+          #   { :email_address => 'xyz@amazon.com }
+          #
+          # It needs to look like
+          #   'id="abc...fec"'
+          #   'uri="http://abc.com/foo"'
+          #   'emailAddress="xyz@amazon.com"'
+          type, token = grantee.to_a.flatten
+          type = type.to_s.split('_').map{|part| ucfirst(part) }.join
+          "#{type[0,1].downcase}#{type[1..-1]}=\"#{token}\""
+        else
+          raise ArgumentError, "grantees must be a string or a hash"
+        end
+      end
+
+      def ucfirst str
+        str[0,1].upcase + str[1..-1]
+      end
+
+    end
+  end
+end

data/lib/aws/s3/bucket.rb

@@ -27,6 +27,7 @@ module AWS
     class Bucket
 
       include Core::Model
+      include ACLOptions
 
       # @param [String] name
       # @param [Hash] options
@@ -212,18 +213,12 @@ module AWS
 
       end
 
-      # Sets the bucket's access control list.  +acl+ can be:
-      #
-      # * An XML policy as a string (which is passed to S3 uninterpreted)
-      # * An AccessControlList object
-      # * Any object that responds to +to_xml+
-      # * Any Hash that is acceptable as an argument to
-      #   AccessControlList#initialize.
-      # 
-      # @param [AccessControlList] acl
+      # Sets the bucket's ACL (access control list).  You can provide an ACL
+      # in a number of different formats.
+      # @param (see ACLOptions#acl_options)
       # @return [nil]
-      def acl=(acl)
-        client.set_bucket_acl(:bucket_name => name, :acl => acl)
+      def acl= acl
+        client.set_bucket_acl(acl_options(acl).merge(:bucket_name => name))
         nil
       end