aws-sdk 1.0.0

data/lib/aws/ec2/security_group.rb

@@ -0,0 +1,246 @@
+# 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/ec2/resource'
+require 'aws/ec2/tagged_item'
+require 'aws/ec2/security_group/ip_permission'
+require 'aws/ec2/security_group/ip_permission_collection'
+
+module AWS
+  class EC2
+
+    # Represents a security group in EC2.
+    class SecurityGroup < Resource
+
+      include TaggedItem
+
+      def initialize id, options = {}
+        @id = id
+        @name = options[:name]
+        @description = options[:description]
+        @owner_id = options[:owner_id]
+        super
+      end
+
+      # @return [String] The id of the security group.
+      attr_reader :id
+
+      alias_method :group_id, :id
+
+      # @return [Boolean] True if the security group exists.
+      def exists?
+        client.describe_security_groups(:filters =>
+                                         [{ :name => "group-id",
+                                            :values => [id] }]).
+          security_group_index.key?(id)
+      end
+
+      # @return [String] The name of the security group.
+      def name; end
+      describe_call_attribute :group_name, :getter => :name, :memoize => true
+
+      # @return [String] The id of the owner for this security group.
+      def owner_id; end
+      describe_call_attribute :owner_id, :memoize => true
+
+      # @return [String] The short informal description given when the
+      #   group was created.
+      def description; end
+      describe_call_attribute :group_description, :getter => :description, :memoize => true
+
+      describe_call_attribute :ip_permissions, :getter => :ip_permissions_list
+
+      # @return [SecurityGroup::IpPermissionCollection] Returns a
+      #   collection of {IpPermission} objects that represents all of
+      #   the permissions this security group has authorizations for.
+      def ip_permissions
+        IpPermissionCollection.new(self, :config => config)
+      end
+
+      # Adds ingress rules for ICMP pings.  Defaults to 0.0.0.0/0 for 
+      # the list of allowed IP ranges the ping can come from.
+      #
+      #   security_group.allow_ping # anyone can ping servers in this group
+      #
+      #   # only allow ping from a particular address
+      #   security_group.allow_ping('123.123.123.123/0')
+      #
+      # @param [String] ip_ranges One or more IP ranges to allow ping from.
+      #   Defaults to 0.0.0.0/0
+      def allow_ping *sources
+        sources << '0.0.0.0/0' if sources.empty?
+        authorize_ingress('icmp', -1, *sources)
+      end
+
+      # Removes ingress rules for ICMP pings.  Defaults to 0.0.0.0/0 for 
+      # the list of IP ranges to revoke.
+      #
+      # @param [String] ip_ranges One or more IP ranges to allow ping from.
+      #   Defaults to 0.0.0.0/0
+      def disallow_ping *sources
+        sources << '0.0.0.0/0' if sources.empty?
+        revoke_ingress('icmp', -1, *sources)
+      end
+
+      # Adds an ingress rules to a security group.
+      #
+      # Each ingress exception is comprised of a protocol a port range
+      # and a list of sources.
+      # 
+      #
+      # This example grants the whole internet (0.0.0.0/0) access to port 80 
+      # over TCP (HTTP web traffic).
+      #
+      #   security_groups['websrv'].authorize_ingress(:tcp, 80)
+      #
+      # In the following example we grant SSH access from a list of 
+      # IP address.
+      #
+      #   security_groups['appsrv'].authorize_ingress(:tcp, 22, 
+      #     '111.111.111.111/0', '222.222.222.222/0')
+      #
+      # You can also grant privileges to other security groups. This
+      # is a convenient shortcut for granting permissions to all EC2
+      # servers in a particular security group access.
+      #
+      #   web = security_groups['httpservers']
+      #   db = security_groups['dbservers']
+      #
+      #   db.authorize_ingress(:tcp, 3306, web)
+      #
+      # You can specify port ranges as well:
+      #
+      #   security_groups['ftpsvr'].authorize_ingress(:tcp, 20..21)
+      #
+      # You can even mix and match IP address and security groups.
+      #
+      # @param [String, Symbol] protocol Should be :tcp, :udp or :icmp
+      #   or the string equivalent.
+      #
+      # @param [Integer, Range] ports The port (or port range) to allow
+      #   ingress traffic over.  You can pass a single integer (like 80) 
+      #   or a range (like 20..21).
+      #
+      # @param [Mixed] sources One or more CIDR IP addresses,
+      #   security groups, or hashes.  Hash values should
+      #   have :group_id and :user_id keys/values.  This is useful
+      #   for when the security group belongs to another account.  The
+      #   user id should be the owner_id (account id) of the security
+      #   group.
+      #
+      # @return [nil]
+      def authorize_ingress protocol, ports, *sources
+        permissions = format_permission(protocol, ports, sources)
+        client.authorize_security_group_ingress(
+          :group_id => id,
+          :ip_permissions => permissions)
+        nil
+      end
+
+      # @param see #authorize_ingress
+      # @return [nil]
+      def revoke_ingress protocol, ports, *sources
+        permissions = format_permission(protocol, ports, sources)
+        client.revoke_security_group_ingress(
+          :group_id => id,
+          :ip_permissions => permissions)
+        nil
+      end
+
+      # Deletes this security group. 
+      #
+      # If you attempt to delete a security group that contains 
+      # instances, or attempt to delete a security group that is referenced
+      # by another security group, an error is raised. For example, if 
+      # security group B has a rule that allows access from security 
+      # group A, security group A cannot be deleted until the rule is 
+      # removed.
+      # @return [nil]
+      def delete
+        client.delete_security_group(:group_id => id)
+        nil
+      end
+
+      # @private
+      def resource_type
+        'security-group'
+      end
+
+      # @private
+      def inflected_name
+        "group"
+      end
+
+      # @private
+      def self.describe_call_name
+        :describe_security_groups
+      end
+      def describe_call_name; self.class.describe_call_name; end
+
+      # @private
+      protected
+      def find_in_response(resp)
+        resp.security_group_index[id]
+      end
+
+      # @private
+      protected
+      def format_permission protocol, ports, sources
+
+        permission = {}
+        permission[:ip_protocol] = protocol.to_s.downcase
+        permission[:from_port] = Array(ports).first.to_i
+        permission[:to_port] = Array(ports).last.to_i
+
+        ip_ranges = []
+        groups = []
+
+        # default to 0.0.0.0/0
+        sources << '0.0.0.0/0' if sources.empty?
+
+        sources.each do |where|
+          case where 
+
+          when String 
+            ip_ranges << where
+
+          when SecurityGroup
+            groups << {:group_id => where.id, :user_id => where.owner_id}
+
+          when Hash 
+            if where.has_key?(:group_id) and where.has_key?(:user_id)
+              groups << where
+            else
+              raise ArgumentError, 'invalid ingress ip permission, hashes ' +
+               'must have :group_id and :user_id key/values'
+            end
+          else
+            raise ArgumentError, 'invalid ingress ip permission, ' +
+              'expected CIDR IP addres or SecurityGroup'
+          end
+        end
+
+        unless ip_ranges.empty?
+          permission[:ip_ranges] = ip_ranges.collect{|ip| { :cidr_ip => ip } }
+        end
+
+        unless groups.empty?
+          permission[:user_id_group_pairs] = groups
+        end
+
+        [permission]
+
+      end
+    end
+  end
+end

