aws-sdk 1.0.0

data/lib/aws/ec2/snapshot.rb

@@ -0,0 +1,138 @@
+# 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/has_permissions'
+require 'aws/ec2/tagged_item'
+
+module AWS
+  class EC2
+
+    # Represents an Amazon EBS snapshot.
+    #
+    # @example Taking a snapshot from a volume
+    #  snapshot = volume.create_snapshot("Database Backup 12/21/2010")
+    #  sleep 1 until [:completed, :error].include?(snapshot.status)
+    #
+    # @example Managing snapshot permissions
+    #  unless snapshot.public?
+    #    snapshot.permissions.add("12345678901")
+    #  end
+    #
+    # @attr_reader [String] volume_id The ID of the volume this
+    #   snapshot was created from.
+    #
+    # @attr_reader [Symbol] status The status of the snapshot.
+    #   Possible values:
+    #
+    #   * +:pending+
+    #   * +:completed+
+    #   * +:error+
+    #
+    # @attr_reader [Time] start_time The time at which the snapshot
+    #   was initiated.
+    #
+    # @attr_reader [Integer] progress The progress of the snapshot
+    #   as a percentage.
+    #
+    # @attr_reader [String] owner_id The AWS account ID of the
+    #   snapshot owner.
+    #
+    # @attr_reader [Integer] volume_size The size of the volume from
+    #   which the snapshot was created.
+    #
+    # @attr_reader [String] description The description of the
+    #   snapshot provided at snapshot initiation.
+    class Snapshot < Resource
+
+      include HasPermissions
+      include TaggedItem
+      alias_method :create_volume_permissions, :permissions
+
+      # The snapshot ID
+      attr_reader :id
+
+      # @private
+      def initialize(id, opts = {})
+        @id = id
+        super(opts)
+      end
+
+      # Deletes the snapshot.
+      def delete
+        client.delete_snapshot(:snapshot_id => id)
+      end
+
+      # Creates a volume from the snapshot.
+      #
+      # @param [AvailabilityZone or String] availability_zone The
+      #   Availability Zone in which to create the new volume. See
+      #   {EC2#availability_zones} for how to get a list of
+      #   availability zones.
+      #
+      # @param [Hash] opts Additional options for creating the volume
+      #
+      # @option opts [Integer] size The desired size (in gigabytes)
+      #   for the volume.
+      #
+      # @return [Volume] The newly created volume
+      def create_volume(availability_zone, opts = {})
+        VolumeCollection.new(:config => config).
+          create(opts.merge(:snapshot => self,
+                            :availability_zone => availability_zone))
+      end
+
+      # @return [Boolean] True if the snapshot exists.
+      def exists?
+        resp =
+          client.describe_snapshots(:filters => [{ :name => 'snapshot-id',
+                                                   :values => [id] }]) and
+          !resp.snapshot_set.empty?
+      end
+
+      describe_call_attribute :volume_id
+
+      # @return [Volume] The volume this snapshot was created from.
+      def volume
+        Volume.new(volume_id, :config => config) if volume_id
+      end
+
+      describe_call_attribute :status, :to_sym => true
+      describe_call_attribute :start_time
+      describe_call_attribute :progress do
+        translate_output { |value| value.to_i if value }
+      end
+      describe_call_attribute :owner_id
+      describe_call_attribute :volume_size
+      describe_call_attribute :owner_alias
+      describe_call_attribute :description
+
+      # @private
+      def __permissions_attribute__
+        "createVolumePermission"
+      end
+
+      populate_from :create_snapshot do |resp|
+        attributes_from_response_object(resp) if
+          resp.snapshot_id == id
+      end
+
+      protected
+      def find_in_response(resp)
+        resp.snapshot_index[id]
+      end
+
+    end
+
+  end
+end

data/lib/aws/ec2/snapshot_collection.rb

