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

Class: Aws::EC2::Snapshot

Inherits:

Resources::Resource

Object
Resources::Resource
Aws::EC2::Snapshot

show all

Defined in:: (unknown)

Instance Attribute Summary collapse

#data_encryption_key_id ⇒ String readonly
The data encryption key identifier for the snapshot.
#description ⇒ String readonly
The description for the snapshot.
#encrypted ⇒ Boolean readonly
Indicates whether the snapshot is encrypted.
#id ⇒ String readonly
#kms_key_id ⇒ String readonly
The Amazon Resource Name (ARN) of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to protect the volume encryption key for the parent volume.
#owner_alias ⇒ String readonly
The AWS owner alias, from an Amazon-maintained list (amazon).
#owner_id ⇒ String readonly
The AWS account ID of the EBS snapshot owner.
#progress ⇒ String readonly
The progress of the snapshot, as a percentage.
#snapshot_id ⇒ String readonly
The ID of the snapshot.
#start_time ⇒ Time readonly
The time stamp when the snapshot was initiated.
#state ⇒ String readonly
The snapshot state.
#state_message ⇒ String readonly
Encrypted Amazon EBS snapshots are copied asynchronously.
#tags ⇒ Array<Types::Tag> readonly
Any tags assigned to the snapshot.
#volume_id ⇒ String readonly
The ID of the volume that was used to create the snapshot.
#volume_size ⇒ Integer readonly
The size of the volume, in GiB.

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

#copy(options = {}) ⇒ Types::CopySnapshotResult
Copies a point-in-time snapshot of an EBS volume and stores it in Amazon S3.
#create_tags(options = {}) ⇒ Array<Tag>
#delete(options = {}) ⇒ Struct
Deletes the specified snapshot.

When you make periodic snapshots of a volume, the snapshots are incremental, and only the blocks on the device that have changed since your last snapshot are saved in the new snapshot.
#delete_tags(options = {}) ⇒ Array<Tag>
#describe_attribute(options = {}) ⇒ Types::DescribeSnapshotAttributeResult
Describes the specified attribute of the specified snapshot.
#initialize ⇒ Object constructor
#modify_attribute(options = {}) ⇒ Struct
Adds or removes permission settings for the specified snapshot.
#reset_attribute(options = {}) ⇒ Struct
Resets permission settings for the specified snapshot.

For more information about modifying snapshot permissions, see Sharing snapshots in the Amazon Elastic Compute Cloud User Guide.
.
#volume ⇒ Volume^?
#wait_until_completed {|waiter| ... } ⇒ Snapshot
Waits until this Snapshot is completed.

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #load, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

#initialize(id, options = {}) ⇒ `Object` #initialize(options = {}) ⇒ `Object`

Overloads:

