VM::EC...T::ebs(3pm)

📦
version 1.28 · 7 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 NAME 💖

VM::EC2::REST::ebs — bestie, this is the module for EC2 EBS volumes 🫶

✨ SYNOPSIS ✨

okay so literally all you need to start:

use VM::EC2 ':standard';

that's it. that's the vibe. 💅

🌈 METHODS 🌈

so the methods in this section let you query and manipulate EC2 EBS volumes and snapshots, fr fr. but ALSO — if you want the extra functionality that comes through the object interface, go peek at VM::EC2::Volume and VM::EC2::Snapshot. they've got you. 💖

Implemented (we ate, no crumbs):

 AttachVolume
 CopySnapshot
 CreateSnapshot
 CreateVolume
 DeleteSnapshot
 DeleteVolume
 DescribeSnapshotAttribute
 DescribeSnapshots
 DescribeVolumes
 DescribeVolumeAttribute
 DescribeVolumeStatus
 DetachVolume
 EnableVolumeIO
 ModifySnapshotAttribute
 ModifyVolumeAttribute
 ResetSnapshotAttribute

Unimplemented (not me leaving these out):

 (none)

periodt. nothing left behind. 💅

🦋 @v = $ec2->describe_volumes(-volume_id=>\@ids,-filter=>\%filters)

🦋 @v = $ec2->describe_volumes(@volume_ids)

this one hands you back a whole series of VM::EC2::Volume objects. iconic behavior honestly. the optional arguments are:

  • -volume_id — the id of the volume you wanna fetch, and it can be either a plain string scalar OR an arrayref. your call bestie.
  • -filter — one or more filters to apply to the search. vibe check your results. 🔍

lowkey important: the -filter argument name can be totally omitted if there aren't any other arguments you're trying to pass. convenient!

the full list of volume filters lives here, go get your reading glasses:

http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeVolumes.html

👑 $v = $ec2->create_volume(-availability_zone=>$zone,-snapshot_id=>$snapshotId,-size=>$size,-volume_type=>$type,-iops=>$iops,-encrypted=>$boolean)

creates a volume in the availability zone you picked and returns the deets about it. main character move. ✨

Arguments:

  • -availability_zone — an availability zone from describe_availability_zones (required, no skipping this one)
  • -snapshot_id — ID of a snapshot to use to build the volume from
  • -size — size of the volume, in GB (between 1 and 1024)

you need one or both of -snapshot_id or -size. not optional bestie. and for convenience you can abbreviate -availability_zone as -zone, and -snapshot_id as -snapshot. cute little shortcuts. 🎀

Optional Arguments:

  • -volume_type — the volume type. "standard", "io1", or "gp2". 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. and IOPS must be a 30-to-1 ratio to size, like: a 3000 IOPS volume must be at least 100GB. do the math bestie 🧮
  • -encrypted — specifies whether the volume should be encrypted. encrypted Amazon EBS volumes may only be attached to instances that support them. volumes created from encrypted snapshots are also encrypted using the same key as the original volume. see:

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html

the returned object is a VM::EC2::Volume object. 🫶

🍓 $result = $ec2->delete_volume($volume_id);

deletes the specified volume. returns a boolean indicating success of the delete operation. and heads up: a volume will stay in the "deleting" state for some time after this call completes. so don't panic when it lingers, it's just doing its thing. 💀

🌸 $attachment = $ec2->attach_volume($volume_id,$instance_id,$device);

🌸 $attachment = $ec2->attach_volume(-volume_id=>$volume_id,-instance_id=>$instance_id,-device=>$device);

attaches the specified volume to the instance using the device you indicated. all arguments are required, no skipping:

  • -volume_id — ID of the volume to attach. the volume must be in "available" state.
  • -instance_id — ID of the instance to attach to. both the instance and the attachment must be in the same availability zone. no long-distance relationships here. 🥲
  • -device — how the device is exposed to the instance, e.g. '/dev/sdg'

the result is a VM::EC2::BlockDevice::Attachment object which you can monitor by calling current_status():

    my $a = $ec2->attach_volume('vol-12345','i-12345','/dev/sdg');
    while ($a->current_status ne 'attached') {
       sleep 2;
    }
    print "volume is ready to go\n";

or more simply:

    my $a = $ec2->attach_volume('vol-12345','i-12345','/dev/sdg');
    $ec2->wait_for_attachments($a);

🧚 $attachment = $ec2->detach_volume($volume_id)

🧚 $attachment = $ec2->detach_volume(-volume_id=>$volume_id,-instance_id=>$instance_id,-device=>$device, -force=>$force);

