plucky (3) VM::EC2::Snapshot.3pm.gz

Provided by: libvm-ec2-perl_1.28-5_all bug

NAME

       VM::EC2::Snapshot - Object describing an Amazon EBS snapshot

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 used to describe an Amazon EBS snapshot.

METHODS

       The following object methods are supported:

        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 L<VM::EC2::Generic>.

       In addition, this class provides several convenience functions:

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

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

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

       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.

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

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

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

   $snap->refresh
       Refreshes the snapshot from information provided by AWS. Use before checking progress or other changeable
       elements.

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

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.