#initialize(id, options = {}) ⇒ Object
Parameters:
- id (String)
Options Hash (options):
- :client (Client) —
  When `:client is not given, the options hash is used to construct a new Client object.
#initialize(options = {}) ⇒ Object
Options Hash (options):
- :id (required, String)
- :client (Client) —
  When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#data_encryption_key_id ⇒ `String` (readonly)

The data encryption key identifier for the snapshot. This value is a unique identifier that corresponds to the data encryption key that was used to encrypt the original volume or snapshot copy. Because data encryption keys are inherited by volumes created from snapshots, and vice versa, if snapshots share the same data encryption key identifier, then they belong to the same volume/snapshot lineage. This parameter is only returned by DescribeSnapshots.

Returns:

(String) —
The data encryption key identifier for the snapshot.

#description ⇒ `String` (readonly)

The description for the snapshot.

Returns:

(String) —
The description for the snapshot.

#encrypted ⇒ `Boolean` (readonly)

Indicates whether the snapshot is encrypted.

Returns:

(Boolean) —
Indicates whether the snapshot is encrypted.

#id ⇒ `String` (readonly)

Returns:

(String)

#kms_key_id ⇒ `String` (readonly)

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

Returns:

(String) —
The Amazon Resource Name (ARN) of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to protect the volume encryption key for the parent volume.

#owner_alias ⇒ `String` (readonly)

The AWS owner alias, from an Amazon-maintained list (amazon). This is not the user-configured AWS account alias set using the IAM console.

Returns:

(String) —
The AWS owner alias, from an Amazon-maintained list (amazon).

#owner_id ⇒ `String` (readonly)

The AWS account ID of the EBS snapshot owner.

Returns:

(String) —
The AWS account ID of the EBS snapshot owner.

#progress ⇒ `String` (readonly)

The progress of the snapshot, as a percentage.

Returns:

(String) —
The progress of the snapshot, as a percentage.

#snapshot_id ⇒ `String` (readonly)

The ID of the snapshot. Each snapshot receives a unique identifier when it is created.

Returns:

(String) —
The ID of the snapshot.

#start_time ⇒ `Time` (readonly)

The time stamp when the snapshot was initiated.

Returns:

(Time) —
The time stamp when the snapshot was initiated.

#state ⇒ `String` (readonly)

The snapshot state.

Possible values:

pending
completed
error

Returns:

(String) —
The snapshot state.

#state_message ⇒ `String` (readonly)

Encrypted Amazon EBS snapshots are copied asynchronously. If a snapshot copy operation fails (for example, if the proper AWS Key Management Service (AWS KMS) permissions are not obtained) this field displays error state details to help you diagnose why the error occurred. This parameter is only returned by DescribeSnapshots.

Returns:

(String) —
Encrypted Amazon EBS snapshots are copied asynchronously.

#tags ⇒ `Array<Types::Tag>` (readonly)

Any tags assigned to the snapshot.

Returns:

(Array<Types::Tag>) —
Any tags assigned to the snapshot.

#volume_id ⇒ `String` (readonly)

The ID of the volume that was used to create the snapshot. Snapshots created by the CopySnapshot action have an arbitrary volume ID that should not be used for any purpose.

Returns:

(String) —
The ID of the volume that was used to create the snapshot.

#volume_size ⇒ `Integer` (readonly)

The size of the volume, in GiB.

Returns:

(Integer) —
The size of the volume, in GiB.

Instance Method Details

#copy(options = {}) ⇒ `Types::CopySnapshotResult`

Copies a point-in-time snapshot of an EBS volume and stores it in Amazon S3. You can copy the snapshot within the same Region or from one Region to another. You can use the snapshot to create EBS volumes or Amazon Machine Images (AMIs).

Copies of encrypted EBS snapshots remain encrypted. Copies of unencrypted snapshots remain unencrypted, unless you enable encryption for the snapshot copy operation. By default, encrypted snapshot copies use the default AWS Key Management Service (AWS KMS) customer master key (CMK); however, you can specify a different CMK.

To copy an encrypted snapshot that has been shared from another account, you must have permissions for the CMK used to encrypt the snapshot.

Snapshots created by copying another snapshot have an arbitrary volume ID that should not be used for any purpose.

For more information, see Copying an Amazon EBS snapshot in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


snapshot.copy({
  description: "String",
  encrypted: false,
  kms_key_id: "KmsKeyId",
  source_region: "String", # required
  tag_specifications: [
    {
      resource_type: "client-vpn-endpoint", # accepts client-vpn-endpoint, customer-gateway, dedicated-host, dhcp-options, egress-only-internet-gateway, elastic-ip, elastic-gpu, export-image-task, export-instance-task, fleet, fpga-image, host-reservation, image, import-image-task, import-snapshot-task, instance, internet-gateway, key-pair, launch-template, local-gateway-route-table-vpc-association, natgateway, network-acl, network-interface, placement-group, reserved-instances, route-table, security-group, snapshot, spot-fleet-request, spot-instances-request, subnet, traffic-mirror-filter, traffic-mirror-session, traffic-mirror-target, transit-gateway, transit-gateway-attachment, transit-gateway-multicast-domain, transit-gateway-route-table, volume, vpc, vpc-peering-connection, vpn-connection, vpn-gateway, vpc-flow-log
      tags: [
        {
          key: "String",
          value: "String",
        },
      ],
    },
  ],
  dry_run: false,
})

Options Hash (options):

:description (String) —
A description for the EBS snapshot.
:encrypted (Boolean) —
To encrypt a copy of an unencrypted snapshot if encryption by default is not enabled, enable encryption using this parameter. Otherwise, omit this parameter. Encrypted snapshots are encrypted, even if you omit this parameter and encryption by default is not enabled. You cannot set this parameter to false. For more information, see Amazon EBS Encryption in the Amazon Elastic Compute Cloud User Guide.
:kms_key_id (String) —
The identifier of the AWS Key Management Service (AWS KMS) customer master key (CMK) to use for Amazon EBS encryption. If this parameter is not specified, your AWS managed CMK for EBS is used. If KmsKeyId is specified, the encrypted state must be true.

You can specify the CMK using any of the following:
- Key ID. For example, 1234abcd-12ab-34cd-56ef-1234567890ab.
- Key alias. For example, alias/ExampleAlias.
- Key ARN. For example, arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab.
- Alias ARN. For example, arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias.
AWS authenticates the CMK asynchronously. Therefore, if you specify an ID, alias, or ARN that is not valid, the action can appear to complete, but eventually fails.
:source_region (required, String) —
The ID of the Region that contains the snapshot to be copied.
:tag_specifications (Array<Types::TagSpecification>) —
The tags to apply to the new 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:

(Types::CopySnapshotResult) —
Returns a response object which responds to the following methods:
- #snapshot_id => String
- #tags => Array<Types::Tag>

See Also:

Client#copy_snapshot

#create_tags(options = {}) ⇒ `Array<Tag>`

Examples:

Request syntax example with placeholder values


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

Basic usage

tags = snapshot.create_tags(options)
tags.map(&:value)
#=> ["tag-value", ...]

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

(Array<Tag>)

See Also:

#delete(options = {}) ⇒ `Struct`

Deletes the specified snapshot.

When you make periodic snapshots of a volume, the snapshots are incremental, and only the blocks on the device that have changed since your last snapshot are saved in the new snapshot. When you delete a snapshot, only the data not needed for any other snapshot is removed. So regardless of which prior snapshots have been deleted, all active snapshots will have access to all the information needed to restore the volume.

You cannot delete a snapshot of the root device of an EBS volume used by a registered AMI. You must first de-register the AMI before you can delete the snapshot.

For more information, see Deleting an Amazon EBS snapshot in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


snapshot.delete({
  dry_run: false,
})

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:

(Struct) —
Returns an empty response.

See Also:

Client#delete_snapshot

#delete_tags(options = {}) ⇒ `Array<Tag>`

Examples:

Request syntax example with placeholder values


snapshot.delete_tags({
  dry_run: false,
  tags: [
    {
      key: "String",
      value: "String",
    },
  ],
})

Basic usage

tags = snapshot.delete_tags(options)
tags.map(&:value)
#=> ["tag-value", ...]

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 (Array<Types::Tag>) —
The tags to delete. Specify a tag key and an optional tag value to delete specific tags. If you specify a tag key without a tag value, we delete any tag with this key regardless of its value. If you specify a tag key with an empty string as the tag value, we delete the tag only if its value is an empty string.

If you omit this parameter, we delete all user-defined tags for the specified resources. We do not delete AWS-generated tags (tags that have the aws: prefix).

Returns:

(Array<Tag>)

See Also:

#describe_attribute(options = {}) ⇒ `Types::DescribeSnapshotAttributeResult`

Describes the specified attribute of the specified snapshot. You can specify only one attribute at a time.

For more information about EBS snapshots, see Amazon EBS Snapshots in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


snapshot.describe_attribute({
  attribute: "productCodes", # required, accepts productCodes, createVolumePermission
  dry_run: false,
})

Options Hash (options):

:attribute (required, String) —
The snapshot attribute you would like to view.
: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:

(Types::DescribeSnapshotAttributeResult) —
Returns a response object which responds to the following methods:
- #create_volume_permissions => Array<Types::CreateVolumePermission>
- #product_codes => Array<Types::ProductCode>
- #snapshot_id => String

See Also:

Client#describe_snapshot_attribute

#modify_attribute(options = {}) ⇒ `Struct`

Adds or removes permission settings for the specified snapshot. You may add or remove specified AWS account IDs from a snapshot's list of create volume permissions, but you cannot do both in a single operation. If you need to both add and remove account IDs for a snapshot, you must use multiple operations. You can make up to 500 modifications to a snapshot in a single operation.

Encrypted snapshots and snapshots with AWS Marketplace product codes cannot be made public. Snapshots encrypted with your default CMK cannot be shared with other accounts.

For more information about modifying snapshot permissions, see Sharing snapshots in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


snapshot.modify_attribute({
  attribute: "productCodes", # accepts productCodes, createVolumePermission
  create_volume_permission: {
    add: [
      {
        group: "all", # accepts all
        user_id: "String",
      },
    ],
    remove: [
      {
        group: "all", # accepts all
        user_id: "String",
      },
    ],
  },
  group_names: ["SecurityGroupName"],
  operation_type: "add", # accepts add, remove
  user_ids: ["String"],
  dry_run: false,
})

Options Hash (options):

:attribute (String) —
The snapshot attribute to modify. Only volume creation permissions can be modified.
:create_volume_permission (Types::CreateVolumePermissionModifications) —
A JSON representation of the snapshot attribute modification.
:group_names (Array<String>) —
The group to modify for the snapshot.
:operation_type (String) —
The type of operation to perform to the attribute.
:user_ids (Array<String>) —
The account ID to modify 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:

(Struct) —
Returns an empty response.

See Also:

Client#modify_snapshot_attribute

#reset_attribute(options = {}) ⇒ `Struct`

Resets permission settings for the specified snapshot.

For more information about modifying snapshot permissions, see Sharing snapshots in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


snapshot.reset_attribute({
  attribute: "productCodes", # required, accepts productCodes, createVolumePermission
  dry_run: false,
})

Options Hash (options):

:attribute (required, String) —
The attribute to reset. Currently, only the attribute for permission to create volumes can be reset.
: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:

(Struct) —
Returns an empty response.

See Also:

Client#reset_snapshot_attribute

#volume ⇒ `Volume`^?

Returns:

(Volume, nil)

#wait_until_completed {|waiter| ... } ⇒ `Snapshot`

Waits until this Snapshot is completed. This method waits by polling Client#describe_snapshots until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration	Default
`#delay`	15
`#max_attempts`	40

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

