aws-sdk 1.0.4 → 1.1.0

data/lib/aws/ec2/volume_collection.rb

@@ -30,7 +30,7 @@ module AWS
     #  volume.exists?
     #
     # @example Get a map of volume IDs to volume status
-    #   ec2.volumes.inject({}) { |m, v| m[i.id] = v.status; m }
+    #   ec2.volumes.inject({}) { |m, v| m[v.id] = v.status; m }
     #   # => { "vol-12345678" => :available, "vol-87654321" => :in_use }
     class VolumeCollection < Collection
 
@@ -41,8 +41,12 @@ module AWS
       def each(&block)
         resp = filtered_request(:describe_volumes)
         resp.volume_set.each do |v|
-          volume = Volume.new(v.volume_id, :config => config)
+
+          volume = Volume.new_from(:describe_volumes, v, 
+            v.volume_id, :config => config)
+
           yield(volume)
+
         end
         nil
       end
@@ -55,32 +59,32 @@ module AWS
       #
       # @return [Volume] An object representing the new volume.
       #
-      # @param [Hash] opts Options for creating the volume.
+      # @param [Hash] options Options for creating the volume.
       #   +:availability_zone+ and one of +:size+, +:snapshot+, or
       #   +:snapshot_id+ is required.
       #
-      # @option opts [Integer] :size The size of the volume, in
+      # @option options [Integer] :size The size of the volume, in
       #   GiBs.  Valid values: 1 - 1024.  If +:snapshot+ or
       #   +:snapshot_id+ is specified, this defaults to the size of
       #   the specified snapshot.
       #
-      # @option opts [Snapshot] :snapshot The snapshot from which to
+      # @option options [Snapshot] :snapshot The snapshot from which to
       #   create the new volume.
       #
-      # @option opts [String] :snapshot_id The ID of the snapshot
+      # @option options [String] :snapshot_id The ID of the snapshot
       #   from which to create the new volume.
       #
-      # @option opts [String, AvailabilityZone] :availability_zone
+      # @option options [String, AvailabilityZone] :availability_zone
       #   The Availability Zone in which to create the new volume.
       #   To get a list of the availability zones you can use, see
       #   {EC2#availability_zones}.
       # @return [Volume]
-      def create(opts = {})
-        if snapshot = opts.delete(:snapshot)
-          opts[:snapshot_id] = snapshot.id
+      def create options = {}
+        if snapshot = options.delete(:snapshot)
+          options[:snapshot_id] = snapshot.id
         end
-        resp = client.create_volume(opts)
-        Volume.new(resp.volume_id, :config => config)
+        resp = client.create_volume(options)
+        Volume.new_from(:create_volume, resp, resp.volume_id, :config => config)
       end
 
       # @private

data/lib/aws/errors.rb

@@ -51,7 +51,8 @@ module AWS
       #   that wrapped the service error.
       attr_reader :http_response
 
-      def initialize http_request, http_response, message = http_response.body
+      def initialize http_request = nil, http_response = nil, message = nil
+        message ||= http_response.body if http_response
         @http_request = http_request
         @http_response = http_response
         super(message)
@@ -97,10 +98,18 @@ module AWS
       # @return [Integer] The HTTP status code returned by the AWS service.
       attr_reader :code
 
-      def initialize(req, resp)
-        super(req, resp, message)
-        include_error_type
-        parse_body(resp.body)
+      def initialize(req = nil, resp = nil)
+        if req.kind_of?(String)
+          # makes it easier to test handling of modeled exceptions
+          super(nil, nil, req)
+          @message = req
+        elsif req and resp
+          super(req, resp, message)
+          include_error_type
+          parse_body(resp.body)
+        else
+          super()
+        end
       end
 
       def include_error_type

data/lib/aws/http/httparty_handler.rb

@@ -62,7 +62,7 @@ module AWS
         })
 
         if request.proxy_uri
-          opts[:http_proxyaddr] = request.proxy_uri.to_s
+          opts[:http_proxyaddr] = request.proxy_uri.host
           opts[:http_proxyport] = request.proxy_uri.port
         end
 
@@ -90,7 +90,7 @@ module AWS
 
         begin
           http_response = self.class.send(method, url, opts)
-        rescue Timeout::Error => e
+        rescue Timeout::Error, Errno::ETIMEDOUT => e
           response.timeout = true
         else
           response.body = http_response.body

data/lib/aws/iam.rb