@@ -0,0 +1,90 @@
+# 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/collection'
+require 'aws/ec2/tagged_collection'
+require 'aws/ec2/snapshot'
+
+module AWS
+  class EC2
+
+    # Represents a collection of Amazon EBS snapshots.  Typically
+    # you should get an instance of this class by calling
+    # {EC2#snapshots}.
+    #
+    # @example Create a snapshot from a volume
+    #  ec2.snapshots.create(:volume => ec2.volumes["vol-123"],
+    #                       :description => "my snapshot")
+    #  # or:
+    #  ec2.volumes["vol-123"].create_snapshot("my snapshot")
+    #
+    # @example Get a snapshot by ID
+    #  snapshot = ec2.snapshots["vol-123"]
+    #  snapshot.exists?
+    #
+    # @example Get a map of snapshot IDs to snapshot status
+    #   ec2.snapshots.inject({}) { |m, s| m[i.id] = s.status; m }
+    #   # => { "snap-12345678" => :pending, "snap-87654321" => :completed }
+    class SnapshotCollection < Collection
+
+      include TaggedCollection
+
+      # @yield [Instance] Yields each volume in the collection.
+      # @return [nil]
+      def each(&block)
+        resp = filtered_request(:describe_snapshots)
+        resp.snapshot_set.each do |v|
+          snapshot = Snapshot.new(v.snapshot_id, :config => config)
+          yield(snapshot)
+        end
+        nil
+      end
+
+      # Creates a snapshot of an Amazon EBS volume and stores it in
+      # Amazon S3. You can use snapshots for backups, to make
+      # identical copies of instance devices, and to save data
+      # before shutting down an instance. For more information about
+      # Amazon EBS, go to the {Amazon Elastic Compute Cloud User
+      # Guide}[http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?using-ebs.html].
+      #
+      # @return [Snapshot] An object representing the new snapshot.
+      #
+      # @param [Hash] opts Options for creating the snapshot.
+      #   Either +:volume+ or +:volume_id+ is required.
+      #
+      # @param opts [Volume] :volume The Amazon EBS volume of which
+      #   to take a snapshot.
+      #
+      # @param opts [String] :volume_id The ID of the Amazon EBS
+      #   volume of which to take a snapshot.
+      #
+      # @param opts [String] :description An optional description of
+      #   the snapshot.  May contain up to 255 characters.
+      def create opts = {}
+        if volume = opts.delete(:volume)
+          opts[:volume_id] = volume.id
+        end
+        resp = client.create_snapshot(opts)
+        Snapshot.new(resp.snapshot_id, :config => config)
+      end
+
+      # @private
+      protected
+      def member_class
+        Snapshot
+      end
+
+    end
+
+  end
+end

data/lib/aws/ec2/tag.rb

@@ -0,0 +1,88 @@
+# 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/cacheable'
+
+module AWS
+  class EC2
+
+    # Represents an EC2 tag.
+    class Tag < Resource
+
+      # @param [String] key The name of the tag
+      # @param [Hash] options
+      # @option options [String] :value ('') The optional value of the tag.
+      def initialize resource, key, options = {}
+        @resource = resource
+        @key = key.to_s
+        super
+      end
+
+      # @return [Object] The EC2 resource this tag belongs to.
+      attr_reader :resource
+
+      # @return [String] The name of this tag.
+      attr_reader :key
+
+      alias_method :name, :key
+
+      # @return [String] The tag value.
+      def value; end
+      describe_call_attribute :value
+
+      # Deletes this tag.
+      # @return [nil]
+      def delete(value = nil)
+        tag_opts = { :key => key }
+        tag_opts[:value] = value if value
+        client.delete_tags(:resources => [resource.id], :tags => [tag_opts])
+        nil
+      end
+
+      # @private
+      def inspect
+        "<#{local_cache_key}>"
+      end
+
+      # @private
+      def local_cache_key
+        "#{self.class}:#{response_index_key}"
+      end
+
+      private
+      def response_index_key
+        type = resource.tagging_resource_type
+        id = resource.send(:__resource_id__)
+        "#{type}:#{id}:#{key}"
+      end
+
+      protected
+      def find_in_response(resp)
+        resp.tag_index[response_index_key]
+      end
+
+      protected
+      def describe_call
+        client.describe_tags(:filters =>
+                             [{ :name => "key",
+                                :values => [key] },
+                              { :name => "resource-type",
+                                :values => [resource.tagging_resource_type] },
+                              { :name => "resource-id",
+                                :values => [resource.send(:__resource_id__)] }])
+      end
+
+    end
+  end
+end

