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:



274
275
276
277
278
 
# File 'lib/aws-sdk-ec2/volume.rb', line 274

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:



127
128
129
 
# File 'lib/aws-sdk-ec2/volume.rb', line 127

def client
  @client
end

#create_snapshot(options = {}) ⇒ Snapshot

Examples:

Request syntax with placeholder values


snapshot = volume.create_snapshot({
  description: "String",
  tag_specifications: [
    {
      resource_type: "client-vpn-endpoint", # accepts client-vpn-endpoint, 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:



308
309
310
311
312
313
314
315
316
 
# File 'lib/aws-sdk-ec2/volume.rb', line 308

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:



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

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:



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

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.



155
156
157
 
# File 'lib/aws-sdk-ec2/volume.rb', line 155

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) 


367
368
369
370
371
 
# File 'lib/aws-sdk-ec2/volume.rb', line 367

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:



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

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:



464
465
466
467
468
 
# File 'lib/aws-sdk-ec2/volume.rb', line 464

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:



498
499
500
501
502
 
# File 'lib/aws-sdk-ec2/volume.rb', line 498

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) 


516
517
518
519
520
 
# File 'lib/aws-sdk-ec2/volume.rb', line 516

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. 


638
639
640
 
# File 'lib/aws-sdk-ec2/volume.rb', line 638

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, 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. The maximum IOPS for `io1` of 64,000 is guaranteed only on [Nitro-based instances]. Other instance families guarantee performance up to 32,000 IOPS.

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 [2]: docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances

Returns:

  • (Integer) 


106
107
108
 
# File 'lib/aws-sdk-ec2/volume.rb', line 106

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) 


137
138
139
140
141
 
# File 'lib/aws-sdk-ec2/volume.rb', line 137

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) 


540
541
542
543
544
 
# File 'lib/aws-sdk-ec2/volume.rb', line 540

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>) —

    Describes the snapshots owned by one or more owners.

  • :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 the snapshots for which you have create volume 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:



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

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:



112
113
114
 
# File 'lib/aws-sdk-ec2/volume.rb', line 112

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) 


120
121
122
 
# File 'lib/aws-sdk-ec2/volume.rb', line 120

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



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

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