@@ -0,0 +1,306 @@
+# Copyright 2011 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 'aws/common'
+require 'aws/inflection'
+require 'aws/service_interface'
+require 'aws/iam/client'
+require 'aws/iam/user_collection'
+require 'aws/iam/group_collection'
+require 'aws/iam/signing_certificate_collection'
+require 'aws/iam/server_certificate_collection'
+require 'aws/iam/account_alias_collection'
+require 'aws/iam/access_key_collection'
+
+module AWS
+
+  # This class is the starting point for working with 
+  # AWS Identity and Access Management (IAM).
+  #
+  # For more information about IAM:
+  #
+  # * {AWS Identity and Access Management}[http://aws.amazon.com/iam/]
+  # * {AWS Identity and Access Management Documentation}[http://aws.amazon.com/documentation/iam/]
+  #
+  # = Credentials
+  #
+  # You can setup default credentials for all AWS services via 
+  # AWS.config:
+  #
+  #   AWS.config(
+  #     :access_key_id => 'YOUR_ACCESS_KEY_ID',
+  #     :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
+  # 
+  # Or you can set them directly on the IAM interface:
+  #
+  #   iam = AWS::IAM.new(
+  #     :access_key_id => 'YOUR_ACCESS_KEY_ID',
+  #     :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
+  #
+  # = Account Summary
+  #
+  # You can get account level information about entity usage and IAM quotas
+  # directly from an IAM interface object.
+  #
+  #   summary = iam.account_summary
+  #
+  #   puts "Num users: #{summary[:users]}"
+  #   puts "Num user quota: #{summary[:users_quota]}"
+  #
+  # For a complete list of summary attributes see the {#account_summary} method.
+  #
+  # = Account Aliases
+  #
+  # Currently IAM only supports a single account alias for each AWS account.
+  # You can set the account alias on the IAM interface.
+  #
+  #   iam.account_alias = 'myaccountalias'
+  #   iam.account_alias
+  #   #=> 'myaccountalias'
+  #
+  # You can also remove your account alias:
+  #
+  #   iam.remove_account_alias
+  #   iam.account_alias
+  #   #=> nil
+  #
+  # = Access Keys
+  #
+  # You can create up to 2 access for your account and 2 for each user.
+  # This makes it easy to rotate keys if you need to.  You can also
+  # deactivate/activate access keys.
+  #
+  #   # get your current access key
+  #   old_access_key = iam.access_keys.first
+  #
+  #   # create a new access key
+  #   new_access_key = iam.access_keys.create
+  #   new_access_key.credentials
+  #   #=> { :access_key_id => 'ID', :secret_access_key => 'SECRET' }
+  #
+  #   # go rotate your keys/credentials ...
+  #
+  #   # now disable the old access key
+  #   old_access_key.deactivate!
+  #
+  #   # go make sure everything still works ...
+  #
+  #   # all done, lets clean up
+  #   old_access_key.delete
+  #
+  # Users can also have access keys:
+  #
+  #   u = iam.users['someuser']
+  #   access_key = u.access_keys.create
+  #   access_key.credentials
+  #   #=> { :access_key_id => 'ID', :secret_access_key => 'SECRET' }
+  #
+  # See {AccessKeyCollection} and {AccessKey} for more information about
+  # working with access keys.
+  #
+  # = Users & Gropus
+  #
+  # Each AWS account can have multiple users.  Users can be used to easily
+  # manage permissions.  Users can also be organized into groups.  
+  #
+  #   user = iam.users.create('JohnDoe')
+  #   group = iam.groups.create('Developers')
+  #
+  #   # add a user to a group
+  #   user.groups.add(group)
+  #
+  #   # remove a user from a group
+  #   user.groups.remove(group)
+  #
+  #   # add a user to a group
+  #   group.users.add(user)
+  #
+  #   # remove a user from a group
+  #   group.users.remove(user)
+  #
+  # See {User}, {UserCollection}, {Group} and {GroupCollection} for more
+  # information on how to work with users and groups.
+  #
+  # = Other Interfaces
+  #
+  # Other useful IAM interfaces:
+  # * User Login Profiles ({LoginProfile})
+  # * Policies ({Policy})
+  # * Server Certificates ({ServerCertificateCollection}, {ServerCertificate})
+  # * Signing Certificates ({SigningCertificateCollection}, {SigningCertificate})
+  # * Multifactor Authentication Devices ({MFADeviceCollection}, {MFADevice})
+  #
+  class IAM
+
+    include ServiceInterface
+
+    # Returns a collection that represents all AWS users for this account:
+    #
+    # @example Getting a user by name
+    #
+    #   user = iam.users['username']
+    #
+    # @example Enumerating users
+    #
+    #   iam.users.each do |user|
+    #     puts user.name
+    #   end
+    # 
+    # @return [UserCollection] Returns a collection that represents all of
+    #   the IAM users for this AWS account.
+    def users
+      UserCollection.new(:config => config)
+    end
+
+    # Returns a collection that represents all AWS groups for this account:
+    #
+    # @example Getting a group by name
+    #
+    #   group = iam.groups['groupname']
+    #
+    # @example Enumerating groups
+    #
+    #   iam.groups.each do |group|
+    #     puts group.name
+    #   end
+    #
+    # @return [GroupCollection] Returns a collection that represents all of
+    #   the IAM groups for this AWS account.
+    def groups
+      GroupCollection.new(:config => config)
+    end
+
+    # Returns a collection that represents the access keys for this 
+    # AWS account.
+    #
+    #   iam = AWS::IAM.new
+    #   iam.access_keys.each do |access_key|
+    #     puts access_key.id
+    #   end
+    #
+    # @return [AccessKeyCollection] Returns a collection that represents all
+    #   access keys for this AWS account.
+    def access_keys
+      AccessKeyCollection.new(:config => config)
+    end
+
+    # Returns a collection that represents the signing certificates
+    # for this AWS account.  
+    #
+    #   iam = AWS::IAM.new
+    #   iam.signing_certificates.each do |cert|
+    #     # ...
+    #   end
+    #
+    # If you need to access the signing certificates of a specific user,
+    # see {User#signing_certificates}.
+    # 
+    # @return [SigningCertificateCollection] Returns a collection that
+    #   represents signing certificates for this AWS account.
+    def signing_certificates
+      SigningCertificateCollection.new(:config => config)
+    end
+
+    # @note Currently, Amazon Elastic Load Balancing is the only
+    #   service to support the use of server certificates with
+    #   IAM. Using server certificates with Amazon Elastic Load
+    #   Balancing is described in the
+    #   {http://docs.amazonwebservices.com/ElasticLoadBalancing/latest/DeveloperGuide/US_SettingUpLoadBalancerHTTPSIntegrated.html
+    #   Amazon Elastic Load Balancing} Developer Guide.
+    #
+    # Returns a collection that represents the server certificates
+    # for this AWS account.
+    #
+    #   iam = AWS::IAM.new
+    #   iam.server_certificates.each do |cert|
+    #     # ...
+    #   end
+    #
+    # @return [ServerCertificateCollection] Returns a collection that
+    #   represents server certificates for this AWS account.
+    def server_certificates
+      ServerCertificateCollection.new(:config => config)
+    end
+
+    # Sets the account alias for this AWS account.
+    # @param [String] account_alias
+    # @return [String] Returns the account alias passed.
+    def account_alias= account_alias
+      account_alias.nil? ?
+        remove_account_alias :
+        account_aliases.create(account_alias)
+    end
+
+    # @return [String,nil] Returns the account alias.  If this account has
+    #   no alias, then +nil+ is returned.
+    def account_alias
+      account_aliases.first
+    end
+
+    # Deletes the account alias (if one exists).
+    # @return [nil] 
+    def remove_account_alias
+      account_aliases.each do |account_alias|
+        account_aliases.delete(account_alias)
+      end
+      nil
+    end
+
+    # @private
+    def account_aliases
+      AccountAliasCollection.new(:config => config)
+    end
+
+    # Retrieves account level information about account entity usage
+    # and IAM quotas.  The returned hash contains the following keys:
+    #
+    # [+:users+] Number of users for the AWS account
+    #
+    # [+:users_quota+] Maximum users allowed for the AWS account
+    #
+    # [+:groups+] Number of Groups for the AWS account
+    #
+    # [+:groups_quota+] Maximum Groups allowed for the AWS account
+    #
+    # [+:server_certificates+] Number of Server Certificates for the
+    #                          AWS account
+    #
+    # [+:server_certificates_quota+] Maximum Server Certificates
+    #                                allowed for the AWS account
+    #
+    # [+:user_policy_size_quota+] Maximum allowed size for user policy
+    #                             documents (in kilobytes)
+    #
+    # [+:group_policy_size_quota+] Maximum allowed size for Group
+    #                              policy documents (in kilobyes)
+    #
+    # [+:groups_per_user_quota+] Maximum number of groups a user can
+    #                            belong to
+    #
+    # [+:signing_certificates_per_user_quota+] Maximum number of X509
+    #                                          certificates allowed
+    #                                          for a user
+    #
+    # [+:access_keys_per_user_quota+] Maximum number of access keys
+    #                                 that can be created per user
+    #
+    # @return [Hash]
+    def account_summary
+      client.get_account_summary.summary_map.inject({}) do |h, (k,v)|
+        h[Inflection.ruby_name(k).to_sym] = v
+        h
+      end
+    end
+
+  end
+end