snapshot.wait_until_completed

Yield Parameters:

waiter (Waiters::Waiter)

Returns:

(Snapshot) —
Returns a copy of this Snapshot with loaded data.

Raises:

(Waiters::Errors::WaiterFailed)

See Also:

Client#wait_until

Class: Aws::EC2::Snapshot

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

Instance Method Summary collapse

Methods inherited from Resources::Resource

Methods included from Resources::OperationMethods

Constructor Details

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

Instance Attribute Details

#data_encryption_key_id ⇒ String (readonly)

#description ⇒ String (readonly)

#encrypted ⇒ Boolean (readonly)

#id ⇒ String (readonly)

#kms_key_id ⇒ String (readonly)

#owner_alias ⇒ String (readonly)

#owner_id ⇒ String (readonly)

#progress ⇒ String (readonly)

#snapshot_id ⇒ String (readonly)

#start_time ⇒ Time (readonly)

#state ⇒ String (readonly)

#state_message ⇒ String (readonly)

#tags ⇒ Array<Types::Tag> (readonly)

#volume_id ⇒ String (readonly)

#volume_size ⇒ Integer (readonly)

Instance Method Details

#copy(options = {}) ⇒ Types::CopySnapshotResult

#create_tags(options = {}) ⇒ Array<Tag>

