Class: Aws::EC2::Volume

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

Defined Under Namespace

Classes: Collection

Read-Only Attributes collapse

Actions collapse

Associations 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 '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 (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:



277
278
279
280
281
 
# File 'lib/aws-sdk-ec2/volume.rb', line 277

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

#attachments ⇒ Array<Types::VolumeAttachment>

Information about the volume attachments.

Returns:



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

def attachments
  data[:attachments]
end

#availability_zone ⇒ String

The Availability Zone for the volume.

Returns:

  • (String) 


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

def availability_zone
  data[:availability_zone]
end

#client ⇒ Client

Returns:



130
131
132
 
# File 'lib/aws-sdk-ec2/volume.rb', line 130

def client
  @client
end

#create_snapshot(options = {}) ⇒ Snapshot

Examples:

Request syntax with placeholder values


snapshot = volume.create_snapshot({
  description: "String",
  tag_specifications: [
    {
      resource_type: "customer-gateway", # accepts customer-gateway, dedicated-host, dhcp-options, elastic-ip, fleet, fpga-image, image, instance, internet-gateway, launch-template, natgateway, network-acl, network-interface, reserved-instances, route-table, security-group, snapshot, spot-instances-request, subnet, transit-gateway, transit-gateway-attachment, transit-gateway-route-table, volume, vpc, vpc-peering-connection, vpn-connection, vpn-gateway
      tags: [
        {
          key: "String",
          value: "String",
        },
      ],
    },
  ],
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :description (String) —

    A description for the snapshot.

  • :tag_specifications (Array<Types::TagSpecification>) —

    The tags to apply to the snapshot during creation.

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



311
312
313
314
315
316
317
318
319
 
# File 'lib/aws-sdk-ec2/volume.rb', line 311

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:



343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/aws-sdk-ec2/volume.rb', line 343

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_time ⇒ Time

The time stamp when volume creation was initiated.

Returns:

  • (Time) 


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

def create_time
  data[:create_time]
end

#data ⇒ Types::Volume

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

Returns:



150
151
152
153
 
# File 'lib/aws-sdk-ec2/volume.rb', line 150

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.



158
159
160
 
# File 'lib/aws-sdk-ec2/volume.rb', line 158

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) 


370
371
372
373
374
 
# File 'lib/aws-sdk-ec2/volume.rb', line 370

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", # required, accepts autoEnableIO, productCodes
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :attribute (required, 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:



391
392
393
394
395
 
# File 'lib/aws-sdk-ec2/volume.rb', line 391

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:



467
468
469
470
471
 
# File 'lib/aws-sdk-ec2/volume.rb', line 467

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:



501
502
503
504
505
 
# File 'lib/aws-sdk-ec2/volume.rb', line 501

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) 


519
520
521
522
523
 
# File 'lib/aws-sdk-ec2/volume.rb', line 519

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

#encrypted ⇒ Boolean

Indicates whether the volume will be encrypted.

Returns:

  • (Boolean) 


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

def encrypted
  data[:encrypted]
end

#id ⇒ String Also known as: volume_id

Returns:

  • (String) 


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

def id
  @id
end

#identifiers ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated. 


641
642
643
 
# File 'lib/aws-sdk-ec2/volume.rb', line 641

def identifiers
  { id: @id }
end

#iops ⇒ Integer

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 about General Purpose SSD baseline performance, I/O credits, and bursting, see [Amazon EBS Volume Types] in the *Amazon Elastic Compute Cloud User Guide*.

Constraints: Range is 100-16,000 IOPS for ‘gp2` volumes and 100 to 64,000IOPS for `io1` volumes in most regions. Maximum `io1`IOPS of 64,000 is guaranteed only on [Nitro-based instances](AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances). Other instance families guarantee performance up to 32,000 IOPS. For more information, see [Amazon EBS Volume Types] in the *Amazon Elastic Compute Cloud User Guide*.

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.

[1]: docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

Returns:

  • (Integer) 


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

def iops
  data[:iops]
end

#kms_key_id ⇒ String

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 'lib/aws-sdk-ec2/volume.rb', line 62

def kms_key_id
  data[:kms_key_id]
end

#load ⇒ self 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) 


140
141
142
143
144
 
# File 'lib/aws-sdk-ec2/volume.rb', line 140

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) 


543
544
545
546
547
 
# File 'lib/aws-sdk-ec2/volume.rb', line 543

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

#size ⇒ Integer

The size of the volume, in GiBs.

Returns:

  • (Integer) 


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

def size
  data[:size]
end

#snapshot_id ⇒ String

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

Returns:

  • (String) 


74
75
76
 
# File '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`:&lt;key&gt; - The key/value combination of a tag assigned to the resource. Use the tag key in the filter name and the tag value as the filter value. For example, to find all resources that have a tag with the key `Owner` and the value `TeamA`, specify `tag:Owner` for the filter name and `TeamA` for the filter value.

    • ‘tag-key` - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value.

    • ‘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:



617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
 
# File 'lib/aws-sdk-ec2/volume.rb', line 617

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

#state ⇒ String

The volume state.

Returns:

  • (String) 


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

def state
  data[:state]
end

#tags ⇒ Array<Types::Tag>

Any tags assigned to the volume.

Returns:



115
116
117
 
# File 'lib/aws-sdk-ec2/volume.rb', line 115

def tags
  data[:tags]
end

#volume_type ⇒ String

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) 


123
124
125
 
# File 'lib/aws-sdk-ec2/volume.rb', line 123

def volume_type
  data[:volume_type]
end

#wait_until(options = {}, &block) ⇒ Resource

Deprecated.

Use [Aws::EC2::Client] #wait_until instead

Note:

The waiting operation is performed on a copy. The original resource remains unchanged

Waiter polls an API operation until a resource enters a desired state.

## Basic Usage

Waiter will polls until it is successful, it fails by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop until condition is true
resource.wait_until(options) {|resource| condition}

## Example

instance.wait_until(max_attempts:10, delay:5) {|instance| instance.state.name == 'running' }

## Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. The waiting condition is set by passing a block to #wait_until:

# poll for ~25 seconds
resource.wait_until(max_attempts:5,delay:5) {|resource|...}

## Callbacks

You can be notified before each polling attempt and before each delay. If you throw ‘:success` or `:failure` from these callbacks, it will terminate the waiter.

started_at = Time.now
# poll for 1 hour, instead of a number of attempts
proc = Proc.new do |attempts, response|
  throw :failure if Time.now - started_at > 3600
end

  # disable max attempts
instance.wait_until(before_wait:proc, max_attempts:nil) {...}

## Handling Errors

When a waiter is successful, it returns the Resource. When a waiter fails, it raises an error.

begin
  resource.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

attempts attempt in seconds invoked before each attempt invoked before each wait

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :max_attempts (Integer) — default: 10 —

    Maximum number of

  • :delay (Integer) — default: 10 —

    Delay between each

  • :before_attempt (Proc) — default: nil —

    Callback

  • :before_wait (Proc) — default: nil —

    Callback

Returns:

  • (Resource) —

    if the waiter was successful

Raises:

  • (Aws::Waiters::Errors::FailureStateError) —

    Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

    yet successful.

  • (Aws::Waiters::Errors::UnexpectedError) —

    Raised when an error is encountered while polling for a resource that is not expected.

  • (NotImplementedError) —

    Raised when the resource does not



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/aws-sdk-ec2/volume.rb', line 240

def wait_until(options = {}, &block)
  self_copy = self.dup
  attempts = 0
  options[:max_attempts] = 10 unless options.key?(:max_attempts)
  options[:delay] ||= 10
  options[:poller] = Proc.new do
    attempts += 1
    if block.call(self_copy)
      [:success, self_copy]
    else
      self_copy.reload unless attempts == options[:max_attempts]
      :retry
    end
  end
  Aws::Waiters::Waiter.new(options).wait({})
end