aws-sdk-v1 1.52.0

data/lib/aws/ec2/tag_collection.rb

@@ -0,0 +1,107 @@
+# Copyright 2011-2013 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
+
+    # 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
+
+      # @api private
+      def tagging_resource_type
+        @resource_type
+      end
+
+      # @api 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', :value => '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 = Core::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
+
+      # @api private
+      protected
+      def member_class
+        Tag
+      end
+
+    end
+  end
+end

data/lib/aws/ec2/tagged_collection.rb

@@ -0,0 +1,67 @@
+# Copyright 2011-2013 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
+
+    # Most of the AWS::EC2 collections include TaggedCollection.  This
+    # module provides methods for filtering the collection with
+    # tags.
+    #
+    #     collecion.tagged('prod').each do {|obj| ... }
+    #
+    module TaggedCollection
+
+      # Filters the collection by a paired tag key and value.
+      #
+      #    ec2.instances.with_tag('role', 'web')
+      #
+      # You can filter a single tag key with multiple values:
+      #
+      #    ec2.instances.with_tag('role', ['web', 'db'])
+      #
+      # @param [String] tag_key
+      # @param [String, Array<String>] tag_value
+      def with_tag(tag_key, *values)
+        filter("tag:#{tag_key}", *values)
+      end
+
+      # 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

data/lib/aws/ec2/tagged_item.rb

@@ -0,0 +1,85 @@
+# Copyright 2011-2013 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
+    module TaggedItem
+
+      # Adds a single tag with an optional tag value.
+      #
+      #     # adds a tag with the key production
+      #     resource.tag('production')
+      #
+      #     # adds a tag with the optional value set to production
+      #     resource.tag('role', :value => 'webserver')
+      #
+      # @param [String] key The name of the tag to add.
+      # @param [Hash] options
+      # @option options [String] :value An optional tag value.
+      # @return [Tag] The tag that was created.
+      def add_tag key, options = {}
+        client.create_tags({
+          :resources => [id],
+          :tags => [{ :key => key, :value => options[:value].to_s }],
+        })
+        Tag.new(self, key, options.merge(:config => config))
+      end
+      alias_method :tag, :add_tag
+
+      # Deletes all tags associated with this EC2 resource.
+      # @return [nil]
+      def clear_tags
+        client.delete_tags(:resources => [self.id])
+        nil
+      end
+
+      # Returns a collection that represents only tags belonging to
+      # this resource.
+      #
+      # @example Manipulating the tags of an EC2 instance
+      #   i = ec2.instances["i-123"]
+      #   i.tags.to_h                  # => { "foo" => "bar", ... }
+      #   i.tags.clear
+      #   i.tags.stage = "production"
+      #   i.tags.stage                 # => "production"
+      #
+      # @return [ResourceTagCollection] A collection of tags that
+      #   belong to this resource.
+      #
+      def tags
+        ResourceTagCollection.new(self, :config => config)
+      end
+
+      # @api private
+      def cached_tags
+        if cache = AWS.response_cache
+          cache.select(describe_call_name.to_sym).each do |resp|
+            if obj = find_in_response(resp)
+              return obj.tag_set.inject({}) do |hash, tag|
+                hash[tag.key] = tag.value
+                hash
+              end
+            end
+          end
+        end
+        nil
+      end
+
+      # @api private
+      def tagging_resource_type
+        Core::Inflection.ruby_name(self.class.to_s).tr("_","-")
+      end
+
+    end
+  end
+end

data/lib/aws/ec2/volume.rb