#delete(options = {}) ⇒ Struct

#delete_tags(options = {}) ⇒ Array<Tag>

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

#modify_attribute(options = {}) ⇒ Struct

#reset_attribute(options = {}) ⇒ Struct

#volume ⇒ Volume?

#wait_until_completed {|waiter| ... } ⇒ Snapshot

#initialize(id, options = {}) ⇒ `Object` #initialize(options = {}) ⇒ `Object`

#data_encryption_key_id ⇒ `String` (readonly)

#description ⇒ `String` (readonly)

#encrypted ⇒ `Boolean` (readonly)

#id ⇒ `String` (readonly)

#kms_key_id ⇒ `String` (readonly)

#owner_alias ⇒ `String` (readonly)

#owner_id ⇒ `String` (readonly)

#progress ⇒ `String` (readonly)

#snapshot_id ⇒ `String` (readonly)

#start_time ⇒ `Time` (readonly)

#state ⇒ `String` (readonly)

#state_message ⇒ `String` (readonly)

#tags ⇒ `Array<Types::Tag>` (readonly)

#volume_id ⇒ `String` (readonly)

#volume_size ⇒ `Integer` (readonly)

#copy(options = {}) ⇒ `Types::CopySnapshotResult`

#create_tags(options = {}) ⇒ `Array<Tag>`

#delete(options = {}) ⇒ `Struct`

#delete_tags(options = {}) ⇒ `Array<Tag>`

#describe_attribute(options = {}) ⇒ `Types::DescribeSnapshotAttributeResult`

#modify_attribute(options = {}) ⇒ `Struct`

#reset_attribute(options = {}) ⇒ `Struct`

#volume ⇒ `Volume`^?

#wait_until_completed {|waiter| ... } ⇒ `Snapshot`