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 DescribeSnapshots.

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 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_aliasString (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_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 DescribeSnapshots.

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

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:

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

    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:

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:

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

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

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

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