data/lib/aws/ec2/security_group/ip_permission.rb

@@ -0,0 +1,70 @@
+# 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/model'
+
+module AWS
+  class EC2
+    class SecurityGroup < Resource
+      class IpPermission
+
+        include Model
+
+        # @param protocol [:tcp, :udp, :icmp]
+        # @param port [Range,Integer] An integer or a range of integers
+        #   to open ports for.
+        # @param [Hash] options
+        # @option options [Array] :ip_ranges An array of CIDR ip address
+        #   to grant permission to.
+        # @option options [Array] :groups An array of SecurityGroup objects to
+        #   grant permission to.
+        def initialize security_group, protocol, ports, options = {}
+          @security_group = security_group
+          @protocol = protocol.to_s.downcase.to_sym
+          @port_range = (Array(ports).first..Array(ports).last)
+          @ip_ranges = Array(options[:ip_ranges])
+          @groups = Array(options[:groups])
+          super
+        end
+
+        # @return [SecurityGroup] The security group this permission is 
+        #   authorized for.
+        attr_reader :security_group
+
+        # @return [Symbol] The protocol (:tcp, :udp, :icmp)
+        attr_reader :protocol
+
+        # @return [Range] The port range (e.g. 80..80, 4000..4010, etc)
+        attr_reader :port_range
+
+        # @return [Array] An array if string CIDR ip addresses.
+        attr_reader :ip_ranges
+
+        # @return [Array] An array of security groups that have been 
+        # granted access with this permission.
+        attr_reader :groups
+
+        def authorize
+          sources = groups + ip_ranges
+          security_group.authorize_ingress(protocol, port_range, *sources)
+        end
+
+        def revoke
+          sources = groups + ip_ranges
+          security_group.revoke_ingress(protocol, port_range, *sources)
+        end
+
+      end
+    end
+  end
+end

data/lib/aws/ec2/security_group/ip_permission_collection.rb

