1VM::EC2::Snapshot(3pm)User Contributed Perl DocumentationVM::EC2::Snapshot(3pm)
2
6 VM::EC2::Snapshot - Object describing an Amazon EBS snapshot
7
9 use VM::EC2;
10 $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 # 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 #create a volume from the snapshot
30 $vol = $snap->create_volume(-zone => 'us-east-1a');
31
33 This object is used to describe an Amazon EBS snapshot.
34
36 The following object methods are supported:
37 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 In addition, this class provides several convenience functions:
52 $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 @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 $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 Arguments:
71 -name Name for this image (required)
73 -description Description of this image
75 -kernel_id Kernel for this image (recommended)
77 -ramdisk_id Ramdisk for this image
79 -architecture Architecture ("i386" or "x86_64")
81 -root_device_name Specify the root device based
83 on this snapshot (/dev/sda1).
84 -root_size Size of the root volume (defaults
86 to size of the snapshot).
87 -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 -block_device_mapping Additional block devices you wish to
94 incorporate into the image.
95 -block_devices Same as above.
97 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 The return value is a VM::EC2::Image. You can call its current_status()
105 method to poll its availability:
106 $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 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 print "$ami is ready to go\n";
120 $volume = $snap->create_volume(%args)
122 Create a new volume from this snapshot. Arguments are:
123 -availability_zone -- An availability zone from
125 describe_availability_zones (required)
126 -size -- Size of the volume, in GB (between 1 and 1024).
128 If -size is not provided, then the new volume will have the same size
130 as the snapshot.
131 Optional Arguments:
133 -volume_type -- The volume type. standard or io1, default is
135 standard
136 -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 On success, the returned value is a VM::EC2::Volume object.
143 $status = $snap->current_status
145 Refreshes the snapshot and returns its current status.
146 $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 $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 @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 The two methods are aliases of each other.
164 $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 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 See also authorized_users().
178 $size = $snap->size
180 Alias to volumeSize, provided for consistency with
181 VM::EC2::Volume->size.
182 $snap->refresh
184 Refreshes the snapshot from information provided by AWS. Use before
185 checking progress or other changeable elements.
186 $snapshot_copy = $snapshot->copy(-region=>$dest_region,
188 -description=>$desc)
189 Copies the snapshot to the same or different region.
190 Required Argument:
192 -region The region to copy the snapshot to
193 Optional Argument:
195 -description Description of the new snapshot
196 Returns a VM::EC2::Snapshot object if successful.
198
200 When used in a string context, this object will interpolate the
201 snapshotId.
202
204 VM::EC2 VM::EC2::Generic VM::EC2::Instance VM::EC2::Volume
205
207 Lincoln Stein <lincoln.stein@gmail.com>.
208 Copyright (c) 2011 Ontario Institute for Cancer Research
210 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.
216perl v5.38.0 2023-07-21 VM::EC2::Snapshot(3pm)