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 show all
Defined in:
(unknown)

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

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_idString (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 the DescribeSnapshots API operation.

Returns:

  • (String)

    The data encryption key identifier for the snapshot.

#descriptionString (readonly)

The description for the snapshot.

Returns:

  • (String)

    The description for the snapshot.

#encryptedBoolean (readonly)

Indicates whether the snapshot is encrypted.

Returns:

  • (Boolean)

    Indicates whether the snapshot is encrypted.

#idString (readonly)

Returns:

  • (String)

#kms_key_idString (readonly)

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 parent volume.

Returns:

  • (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 parent volume.

#owner_aliasString (readonly)

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.

Returns:

  • (String)

    Value from an Amazon-maintained list (amazon | aws-marketplace | microsoft) of snapshot owners.

#owner_idString (readonly)

The AWS account ID of the EBS snapshot owner.

Returns:

  • (String)

    The AWS account ID of the EBS snapshot owner.

#progressString (readonly)

The progress of the snapshot, as a percentage.

Returns:

  • (String)

    The progress of the snapshot, as a percentage.

#snapshot_idString (readonly)

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

Returns:

  • (String)

    The ID of the snapshot.

#start_timeTime (readonly)

The time stamp when the snapshot was initiated.

Returns:

  • (Time)

    The time stamp when the snapshot was initiated.

#stateString (readonly)

The snapshot state.

Possible values:

  • pending
  • completed
  • error

Returns:

  • (String)

    The snapshot state.

#state_messageString (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 the DescribeSnapshots API operation.

Returns:

  • (String)

    Encrypted Amazon EBS snapshots are copied asynchronously.

#tagsArray<Types::Tag> (readonly)

Any tags assigned to the snapshot.

Returns:

  • (Array<Types::Tag>)

    Any tags assigned to the snapshot.

#volume_idString (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_sizeInteger (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). The snapshot is copied to the regional endpoint that you send the HTTP request to.

Copies of encrypted EBS snapshots remain encrypted. Copies of unencrypted snapshots remain unencrypted, unless the Encrypted flag is specified during 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 non-default CMK with the KmsKeyId parameter.

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 the CopySnapshot action 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: "String",
  source_region: "String", # required
  dry_run: false,
})

Options Hash (options):

  • :description (String)

    A description for the EBS snapshot.

  • :encrypted (Boolean)

    Specifies whether the destination snapshot should be encrypted. You can encrypt a copy of an unencrypted snapshot using this flag, but you cannot use it to create an unencrypted copy from an encrypted snapshot. Your default CMK for EBS is used unless a non-default AWS Key Management Service (AWS KMS) CMK is specified with KmsKeyId. For more information, see Amazon EBS Encryption in the Amazon Elastic Compute Cloud User Guide.

  • :kms_key_id (String)

    The full ARN of the AWS Key Management Service (AWS KMS) CMK to use when creating the snapshot copy. This parameter is only required if you want to use a non-default CMK; if this parameter is not specified, the default CMK for EBS is used. The ARN contains the arn:aws:kms namespace, followed by the region of the CMK, the AWS account ID of the CMK owner, the key namespace, and then the CMK ID. For example, arn:aws:kms:us-east-1:012345678910:key/abcd1234-a123-456a-a12b-a123b4cd56ef. The specified CMK must exist in the region that the snapshot is being copied to. If a KmsKeyId is specified, the Encrypted flag must also be set.

  • :source_region (required, String)

    The ID of the region that contains the snapshot to be copied.

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

See Also:

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

    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:

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:

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

See Also:

#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 API call. If you need to both add and remove account IDs for a snapshot, you must use multiple API calls.

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 on 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: ["String"],
  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 may be modified at the customer level.

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

#reset_attribute(options = {}) ⇒ Struct

Resets permission settings for the specified snapshot.

For more information on 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:

#volumeVolume?

Returns:

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

Returns:

  • (Snapshot)

    Returns a copy of this Snapshot with loaded data.

Raises:

See Also: