1VM::EC2::Snapshot(3pm)User Contributed Perl DocumentationVM::EC2::Snapshot(3pm)
2
3
4

NAME

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

SYNOPSIS

9         use VM::EC2;
10
11         $ec2       = VM::EC2->new(...);
12         @snap = $ec2->describe_snapshots;
13         for my $snap (@snapshots) {
14             $id    = $snap->snapshotId;
15             $vol   = $snap->volumeId;
16             $state = $snap->status;
17             $time  = $snap->startTime;
18             $progress = $snap->progress;
19             $size  = $snap->volumeSize;
20             $description = $snap->description;
21             $tags  = $snap->tags;
22         }
23
24        # use a snapshot as the root device for a new AMI
25        $ami = $snap->register_image(-name         => 'My new image',
26                                      -kernel_id    => 'aki-407d9529',
27                                      -architecture => 'i386');
28
29        #create a volume from the snapshot
30        $vol = $snap->create_volume(-zone => 'us-east-1a');
31

DESCRIPTION

33       This object is used to describe an Amazon EBS snapshot.
34

METHODS

36       The following object methods are supported:
37
38        snapshotId       -- ID of this snapshot
39        ownerId          -- Owner of this snapshot
40        volumeId         -- ID of the volume snapshot was taken from
41        status           -- Snapshot state, one of "pending", "completed" or "error"
42        startTime        -- Timestamp for when snapshot was begun.
43        progress         -- The progress of the snapshot, in percent.
44        volumeSize       -- Size of the volume, in gigabytes.
45        description      -- Description of the snapshot
46        ownerAlias       -- AWS account alias, such as "self".
47        encrypted        -- True if snapshot is encrypted
48        tags             -- Hashref containing tags associated with this group.
49                            See L<VM::EC2::Generic>.
50
51       In addition, this class provides several convenience functions:
52
53   $vol = $snap->from_volume
54       Returns the VM::EC2::Volume object that this snapshot was originally
55       derived from. If the original volume no longer exists because it has
56       been deleted, this will return undef; if -raise_error was passed to the
57       VM::EC2 object, this will raise an exception.
58
59   @vol = $snap->to_volumes
60       Returns all VM::EC2::Volume objects that were derived from this
61       snapshot. If no volumes currently exist that satisfy this criteria,
62       returns an empty list, but will not raise an error.
63
64   $image = $snap->register_image(%args)
65       Register a new AMI using this snapshot as the root device. By default,
66       the root device will be mapped to /dev/sda1 and will delete on instance
67       termination. You can modify this behavior and add additional block
68       devices.
69
70       Arguments:
71
72        -name                 Name for this image (required)
73
74        -description          Description of this image
75
76        -kernel_id            Kernel for this image (recommended)
77
78        -ramdisk_id           Ramdisk for this image
79
80        -architecture         Architecture ("i386" or "x86_64")
81
82        -root_device_name     Specify the root device based
83                              on this snapshot (/dev/sda1).
84
85        -root_size            Size of the root volume (defaults
86                              to size of the snapshot).
87
88        -root_delete_on_termination   True value (default) to delete
89                              the root volume after the instance
90                              terminates. False value to keep the
91                              EBS volume available.
92
93        -block_device_mapping Additional block devices you wish to
94                              incorporate into the image.
95
96        -block_devices        Same as above.
97
98       See VM::EC2 for information on the syntax of the -block_device_mapping
99       argument. If the root device is explicitly included in the block device
100       mapping argument, then the arguments specified in -root_size, and
101       -root_delete_on_termination will be ignored, and the current snapshot
102       will not automatically be used as the root device.
103
104       The return value is a VM::EC2::Image. You can call its current_status()
105       method to poll its availability:
106
107         $snap = $ec2->describe_snapshots('snap-123456');
108         $ami = $snap->register_image(-name          => 'My new image',
109                                      -kernel_id     => 'aki-407d9529',
110                                      -architecture  => 'i386',
111                                      -block_devices => '/dev/sdc=ephemeral0'
112         ) or die $ec2->error_str;
113
114         while ($ami->current_status eq 'pending') {
115           print "$ami: ",$ami->current_status,"\n"
116           sleep 30;  # takes a long time to register some images
117         }
118
119         print "$ami is ready to go\n";
120
121   $volume = $snap->create_volume(%args)
122       Create a new volume from this snapshot. Arguments are:
123
124        -availability_zone    -- An availability zone from
125                                 describe_availability_zones (required)
126
127        -size                 -- Size of the volume, in GB (between 1 and 1024).
128
129       If -size is not provided, then the new volume will have the same size
130       as the snapshot.
131
132       Optional Arguments:
133
134        -volume_type          -- The volume type.  standard or io1, default is
135                                 standard
136
137        -iops                 -- The number of I/O operations per second (IOPS) that
138                                 the volume supports.  Range is 100 to 4000.  Required
139                                 when volume type is io1.  IOPS must be 30-to-1 ratio
140                                 to size.  ie: 3000 IOPS volume must be at least 100GB.
141
142       On success, the returned value is a VM::EC2::Volume object.
143
144   $status = $snap->current_status
145       Refreshes the snapshot and returns its current status.
146
147   $boolean = $snapshot->is_public
148       Return true if the snapshot's createVolume permissions allow the "all"
149       group to create volumes from the snapshot.
150
151   $boolean = $snapshot->make_public($public)
152       Modify the createVolumePermission attribute to allow the "all" group to
153       create volumes from this snapshot. Provide a true value to make the
154       snapshot public, a false one to make it private.
155
156   @user_ids = $snap->createVolumePermissions()
157   @user_ids = $snap->authorized_users
158       Returns a list of user IDs with createVolume permissions for this
159       snapshot. The result is a list of
160       VM::EC2::Snapshot::CreateVolumePermission objects, which interpolate as
161       strings corresponding to either the user ID, or the group named "all."
162
163       The two methods are aliases of each other.
164
165   $boolean = $snap->add_authorized_users($id1,$id2,...)
166   $boolean = $snap->remove_authorized_users($id1,$id2,...)
167   $boolean = $snap->reset_authorized_users
168       These methods add and remove user accounts which have createVolume
169       permissions for the snapshot. The result code indicates whether the
170       list of user IDs were successfully added or removed. To add the "all"
171       group, use make_public().
172
173       reset_authorized_users() resets the list users authored to create
174       volumes from this snapshot to empty, effectively granting volume
175       creation to the owner only.
176
177       See also authorized_users().
178
179   $size = $snap->size
180       Alias to volumeSize, provided for consistency with
181       VM::EC2::Volume->size.
182
183   $snap->refresh
184       Refreshes the snapshot from information provided by AWS. Use before
185       checking progress or other changeable elements.
186
187   $snapshot_copy = $snapshot->copy(-region=>$dest_region,
188       -description=>$desc)
189       Copies the snapshot to the same or different region.
190
191       Required Argument:
192        -region        The region to copy the snapshot to
193
194       Optional Argument:
195        -description   Description of the new snapshot
196
197       Returns a VM::EC2::Snapshot object if successful.
198

STRING OVERLOADING

200       When used in a string context, this object will interpolate the
201       snapshotId.
202

SEE ALSO

204       VM::EC2 VM::EC2::Generic VM::EC2::Instance VM::EC2::Volume
205

AUTHOR

207       Lincoln Stein <lincoln.stein@gmail.com>.
208
209       Copyright (c) 2011 Ontario Institute for Cancer Research
210
211       This package and its accompanying libraries is free software; you can
212       redistribute it and/or modify it under the terms of the GPL (either
213       version 1, or at your option, any later version) or the Artistic
214       License 2.0.  Refer to LICENSE for the full license text. In addition,
215       please see DISCLAIMER.txt for disclaimers of warranty.
216
217
218
219perl v5.38.0                      2023-07-21            VM::EC2::Snapshot(3pm)
Impressum