@@ -0,0 +1,185 @@
+# Copyright 2011-2013 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
+
+    # Represents an Amazon EBS volume.
+    #
+    # @example Create an empty 15GiB volume and attach it to an instance
+    #   volume = ec2.volumes.create(:size => 15,
+    #                               :availability_zone => "us-west-2a")
+    #   attachment = volume.attach_to(ec2.instances["i-123"], "/dev/sdf")
+    #   sleep 1 until attachment.status != :attaching
+    #
+    # @example Remove all attachments from a volume and then delete it
+    #   volume.attachments.each do |attachment|
+    #     attachment.delete(:force => true)
+    #   end
+    #   sleep 1 until volume.status == :available
+    #   volume.delete
+    #
+    # @attr_reader [Symbol] status The status of the volume.
+    #   Possible values:
+    #
+    #     * `:creating`
+    #     * `:available`
+    #     * `:in_use`
+    #     * `:deleting`
+    #     * `:deleted`
+    #     * `:error`
+    #
+    # @attr_reader [Integer] size The size of the volume in
+    #   gigabytes.
+    #
+    # @attr_reader [String] availability_zone_name Name of the
+    #   Availability Zone in which the volume was created.
+    #
+    # @attr_reader [Time] create_time The time at which the volume
+    #   was created.
+    #
+    # @attr_reader [String] type The volume type.
+    #
+    # @attr_reader [Boolean] encrypted Returns `true` if the volume is
+    #   encrypted.
+    #
+    # @attr_reader [String] iops
+    #
+    class Volume < Resource
+
+      include TaggedItem
+
+      # @api private
+      def initialize(id, opts = {})
+        @id = id
+        super(opts)
+      end
+
+      # @return [String] Returns the volume ID.
+      attr_reader :id
+
+      attribute :status, :to_sym => true
+
+      alias_method :state, :status
+
+      attribute :snapshot_id, :static => true
+
+      attribute :size, :static => true
+
+      attribute :availability_zone_name, :from => :availability_zone,
+        :static => true
+
+      attribute :create_time, :static => true
+
+      attribute :attachment_set
+
+      attribute :iops, :static => true
+
+      attribute :type, :from => :volume_type, :static => true
+
+      attribute :encrypted, :static => true
+
+      alias encrypted? encrypted
+
+      populates_from(:create_volume) do |resp|
+        resp if resp.volume_id == id
+      end
+
+      populates_from(:describe_volumes) do |resp|
+        resp.volume_index[id]
+      end
+
+      # Deletes the volume.
+      def delete
+        client.delete_volume(:volume_id => id)
+        nil
+      end
+
+      # @return [Snapshot] A new snapshot created from the volume.
+      #
+      # @param [String] description An optional description of the
+      #   snapshot.  May be up to 255 characters in length.
+      def create_snapshot description = nil
+        opts = { :volume => self }
+        opts[:description] = description if description
+        SnapshotCollection.new(:config => config).create(opts)
+      end
+
+      # Attaches the volume to an instance.
+      #
+      # @param [Instance] instance The instance to which the volume
+      #   attaches. The volume and instance must be within the same
+      #   Availability Zone and the instance must be running.
+      #
+      # @param [String] device How the device is exposed to the
+      #   instance (e.g., /dev/sdh, or xvdh).
+      #
+      # @return [Attachment] An object representing the attachment,
+      #   which you can use to query the attachment status.
+      def attach_to(instance, device)
+        resp = client.attach_volume(
+          :volume_id => id,
+          :instance_id => instance.id,
+          :device => device
+        )
+        instance = Instance.new(resp.instance_id, :config => config)
+        Attachment.new(self, instance, resp.device, :config => config)
+      end
+      alias_method :attach, :attach_to
+
+      # Detaches the volume from an instance.
+      #
+      # @param [Instance] instance The instance to detach from.
+      # @param [String] device The device name.
+      # @param [Hash] options
+      # @option (see Attachment#delete)
+      # @return [Attachment] Returns the no-longer valid attachment.
+      def detach_from(instance, device, options = {})
+        instance = Instance.new(instance.id, :config => config),
+        a = Attachment.new(self, instance, device, :config => config)
+        a.delete(options)
+        a
+      end
+
+      # @return [Boolean] True if the volume exists.
+      def exists?
+        resp = client.describe_volumes(:filters => [
+          { :name => 'volume-id', :values => [id] }
+        ])
+        resp.volume_index.key?(id)
+      end
+
+      # @return [Snapshot] Snapshot from which the volume was created
+      #   (may be nil).
+      def snapshot
+        snapshot_id ? Snapshot.new(snapshot_id, :config => config) : nil
+      end
+
+      # @return [AvailabilityZone] Returns the Availability
+      #   Zone in which the volume was created.
+      def availability_zone
+        if name = availability_zone_name
+          AvailabilityZone.new(name, :config => config)
+        end
+      end
+
+      # @return [AttachmentCollection] The collection of attachments
+      #   that involve this volume.
+      def attachments
+        AttachmentCollection.new(self, :config => config)
+      end
+
+    end
+
+  end
+end

data/lib/aws/ec2/volume_collection.rb

@@ -0,0 +1,102 @@
+# Copyright 2011-2013 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
+
+    # Represents a collection of Amazon EBS volumes.  Typically you
+    # should get an instance of this class by calling {EC2#volumes}.
+    #
+    # @example Create an empty 15GiB volume
+    #   ec2.volumes.create(:size => 15, :availability_zone => "us-west-2a")
+    #
+    # @example Get a volume by ID
+    #   volume = ec2.volumes["vol-123"]
+    #   volume.exists?
+    #
+    # @example Get a map of volume IDs to volume status
+    #   ec2.volumes.inject({}) { |m, v| m[v.id] = v.status; m }
+    #   # => { "vol-12345678" => :available, "vol-87654321" => :in_use }
+    class VolumeCollection < Collection
+
+      include TaggedCollection
+
+      # @yield [Volume] Yields each volume in the collection.
+      # @return [nil]
+      def each(&block)
+        resp = filtered_request(:describe_volumes)
+        resp.volume_set.each do |v|
+
+          volume = Volume.new_from(:describe_volumes, v,
+            v.volume_id, :config => config)
+
+          yield(volume)
+
+        end
+        nil
+      end
+
+      # Creates a new Amazon EBS volume that any Amazon EC2 instance
+      # in the same Availability Zone can attach to. 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 [Volume] An object representing the new volume.
+      #
+      # @param [Hash] options Options for creating the volume.
+      #   `:availability_zone` and one of `:size`, `:snapshot`, or
+      #   `:snapshot_id` is required.
+      #
+      # @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 options [Snapshot] :snapshot The snapshot from which to
+      #   create the new volume.
+      #
+      # @option options [String] :snapshot_id The ID of the snapshot
+      #   from which to create the new volume.
+      #
+      # @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}.
+      #
+      # @option options [String] :iops
+      #
+      # @option options [String] :volume_type
+      #
+      # @option options [Boolean] :encrypted (false)
+      #   When true, the volume will be encrypted.
+      #   For more information, refer to [Amazon EBS Encryption](http://http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html)
+      #
+      # @return [Volume]
+      #
+      def create options = {}
+        if snapshot = options.delete(:snapshot)
+          options[:snapshot_id] = snapshot.id
+        end
+        resp = client.create_volume(options)
+        Volume.new_from(:create_volume, resp, resp.volume_id, :config => config)
+      end
+
+      # @api private
+      protected
+      def member_class
+        Volume
+      end
+
+    end
+
+  end
+end