data/lib/aws/ec2/tag_collection.rb

@@ -0,0 +1,114 @@
+# 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/inflection'
+require 'aws/ec2/collection'
+require 'aws/ec2/tag'
+require 'aws/ec2/tagged_item'
+require 'aws/ec2/resource'
+
+module AWS
+  class EC2
+
+    # Temporary class that will be removed once the rest of the taggable
+    # EC2 resources have been modeled.
+    class ResourceObject < Resource
+
+      def initialize id, options = {}
+        @id = id
+        @resource_type = options[:resource_type]
+        super
+      end
+
+      attr_reader :id
+
+      include TaggedItem
+
+      # @private
+      def tagging_resource_type
+        @resource_type
+      end
+
+      # @private
+      # We don't know how to make a describe call for this object yet
+      def cached_tags; nil; end
+
+    end
+
+    # Represents all EC2 tags in an account.
+    class TagCollection < Collection
+
+      # Creates a new Tag and assigns it to an EC2 resource.
+      #
+      # @example tagging with names (keys) only
+      #
+      #   ec2.tags.create(instance, 'webserver')
+      #
+      # @example tagging with names (keys) and values
+      #
+      #   ec2.tags.create(instance, 'stage', 'production')
+      #
+      # @param [Object] resource The item to tag.  This should be a taggable
+      #   EC2 resource, like an instance, security group, etc.
+      # @param [String] key The tag key (or name).
+      # @param [Hash] options 
+      # @option optins [String] :value ('') The optional tag value.  When
+      #   left blank its assigned the empty string.
+      # @return [Tag]
+      def create resource, key, options = {}
+        value = options[:value].to_s
+        client.create_tags(
+          :resources => [resource.id],
+          :tags => [{ :key => key, :value => value }])
+        Tag.new(resource, key, :value => value, :config => config)
+      end
+
+      # @return [Tag] Returns a reference to a tag with the given name.
+      def [] tag_name
+        super
+      end
+
+      # Yields once for each tag.
+      # @yield [tag]
+      # @yieldparam [Tag] tag
+      # @return [nil]
+      def each &block
+        response = filtered_request(:describe_tags)
+        response.tag_set.each do |tag|
+
+          resource_class_name = Inflection.class_name(tag.resource_type)
+          if EC2.const_defined?(resource_class_name)
+            resource_class = EC2.const_get(resource_class_name)
+            resource = resource_class.new(tag.resource_id, :config => config)
+          else
+            resource = ResourceObject.new(tag.resource_id,
+                                          :resource_type => tag.resource_type,
+                                          :config => config)
+          end
+
+          yield(Tag.new(resource, tag.key))
+
+        end
+        nil
+      end
+
+      # @private
+      protected
+      def member_class
+        Tag
+      end
+
+    end
+  end
+end

data/lib/aws/ec2/tagged_collection.rb

@@ -0,0 +1,48 @@
+# 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.
+
+module AWS
+  class EC2
+
+    # @private
+    module TaggedCollection
+
+      # Filter the collection by one or more tag keys.  If you pass multiple
+      # tag keys they will be be treated as OR conditions.  If you want to 
+      # AND them together call tagged multiple times (chained).
+      #
+      # Filter the collection to items items tagged 'live' OR 'test'
+      #
+      #   collection.tagged('live', 'test')
+      #
+      # Filter the collection to items tagged 'live' AND 'webserver'
+      #
+      #   collection.tagged('live').tagged('webserver')
+      #
+      def tagged *keys
+        filter('tag-key', *keys)
+      end
+
+      # Filter the collection by one or more tag values.  If you pass multiple
+      # tag values they will be be treated as OR conditions.  If you want to 
+      # AND them together call tagged multiple times (chained).
+      #
+      #   collection.tagged('stage').tagged_values('production')
+      #
+      def tagged_values *values
+        filter('tag-value', *values)
+      end
+
+    end
+  end
+end