data/lib/aws/iam/access_key.rb

@@ -0,0 +1,183 @@
+# Copyright 2011 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 'aws/iam/resource'
+require 'aws/iam/user'
+
+module AWS
+  class IAM
+
+    # @attr_reader [Symbol] status The status of this access key.
+    #   Status may be +:active+ or +:inactive+.
+    #
+    class AccessKey < Resource
+      
+      # @param [String] access_key_id The id of this access key.
+      # @param [Hash] options
+      # @option [String] :user The IAM user this access key belongs to.
+      #   If +:user+ is omitted then this access key belongs to the
+      #   AWS account.
+      def initialize access_key_id, options = {}
+        @id = access_key_id
+        options[:secret_value] = nil unless options.has_key?(:secret_value)
+        @user = options[:user]
+        @user ? super(@user, options) : super(options)
+      end
+
+      # @return [User,nil] Returns the user this access key belongs to.
+      #   Returns +nil+ if this access key belongs to the AWS account and not
+      #   a specific user.
+      attr_reader :user
+
+      # @return [String] Returns the access key id.
+      attr_reader :id
+
+      alias_method :access_key_id, :id
+
+      attribute :secret_value, :as => :secret_access_key, :static => true
+
+      protected :secret_value
+
+      mutable_attribute :status, :to_sym => true
+
+      protected :status=
+
+      populates_from(:create_access_key) do |resp|
+        resp.access_key if matches_response_object?(resp.access_key)
+      end
+
+      populates_from(:list_access_keys) do |resp|
+        resp.access_key_metadata.find {|k| matches_response_object?(k) }
+      end
+
+      # Returns the secret access key.
+      #
+      # You can only access the secret for newly created access 
+      # keys.  Calling +secret+ on existing access keys raises an error.
+      #
+      # @example Getting the secret from a newly created access key
+      #
+      #   access_key = iam.access_keys.create
+      #   access_key.secret
+      #   #=> 'SECRET_ACCESS_KEY'
+      #
+      # @example Failing to get the secret from an existing access key.
+      #
+      #   access_key = iam.access_keys.first
+      #   access_key.secret
+      #   #=> raises a runtime error
+      #
+      # @return [String] Returns the secret access key.  
+      def secret
+        secret_value or raise 'secret is only available for new access keys'
+      end
+
+      alias_method :secret_access_key, :secret
+
+      # @return [String,nil] Returns the name of the user this access key
+      #   belogns to.  If the access key belongs to the account, +nil+ is
+      #   returned.
+      def user_name
+        @user ? @user.name : nil
+      end
+
+      # @return [Boolean] Returns true if this access key is active.
+      def active?
+        status == :active
+      end
+
+      # @return [Boolean] Returns true if this access key is inactive.
+      def inactive?
+        status == :inactive
+      end
+
+      # Activates this access key.
+      #
+      # @example
+      #   access_key.activate!
+      #   access_key.status
+      #   # => :active
+      #
+      # @return [nil]
+      def activate!
+        self.status = 'Active'
+        nil
+      end
+
+      # Deactivates this access key.
+      #
+      # @example
+      #   access_key.deactivate!
+      #   access_key.status
+      #   # => :inactive
+      #
+      # @return [nil]
+      # @return [nil]
+      def deactivate!
+        self.status = 'Inactive'
+        nil
+      end
+
+      # Deletes the access key.
+      def delete
+        client.delete_access_key(resource_options)
+        nil
+      end
+
+      # Returns a hash that should be saved somewhere safe.  
+      #
+      #   access_keys = iam.access_keys.create
+      #   access_keys.credentials
+      #   #=> { :access_key_id => '...', :secret_access_key => '...' }
+      #
+      # You can also use these credentials to make requests:
+      #
+      #   s3 = AWS::S3.new(access_keys.credentials)
+      #   s3.buckets.create('newbucket')
+      #
+      # @return [Hash] Returns a hash with the access key id and
+      #   secret access key. 
+      def credentials
+        { :access_key_id => id, :secret_access_key => secret }
+      end
+
+      # @private
+      protected
+      def resource_identifiers
+        identifiers = []
+        identifiers << [:access_key_id, id]
+        identifiers << [:user_name, user.name] if user
+        identifiers
+      end
+
+      # IAM does not provide a request for "get access keys".
+      # Also note, we do not page the response. This is because 
+      # restrictions on how many access keys an account / user may 
+      # have is fewer than one page of results.
+      # @private
+      protected
+      def get_resource attribute
+        options = user ? { :user_name => user.name } : {}
+        client.list_access_keys(options)
+      end
+
+      # @private
+      protected
+      def matches_response_object? obj
+        user_name = obj.respond_to?(:user_name) ? obj.user_name : nil
+        obj.access_key_id == self.id and user_name == self.user_name
+      end
+
+    end
+  end
+end