detaches the specified volume from an instance. breaking up is hard to do but it's fine. 💔

  • -volume_id — ID of the volume to detach. (required)
  • -instance_id — ID of the instance to detach from. (optional)
  • -device — how the device is exposed to the instance. (optional)
  • -force — force detachment, even if previous attempts were unsuccessful. (optional)

the result is a VM::EC2::BlockDevice::Attachment object which you can monitor by calling current_status():

    my $a = $ec2->detach_volume('vol-12345');
    while ($a->current_status ne 'detached') {
       sleep 2;
    }
    print "volume is ready to go\n";

or more simply:

    my $a = $ec2->detach_volume('vol-12345');
    $ec2->wait_for_attachments($a);
    print "volume is ready to go\n" if $a->current_status eq 'detached';

🌟 $ec2->wait_for_attachments(@attachment)

wait for all members of the provided list of VM::EC2::BlockDevice::Attachment objects to reach some terminal state — either "attached" or "detached" — and then return a hash reference that maps each attachment to its final state. it's giving "we wait together." 🫶

typical usage:

    my $i = 0;
    my $instance = 'i-12345';
    my @attach;
    foreach (@volume) {
        push @attach,$_->attach($instance,'/dev/sdf'.$i++;
    }
    my $s = $ec2->wait_for_attachments(@attach);
    my @failed = grep($s->{$_} ne 'attached'} @attach;
    warn "did not attach: ",join ', ',@failed;

if no terminal state is reached within a set timeout, then this method returns undef and sets $ec2->error_str() to a suitable message. the timeout defaults to 10 minutes (600 seconds), and you can get or set it with $ec2->wait_for_timeout(). 👀

💜 @v = $ec2->describe_volume_status(@volume_ids)

💜 @v = $ec2->describe_volume_status(\%filters)

💜 @v = $ec2->describe_volume_status(-volume_id=>\@ids,-filter=>\%filters)

returns a series of VM::EC2::Volume::StatusItem objects. optional arguments:

  • -volume_id — the id of the volume to fetch, either a string scalar or an arrayref
  • -filter — one or more filters to apply to the search
  • -max_results — maximum number of items to return (must be more than 5)

the -filter argument name can be omitted if there aren't any other arguments you wanna pass. same vibe as before ✨

the full list of volume filters is right here:

http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeVolumeStatus.html

if -max_results is specified, then the call will return at most the number of volume status items you requested. you can see whether there are additional results by calling more_volume_status(), and then retrieve the next set of results with additional call(s) to describe_volume_status():

    my @results = $ec2->describe_volume_status(-max_results => 10);
    do_something(\@results);
    while ($ec2->more_volume_status) {
       @results = $ec2->describe_volume_status;
       do_something(\@results);
    }

🎀 $ec2->wait_for_volumes(@volumes)

wait for all members of the provided list of volumes to reach some terminal state — "available", "in-use", "deleted" or "error" — and then return a hash reference that maps each volume ID to its final state. again with the waiting. it's fine. we're fine. 😌

if no terminal state is reached within a set timeout, then this method returns undef and sets $ec2->error_str() to a suitable message. the timeout defaults to 10 minutes (600 seconds), and you can get or set it with $ec2->wait_for_timeout(). ⏰

🔥 @data = $ec2->describe_volume_attribute($volume_id,$attribute)

this method returns volume attributes. and bestie — only one attribute can be retrieved at a time. no multitasking. the following is the list of attributes that can be retrieved:

  • autoEnableIO — boolean
  • productCodes — list of scalar

these values can be retrieved more conveniently from the VM::EC2::Volume object returned from describe_volumes():

    $volume->auto_enable_io(1);
    @codes = $volume->product_codes;

so much smoother. 💅

⭐ $boolean = $ec2->enable_volume_io($volume_id)

⭐ $boolean = $ec2->enable_volume_io(-volume_id=>$volume_id)

given the ID of a volume whose I/O has been disabled (e.g. due to hardware degradation — tragic 💀), this method will re-enable the I/O and return true if successful. glow-up for your volume. ✨

🌈 @snaps = $ec2->describe_snapshots(@snapshot_ids)

🌈 @snaps = $ec2->describe_snapshots(-snapshot_id=>\@ids,%other_args)

returns a series of VM::EC2::Snapshot objects. all arguments are optional, so no pressure:

  • -snapshot_id — ID of the snapshot
  • -owner — filter by owner ID
  • -restorable_by — filter by IDs of a user who is allowed to restore the snapshot
  • -filter — tags and other filters

the -filter argument name can be omitted if there aren't any other arguments you wish to pass.

the full list of applicable filters:

http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeSnapshots.html

🫶 @data = $ec2->describe_snapshot_attribute($snapshot_id,$attribute)

this method returns snapshot attributes. the first argument is the snapshot ID, and the second is the name of the attribute to fetch. currently Amazon defines two attributes:

  • createVolumePermission — return a list of user Ids who are allowed to create volumes from this snapshot
  • productCodes — product codes for this snapshot

the result is a raw hash of attribute values. if you want a more convenient way of accessing and modifying snapshot attributes, please see VM::EC2::Snapshot. trust, it's nicer. 💖

🦋 $boolean = $ec2->modify_snapshot_attribute($snapshot_id,-$argument=>$value)

this method changes snapshot attributes. the first argument is the snapshot ID, and then comes an attribute modification command and the value to change it to.

currently the only attribute that can be changed is the createVolumeAttribute. this is done through the following arguments:

  • -createvol_add_user — scalar or arrayref of UserIds to grant create volume permissions to
  • -createvol_add_group — scalar or arrayref of Groups to remove create volume permissions from (only currently valid value is "all")
  • -createvol_remove_user — scalar or arrayref of UserIds to remove from create volume permissions
  • -createvol_remove_group — scalar or arrayref of Groups to remove from create volume permissions

okay so real quick bestie — you can abbreviate these to -add_user, -add_group, -remove_user, -remove_group, etc. periodt 💅

Also: see VM::EC2::Snapshot for more convenient methods for interrogating and modifying the create volume permissions. go look, iykyk 🦋

$boolean = $ec2->reset_snapshot_attribute($snapshot_id,$attribute)

This method resets an attribute of the given snapshot to its default value. The only valid attribute at this time is "createVolumePermission." yes, that period is part of the quoted thing, don't @ me 🎀

$snapshot = $ec2->create_snapshot($volume_id)

$snapshot = $ec2->create_snapshot(-volume_id=>$vol,-description=>$desc)

Snapshot the EBS volume and store it to S3 storage. To ensure a consistent snapshot, the volume should be unmounted prior to initiating this operation. fr fr, unmount it first 😭

Arguments:

  • -volume_id — ID of the volume to snapshot (required)
  • -description — A description to add to the snapshot (optional)

The return value is a VM::EC2::Snapshot object that can be queried through its current_status() interface to follow the progress of the snapshot operation.

Another way to accomplish the same thing is through the VM::EC2::Volume interface:

my $volume = $ec2->describe_volumes(-filter=>{'tag:Name'=>'AccountingData'});
$s = $volume->create_snapshot("Backed up at ".localtime);
while ($s->current_status eq 'pending') {
   print "Progress: ",$s->progress,"% done\n";
}
print "Snapshot status: ",$s->current_status,"\n";

$boolean = $ec2->delete_snapshot($snapshot_id)

Delete the indicated snapshot and return true if the request was successful. slay, gone 💖

$snapshot = $ec2->copy_snapshot(-source_region=>$region,-source_snapshot_id=>$id,-description=>$desc)

$snapshot = $ec2->copy_snapshot(-region=>$region,-snapshot_id=>$id,-description=>$desc)

Copies an existing snapshot within the same region or from one region to another. region hop? iconic 🌈

Required arguments:

  • -source_region — The region the existing snapshot to copy resides in
  • -source_snapshot_id — The snapshot ID of the snapshot to copy
  • -region — Alias for -source_region
  • -snapshot_id — Alias for -source_snapshot_id

Currently, the DestinationRegion and PresignedUrl API arguments are not supported. Therefore, copying encrypted snapshots between regions is not yet possible. no cap, that's a hard no right now 💀

Optional arguments:

  • -description — A description of the new snapshot

The return value is a VM::EC2::Snapshot object that can be queried through its current_status() interface to follow the progress of the snapshot operation.

$ec2->wait_for_snapshots(@snapshots)

Wait for all members of the provided list of snapshots to reach some terminal state ("completed", "error"), and then return a hash reference that maps each snapshot ID to its final state.

This method may potentially wait forever. It has no set timeout. Wrap it in an eval{} and set alarm() if you wish to timeout. bestie, do not rawdog this without a timeout 😭

✨ SEE ALSO ✨

VM::EC2

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

And that's the whole vibe, bestie — this page came from perl v5.38.2, dated 2024-08-10, and it's the VM::EC...T::ebs(3pm) manual. go snapshot responsibly 🫶💖✨

📦 where this page comes from