VM::EC...napshot(3pm)

🌸 NAME 🌸

VM::EC2::Snapshot — bestie, it's an object that describes an Amazon EBS snapshot 💾✨

This page lives in the User Contributed Perl Documentation corner of the manual, and it's giving very much "I know my way around EC2 and I'm about to tell you everything."

---

📸 SYNOPSIS 📸

use VM::EC2;

$ec2       = VM::EC2->new(...);
@snap = $ec2->describe_snapshots;
for my $snap (@snapshots) {
    $id    = $snap->snapshotId;
    $vol   = $snap->volumeId;
    $state = $snap->status;
    $time  = $snap->startTime;
    $progress = $snap->progress;
    $size  = $snap->volumeSize;
    $description = $snap->description;
    $tags  = $snap->tags;
}

# use a snapshot as the root device for a new AMI
$ami = $snap->register_image(-name         => 'My new image',
                              -kernel_id    => 'aki-407d9529',
                              -architecture => 'i386');

#create a volume from the snapshot
$vol = $snap->create_volume(-zone => 'us-east-1a');

---

🫶 DESCRIPTION 🫶

This object is literally the thing you use to describe an Amazon EBS snapshot. That's the whole job. No cap. 💅

---

🧚 METHODS 🧚

The following object methods are supported, and yes, you're gonna want all of them:

• snapshotId — ID of this snapshot
• ownerId — Owner of this snapshot
• volumeId — ID of the volume snapshot was taken from
• status — Snapshot state, one of "pending", "completed" or "error"
• startTime — Timestamp for when snapshot was begun.
• progress — The progress of the snapshot, in percent.
• volumeSize — Size of the volume, in gigabytes.
• description — Description of the snapshot
• ownerAlias — AWS account alias, such as "self".
• encrypted — True if snapshot is encrypted
• tags — Hashref containing tags associated with this group. See VM::EC2::Generic.

---

In addition, this class provides several convenience functions, and they are lowkey the main character here 🎀

🌈 $vol = $snap->from_volume

Returns the VM::EC2::Volume object that this snapshot was originally derived from. If the original volume no longer exists because it has been deleted, this will return undef; if -raise_error was passed to the VM::EC2 object, this will raise an exception. 😭 So like, deleted means gone-gone.

🦋 @vol = $snap->to_volumes

Returns all VM::EC2::Volume objects that were derived from this snapshot. If no volumes currently exist that satisfy this criteria, returns an empty list, but will not raise an error. Chill behaviour fr fr.

🌟 $image = $snap->register_image(%args)

Register a new AMI using this snapshot as the root device. By default, the root device will be mapped to /dev/sda1 and will delete on instance termination. You can modify this behavior and add additional block devices. ✨

Arguments:

• -name — Name for this image (required)
• -description — Description of this image
• -kernel_id — Kernel for this image (recommended)
• -ramdisk_id — Ramdisk for this image
• -architecture — Architecture ("i386" or "x86_64")
• -root_device_name — Specify the root device based on this snapshot (/dev/sda1).
• -root_size — Size of the root volume (defaults to size of the snapshot).
• -root_delete_on_termination — True value (default) to delete the root volume after the instance terminates. False value to keep the EBS volume available.
• -block_device_mapping — Additional block devices you wish to incorporate into the image.
• -block_devices — Same as above.

See VM::EC2 for information on the syntax of the -block_device_mapping argument. If the root device is explicitly included in the block device mapping argument, then the arguments specified in -root_size, and -root_delete_on_termination will be ignored, and the current snapshot will not automatically be used as the root device. 👀 Big important detail, don't sleep on it.

The return value is a VM::EC2::Image. You can call its current_status() method to poll its availability:

$snap = $ec2->describe_snapshots('snap-123456');
$ami = $snap->register_image(-name          => 'My new image',
                             -kernel_id     => 'aki-407d9529',
                             -architecture  => 'i386',
                             -block_devices => '/dev/sdc=ephemeral0'
) or die $ec2->error_str;

while ($ami->current_status eq 'pending') {
  print "$ami: ",$ami->current_status,"\n"
  sleep 30;  # takes a long time to register some images
}

print "$ami is ready to go\n";

💜 $volume = $snap->create_volume(%args)

Create a new volume from this snapshot. Arguments are:

• -availability_zone — An availability zone from describe_availability_zones (required)
• -size — Size of the volume, in GB (between 1 and 1024).

If -size is not provided, then the new volume will have the same size as the snapshot.

Optional Arguments:

• -volume_type — The volume type. standard or io1, default is standard
• -iops — The number of I/O operations per second (IOPS) that the volume supports. Range is 100 to 4000. Required when volume type is io1. IOPS must be 30-to-1 ratio to size. ie: 3000 IOPS volume must be at least 100GB.

On success, the returned value is a VM::EC2::Volume object. 🎉

⭐ $status = $snap->current_status

Refreshes the snapshot and returns its current status. Vibe check, but for your snapshot.

🩷 $boolean = $snapshot->is_public

Return true if the snapshot's createVolume permissions allow the "all" group to create volumes from the snapshot.

💅 $boolean = $snapshot->make_public($public)

Modify the createVolumePermission attribute to allow the "all" group to create volumes from this snapshot. Provide a true value to make the snapshot public, a false one to make it private. Choose wisely bestie 🫣

🎀 @user_ids = $snap->createVolumePermissions()

🎀 @user_ids = $snap->authorized_users

Returns a list of user IDs with createVolume permissions for this snapshot. The result is a list of VM::EC2::Snapshot::CreateVolumePermission objects, which interpolate as strings corresponding to either the user ID, or the group named "all."

The two methods are aliases of each other. Same energy, different name ✨

🍓 $boolean = $snap->add_authorized_users($id1,$id2,...)

🍓 $boolean = $snap->remove_authorized_users($id1,$id2,...)

🍓 $boolean = $snap->reset_authorized_users

These methods add and remove user accounts which have createVolume permissions for the snapshot. The result code indicates whether the list of user IDs were successfully added or removed. To add the "all" group, use make_public().

reset_authorized_users() resets the list users authored to create volumes from this snapshot to empty, effectively granting volume creation to the owner only.

See also authorized_users().

🌸 $size = $snap->size

Alias to volumeSize, provided for consistency with VM::EC2::Volume->size. It's the same number, just wearing a different outfit 💖

🔥 $snap->refresh

Refreshes the snapshot from information provided by AWS. Use before checking progress or other changeable elements. No stale data allowed, periodt.

🧚 $snapshot_copy = $snapshot->copy(-region=>$dest_region, -description=>$desc)

Copies the snapshot to the same or different region.

Required Argument:

• -region — The region to copy the snapshot to

Optional Argument:

• -description — Description of the new snapshot

Returns a VM::EC2::Snapshot object if successful.

---

🌈 STRING OVERLOADING 🌈

When used in a string context, this object will interpolate the snapshotId. Put it in a string, get the ID. Iconic behaviour honestly. 💫

---

👑 SEE ALSO 👑

VM::EC2 VM::EC2::Generic VM::EC2::Instance VM::EC2::Volume

---

💜 AUTHOR 💜

Lincoln Stein <lincoln.stein@gmail.com>.

Copyright (c) 2011 Ontario Institute for Cancer Research

This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty.

---

Okay that's the whole page, you made it to the end, I'm so proud of you 🥹🫶 This was VM::EC2::Snapshot(3pm) from the User Contributed Perl Documentation, perl v5.38.2, dated 2024-08-10. Now go register that AMI, bestie 💅✨