@@ -0,0 +1,59 @@
+# 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/model'
+
+module AWS
+  class EC2
+    class SecurityGroup < Resource
+
+      class IpPermissionCollection
+
+        include Model
+        include Enumerable
+
+        attr_reader :security_group
+
+        def initialize(security_group, opts = {})
+          super
+          @security_group = security_group
+        end
+
+        def each
+          security_group.ip_permissions_list.each do |p|
+
+            groups = p.groups.collect do |group|
+              SecurityGroup.new(group.group_id,
+                                :name => group.group_name,
+                                :owner_id => group.user_id,
+                                :config => config)
+            end
+
+            ip_ranges = p.ip_ranges.collect{|ip| ip.cidr_ip }
+
+            permission =
+              IpPermission.new(self, p.ip_protocol, [p.from_port, p.to_port],
+                               :ip_ranges => ip_ranges,
+                               :groups => groups,
+                               :config => config)
+
+            yield(permission)
+
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/aws/ec2/security_group_collection.rb

@@ -0,0 +1,132 @@
+# 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/model'
+require 'aws/ec2/collection'
+require 'aws/ec2/tagged_collection'
+require 'aws/ec2/security_group'
+
+module AWS
+  class EC2
+
+    # Represents all EC2 security groups in an AWS account.
+    class SecurityGroupCollection < Collection
+
+      include TaggedCollection
+
+      # Creates a new 
+      # @param [String] name The name of the security group to create.
+      # @param [Hash] options
+      # @option options [String] :description An informal description 
+      #   of this security group.  Accepts alphanumeric characters, spaces,
+      #   dashes, and underscores. If left blank the description will be set
+      #   to the name.
+      # @return [SecurityGroup]
+      def create name, options = {}
+
+        description = options[:description] || name
+
+        response = client.create_security_group(
+          :group_name => name, 
+          :description => description)
+
+        SecurityGroup.new(response.group_id, {
+          :name => name,
+          :description => description,
+          :config => config })
+
+      end
+
+      # @param [String] group_id The group id of a security group.
+      # @return [SecurityGroup] The group with the given id.
+      def [] group_id
+        super
+      end
+
+      # Specify one or more criteria to filter security groups by.
+      # A subsequent call to #each will limit the security groups returned
+      # by the set of filters.
+      #
+      # If you supply multiple values to #filter then these values are 
+      # treated as an OR condition.  To return security groups named
+      # 'test' or 'fake':
+      #
+      #   security_groups.filter('group-name', 'test', 'fake')
+      #
+      # If you want to and conditions together you need to chain calls to
+      # filter.  To limit security groups to those with a name like
+      # 'test' and like 'ruby':
+      #
+      #   security_groups.
+      #     filter('group-name', '*test*').
+      #     filter('group-name', '*ruby*').each do |group|
+      #     #...
+      #   end
+      #  
+      # Note that * matches one or more characters and ? matches any one
+      # character.
+      #
+      # === Valid Filters
+      #
+      # * description - Description of the security group.
+      # * group-id - ID of the security group.
+      # * group-name - Name of the security group.
+      # * ip-permission.cidr - CIDR range that has been granted the 
+      #   permission.
+      # * ip-permission.from-port - Start of port range for the TCP and UDP 
+      #    protocols, or an ICMP type number.
+      # * ip-permission.group-name - Name of security group that has been 
+      #   granted the permission.
+      # * ip-permission.protocol - IP protocol for the permission. Valid 
+      #   values include 'tcp', 'udp', 'icmp' or a protocol number.
+      # * ip-permission.to-port - End of port range for the TCP and UDP 
+      #   protocols, or an ICMP code.
+      # * ip-permission.user-id - ID of AWS account that has been granted 
+      #   the permission.
+      # * owner-id - AWS account ID of the owner of the security group.
+      # * tag-key - Key of a tag assigned to the security group.
+      # * tag-value - Value of a tag assigned to the security group.
+      #
+      # @return [SecurityGroupCollection] A new collection that represents
+      #   a subset of the security groups associated with this account.
+
+      # Yields once for each security group in this account. 
+      #
+      # @yield [group]
+      # @yieldparam [SecurityGroup] group
+      # @return [nil]
+      def each &block
+
+        response = filtered_request(:describe_security_groups)
+        response.security_group_info.each do |info|
+
+          group = SecurityGroup.new(info.group_id,
+            :name => info.group_name,
+            :description => info.group_description,
+            :owner_id => info.owner_id,
+            :config => config)
+
+          yield(group)
+
+        end
+        nil
+      end
+
+      protected
+      def member_class
+        SecurityGroup
+      end
+
+    end
+  end
+end