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

Class: Aws::EC2::Volume

Inherits:
Object
  • Object
show all
Defined in:
gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb

Defined Under Namespace

Classes: Collection

Actions collapse

Associations collapse

Read-Only Attributes collapse

Instance Method Summary collapse

Constructor Details

#initialize(id, options = {}) ⇒ Volume #initialize(options = {}) ⇒ Volume

Returns a new instance of Volume

Overloads:

  • #initialize(id, options = {}) ⇒ Volume

    Parameters:

    • id (String)

    Options Hash (options):

  • #initialize(options = {}) ⇒ Volume

    Options Hash (options):

    • :id (required, String)
    • :client (Client)


19
20
21
22
23
24
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 19

def initialize(*args)
  options = Hash === args.last ? args.pop.dup : {}
  @id = extract_id(args, options)
  @data = options.delete(:data)
  @client = options.delete(:client) || Client.new(options)
end

Instance Method Details

#attach_to_instance(options = {}) ⇒ Types::VolumeAttachment

Examples:

Request syntax with placeholder values


volume.attach_to_instance({
  device: "String", # required
  instance_id: "String", # required
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :device (required, String)

    The device name to expose to the instance (for example, /dev/sdh or xvdh).

  • :instance_id (required, String)

    The ID of the instance.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:



178
179
180
181
182
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 178

def attach_to_instance(options = {})
  options = options.merge(volume_id: @id)
  resp = @client.attach_volume(options)
  resp.data
end

#attachmentsArray<Types::VolumeAttachment>

Information about the volume attachments.

Returns:



36
37
38
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 36

def attachments
  data.attachments
end

#availability_zoneString

The Availability Zone for the volume.

Returns:

  • (String)


42
43
44
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 42

def availability_zone
  data.availability_zone
end

#clientClient

Returns:



125
126
127
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 125

def client
  @client
end

#create_snapshot(options = {}) ⇒ Snapshot

Examples:

Request syntax with placeholder values


snapshot = volume.create_snapshot({
  description: "String",
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :description (String)

    A description for the snapshot.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:



199
200
201
202
203
204
205
206
207
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 199

def create_snapshot(options = {})
  options = options.merge(volume_id: @id)
  resp = @client.create_snapshot(options)
  Snapshot.new(
    id: resp.data.snapshot_id,
    data: resp.data,
    client: @client
  )
end

#create_tags(options = {}) ⇒ Tag::Collection

Examples:

Request syntax with placeholder values


tag = volume.create_tags({
  dry_run: false,
  tags: [ # required
    {
      key: "String",
      value: "String",
    },
  ],
})

Parameters:

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

    ({})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :tags (required, Array<Types::Tag>)

    One or more tags. The value parameter is required, but if you don't want the tag to have a value, specify the parameter with no value, and we set the value to an empty string.

Returns:



231
232
233
234
235
236
237
238
239
240
241
242
243
244
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 231

def create_tags(options = {})
  batch = []
  options = Aws::Util.deep_merge(options, resources: [@id])
  resp = @client.create_tags(options)
  options[:tags].each do |t|
    batch << Tag.new(
      resource_id: @id,
      key: t[:key],
      value: t[:value],
      client: @client
    )
  end
  Tag::Collection.new([batch], size: batch.size)
end

#create_timeTime

The time stamp when volume creation was initiated.

Returns:

  • (Time)


48
49
50
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 48

def create_time
  data.create_time
end

#dataTypes::Volume

Returns the data for this Aws::EC2::Volume. Calls Client#describe_volumes if #data_loaded? is false.

Returns:



145
146
147
148
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 145

def data
  load unless @data
  @data
end

#data_loaded?Boolean

Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.

Returns:

  • (Boolean)

    Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.



153
154
155
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 153

def data_loaded?
  !!@data
end

#delete(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


volume.delete({
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (EmptyStructure)


258
259
260
261
262
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 258

def delete(options = {})
  options = options.merge(volume_id: @id)
  resp = @client.delete_volume(options)
  resp.data
end

#describe_attribute(options = {}) ⇒ Types::DescribeVolumeAttributeResult

Examples:

Request syntax with placeholder values


volume.describe_attribute({
  attribute: "autoEnableIO", # accepts autoEnableIO, productCodes
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :attribute (String)

    The attribute of the volume. This parameter is required.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:



279
280
281
282
283
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 279

def describe_attribute(options = {})
  options = options.merge(volume_id: @id)
  resp = @client.describe_volume_attribute(options)
  resp.data
end

#describe_status(options = {}) ⇒ Types::DescribeVolumeStatusResult

Examples:

Request syntax with placeholder values


volume.describe_status({
  filters: [
    {
      name: "String",
      values: ["String"],
    },
  ],
  max_results: 1,
  next_token: "String",
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :filters (Array<Types::Filter>)

    One or more filters.

    • action.code - The action code for the event (for example, enable-volume-io).

    • action.description - A description of the action.

    • action.event-id - The event ID associated with the action.

    • availability-zone - The Availability Zone of the instance.

    • event.description - A description of the event.

    • event.event-id - The event ID.

    • event.event-type - The event type (for io-enabled: passed | failed; for io-performance: io-performance:degraded | io-performance:severely-degraded | io-performance:stalled).

    • event.not-after - The latest end time for the event.

    • event.not-before - The earliest start time for the event.

    • volume-status.details-name - The cause for volume-status.status (io-enabled | io-performance).

    • volume-status.details-status - The status of volume-status.details-name (for io-enabled: passed | failed; for io-performance: normal | degraded | severely-degraded | stalled).

    • volume-status.status - The status of the volume (ok | impaired | warning | insufficient-data).

  • :max_results (Integer)

    The maximum number of volume results returned by DescribeVolumeStatus in paginated output. When this parameter is used, the request only returns MaxResults results in a single page along with a NextToken response element. The remaining results of the initial request can be seen by sending another request with the returned NextToken value. This value can be between 5 and 1000; if MaxResults is given a value larger than 1000, only 1000 results are returned. If this parameter is not used, then DescribeVolumeStatus returns all results. You cannot specify this parameter and the volume IDs parameter in the same request.

  • :next_token (String)

    The NextToken value to include in a future DescribeVolumeStatus request. When the results of the request exceed MaxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:



355
356
357
358
359
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 355

def describe_status(options = {})
  options = Aws::Util.deep_merge(options, volume_ids: [@id])
  resp = @client.describe_volume_status(options)
  resp.data
end

#detach_from_instance(options = {}) ⇒ Types::VolumeAttachment

Examples:

Request syntax with placeholder values


volume.detach_from_instance({
  device: "String",
  force: false,
  instance_id: "String",
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :device (String)

    The device name.

  • :force (Boolean)

    Forces detachment if the previous detachment attempt did not occur cleanly (for example, 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 won't 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.

  • :instance_id (String)

    The ID of the instance.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:



389
390
391
392
393
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 389

def detach_from_instance(options = {})
  options = options.merge(volume_id: @id)
  resp = @client.detach_volume(options)
  resp.data
end

#enable_io(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


volume.enable_io({
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (EmptyStructure)


407
408
409
410
411
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 407

def enable_io(options = {})
  options = options.merge(volume_id: @id)
  resp = @client.enable_volume_io(options)
  resp.data
end

#encryptedBoolean

Indicates whether the volume will be encrypted.

Returns:

  • (Boolean)


54
55
56
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 54

def encrypted
  data.encrypted
end

#idString Also known as: volume_id

Returns:

  • (String)


29
30
31
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 29

def id
  @id
end

#iopsInteger

The number of I/O operations per second (IOPS) that the volume supports. For Provisioned IOPS SSD volumes, this represents the number of IOPS that are provisioned for the volume. For General Purpose SSD volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting. For more information on General Purpose SSD baseline performance, I/O credits, and bursting, see Amazon EBS Volume Types in the Amazon Elastic Compute Cloud User Guide.

Constraint: Range is 100-20000 IOPS for io1 volumes and 100-10000 IOPS for gp2 volumes.

Condition: This parameter is required for requests to create io1 volumes; it is not used in requests to create gp2, st1, sc1, or standard volumes.

Returns:

  • (Integer)


104
105
106
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 104

def iops
  data.iops
end

#kms_key_idString

The full ARN of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to protect the volume encryption key for the volume.

Returns:

  • (String)


62
63
64
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 62

def kms_key_id
  data.kms_key_id
end

#loadself Also known as: reload

Loads, or reloads #data for the current Aws::EC2::Volume. Returns self making it possible to chain methods.

volume.reload.data

Returns:

  • (self)


135
136
137
138
139
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 135

def load
  resp = @client.describe_volumes(volume_ids: [@id])
  @data = resp.volumes[0]
  self
end

#modify_attribute(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


volume.modify_attribute({
  auto_enable_io: {
    value: false,
  },
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :auto_enable_io (Types::AttributeBooleanValue)

    Indicates whether the volume should be auto-enabled for I/O operations.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (EmptyStructure)


431
432
433
434
435
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 431

def modify_attribute(options = {})
  options = options.merge(volume_id: @id)
  resp = @client.modify_volume_attribute(options)
  resp.data
end

#sizeInteger

The size of the volume, in GiBs.

Returns:

  • (Integer)


68
69
70
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 68

def size
  data.size
end

#snapshot_idString

The snapshot from which the volume was created, if applicable.

Returns:

  • (String)


74
75
76
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 74

def snapshot_id
  data.snapshot_id
end

#snapshots(options = {}) ⇒ Snapshot::Collection

Examples:

Request syntax with placeholder values


snapshots = volume.snapshots({
  filters: [
    {
      name: "String",
      values: ["String"],
    },
  ],
  owner_ids: ["String"],
  restorable_by_user_ids: ["String"],
  snapshot_ids: ["String"],
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :filters (Array<Types::Filter>)

    One or more filters.

    • description - A description of the snapshot.

    • owner-alias - Value from an Amazon-maintained list (amazon | aws-marketplace | microsoft) of snapshot owners. Not to be confused with the user-configured AWS account alias, which is set from the IAM console.

    • owner-id - The ID of the AWS account that owns the snapshot.

    • progress - The progress of the snapshot, as a percentage (for example, 80%).

    • snapshot-id - The snapshot ID.

    • start-time - The time stamp when the snapshot was initiated.

    • status - The status of the snapshot (pending | completed | error).

    • tag:key=value - The key/value combination of a tag assigned to the resource. Specify the key of the tag in the filter name and the value of the tag in the filter value. For example, for the tag Purpose=X, specify tag:Purpose for the filter name and X for the filter value.

    • tag-key - The key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter "tag-key=Purpose" and the filter "tag-value=X", you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose is X, see the tag:key=value filter.

    • tag-value - The value of a tag assigned to the resource. This filter is independent of the tag-key filter.

    • volume-id - The ID of the volume the snapshot is for.

    • volume-size - The size of the volume, in GiB.

  • :owner_ids (Array<String>)

    Returns the snapshots owned by the specified owner. Multiple owners can be specified.

  • :restorable_by_user_ids (Array<String>)

    One or more AWS accounts IDs that can create volumes from the snapshot.

  • :snapshot_ids (Array<String>)

    One or more snapshot IDs.

    Default: Describes snapshots for which you have launch permissions.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:



512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 512

def snapshots(options = {})
  batches = Enumerator.new do |y|
    options = Aws::Util.deep_merge(options, filters: [{
      name: "volume-id",
      values: [@id]
    }])
    resp = @client.describe_snapshots(options)
    resp.each_page do |page|
      batch = []
      page.data.snapshots.each do |s|
        batch << Snapshot.new(
          id: s.snapshot_id,
          data: s,
          client: @client
        )
      end
      y.yield(batch)
    end
  end
  Snapshot::Collection.new(batches)
end

#stateString

The volume state.

Returns:

  • (String)


80
81
82
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 80

def state
  data.state
end

#tagsArray<Types::Tag>

Any tags assigned to the volume.

Returns:



110
111
112
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 110

def tags
  data.tags
end

#volume_typeString

The volume type. This can be gp2 for General Purpose SSD, io1 for Provisioned IOPS SSD, st1 for Throughput Optimized HDD, sc1 for Cold HDD, or standard for Magnetic volumes.

Returns:

  • (String)


118
119
120
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/volume.rb', line 118

def volume_type
  data.volume_type
end