You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::EC2::Volume

Inherits:
Resource
  • Object
show all
Includes:
TaggedItem
Defined in:
lib/aws/ec2/volume.rb

Overview

Represents an Amazon EBS volume.

Examples:

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

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from TaggedItem

#add_tag, #clear_tags, #tags

Instance Attribute Details

#availability_zone_name ⇒ String (readonly)

Name of the Availability Zone in which the volume was created.

Returns:

  • (String) —

    the current value of availability_zone_name



58
59
60
 
# File 'lib/aws/ec2/volume.rb', line 58

def availability_zone_name
  @availability_zone_name
end

#create_time ⇒ Time (readonly)

The time at which the volume was created.

Returns:

  • (Time) —

    the current value of create_time



58
59
60
 
# File 'lib/aws/ec2/volume.rb', line 58

def create_time
  @create_time
end

#encrypted ⇒ Boolean (readonly) Also known as: encrypted?

Returns true if the volume is encrypted.

Returns:

  • (Boolean) —

    the current value of encrypted



58
59
60
 
# File 'lib/aws/ec2/volume.rb', line 58

def encrypted
  @encrypted
end

#id ⇒ String (readonly)

Returns the volume ID.

Returns:

  • (String) —

    Returns the volume ID.



69
70
71
 
# File 'lib/aws/ec2/volume.rb', line 69

def id
  @id
end

#iops ⇒ String (readonly)

Returns the current value of iops

Returns:

  • (String) —

    the current value of iops



58
59
60
 
# File 'lib/aws/ec2/volume.rb', line 58

def iops
  @iops
end

#size ⇒ Integer (readonly)

The size of the volume in gigabytes.

Returns:

  • (Integer) —

    the current value of size



58
59
60
 
# File 'lib/aws/ec2/volume.rb', line 58

def size
  @size
end

#status ⇒ Symbol (readonly) Also known as: state

The status of the volume. Possible values:

  • :creating
  • :available
  • :in_use
  • :deleting
  • :deleted
  • :error

Returns:

  • (Symbol) —

    the current value of status



58
59
60
 
# File 'lib/aws/ec2/volume.rb', line 58

def status
  @status
end

#type ⇒ String (readonly)

The volume type.

Returns:

  • (String) —

    the current value of type



58
59
60
 
# File 'lib/aws/ec2/volume.rb', line 58

def type
  @type
end

Instance Method Details

#attach_to(instance, device) ⇒ Attachment Also known as: attach

Attaches the volume to an instance.

Parameters:

  • 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.

  • device (String) —

    How the device is exposed to the instance (e.g., /dev/sdh, or xvdh).

Returns:

  • (Attachment) —

    An object representing the attachment, which you can use to query the attachment status.



129
130
131
132
133
134
135
136
137
 
# File 'lib/aws/ec2/volume.rb', line 129

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

#attachments ⇒ AttachmentCollection

Returns The collection of attachments that involve this volume.

Returns:



178
179
180
 
# File 'lib/aws/ec2/volume.rb', line 178

def attachments
  AttachmentCollection.new(self, :config => config)
end

#availability_zone ⇒ AvailabilityZone

Returns the Availability Zone in which the volume was created.

Returns:

  • (AvailabilityZone) —

    Returns the Availability Zone in which the volume was created.



170
171
172
173
174
 
# File 'lib/aws/ec2/volume.rb', line 170

def availability_zone
  if name = availability_zone_name
    AvailabilityZone.new(name, :config => config)
  end
end

#create_snapshot(description = nil) ⇒ Snapshot

Returns A new snapshot created from the volume.

Parameters:

  • description (String) (defaults to: nil) —

    An optional description of the snapshot. May be up to 255 characters in length.

Returns:

  • (Snapshot) —

    A new snapshot created from the volume.



112
113
114
115
116
 
# File 'lib/aws/ec2/volume.rb', line 112

def create_snapshot description = nil
  opts = { :volume => self }
  opts[:description] = description if description
  SnapshotCollection.new(:config => config).create(opts)
end

#delete ⇒ Object

Deletes the volume.



103
104
105
106
 
# File 'lib/aws/ec2/volume.rb', line 103

def delete
  client.delete_volume(:volume_id => id)
  nil
end

#detach_from(instance, device, options = {}) ⇒ Attachment

Detaches the volume from an instance.

Parameters:

  • instance (Instance) —

    The instance to detach from.

  • device (String) —

    The device name.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :force (Boolean) —

    Forces detachment if the previous detachment attempt did not occur cleanly (logging into an instance, unmounting the volume, and detaching normally). This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance will not have an opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures.

Returns:

  • (Attachment) —

    Returns the no-longer valid attachment.



147
148
149
150
151
152
 
# File 'lib/aws/ec2/volume.rb', line 147

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

#exists? ⇒ Boolean

Returns True if the volume exists.

Returns:

  • (Boolean) —

    True if the volume exists.



155
156
157
158
159
160
 
# File 'lib/aws/ec2/volume.rb', line 155

def exists?
  resp = client.describe_volumes(:filters => [
    { :name => 'volume-id', :values => [id] }
  ])
  resp.volume_index.key?(id)
end

#snapshot ⇒ Snapshot

Returns Snapshot from which the volume was created (may be nil).

Returns:

  • (Snapshot) —

    Snapshot from which the volume was created (may be nil).



164
165
166
 
# File 'lib/aws/ec2/volume.rb', line 164

def snapshot
  snapshot_id ? Snapshot.new(snapshot_id, :config => config) : nil
end