1VM::EC2::REST::ebs(3pm)User Contributed Perl DocumentatioVnM::EC2::REST::ebs(3pm)
2
6 VM::EC2::REST::ebs - Modules for EC2 EBS volumes
7
9 use VM::EC2 ':standard';
10
12 The methods in this section allow you to query and manipulate EC2 EBS
13 volumes and snapshots. See VM::EC2::Volume and VM::EC2::Snapshot for
14 additional functionality provided through the object interface.
15 Implemented:
17 AttachVolume
18 CopySnapshot
19 CreateSnapshot
20 CreateVolume
21 DeleteSnapshot
22 DeleteVolume
23 DescribeSnapshotAttribute
24 DescribeSnapshots
25 DescribeVolumes
26 DescribeVolumeAttribute
27 DescribeVolumeStatus
28 DetachVolume
29 EnableVolumeIO
30 ModifySnapshotAttribute
31 ModifyVolumeAttribute
32 ResetSnapshotAttribute
33 Unimplemented:
35 (none)
36 @v = $ec2->describe_volumes(-volume_id=>\@ids,-filter=>\%filters)
38 @v = $ec2->describe_volumes(@volume_ids)
39 Return a series of VM::EC2::Volume objects. Optional arguments:
40 -volume_id The id of the volume to fetch, either a string
42 scalar or an arrayref.
43 -filter One or more filters to apply to the search
45 The -filter argument name can be omitted if there are no other
47 arguments you wish to pass.
48 The full list of volume filters can be found at:
50 http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeVolumes.html
51 $v =
53 $ec2->create_volume(-availability_zone=>$zone,-snapshot_id=>$snapshotId,-size=>$size,-volume_type=>$type,-iops=>$iops,-encrypted=>$boolean)
54 Create a volume in the specified availability zone and return
55 information about it.
56 Arguments:
58 -availability_zone -- An availability zone from
60 describe_availability_zones (required)
61 -snapshot_id -- ID of a snapshot to use to build volume from.
63 -size -- Size of the volume, in GB (between 1 and 1024).
65 One or both of -snapshot_id or -size are required. For convenience, you
67 may abbreviate -availability_zone as -zone, and -snapshot_id as
68 -snapshot.
69 Optional Arguments:
71 -volume_type -- The volume type. "standard", "io1", or "gp2"
73 Default is "standard"
74 -iops -- The number of I/O operations per second (IOPS) that
76 the volume supports. Range is 100 to 4000. Required
77 when volume type is io1. IOPS must be 30-to-1 ratio
78 to size. ie: 3000 IOPS volume must be at least 100GB.
79 -encrypted -- Specifies whether the volume should be encrypted.
81 Encrypted Amazon EBS volumes may only be attached to
82 instances that support them. Volumes created from
83 encrypted snapshots are also encrypted using the same
84 key as the original volume.
85 See: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html
86 The returned object is a VM::EC2::Volume object.
88 $result = $ec2->delete_volume($volume_id);
90 Deletes the specified volume. Returns a boolean indicating success of
91 the delete operation. Note that a volume will remain in the "deleting"
92 state for some time after this call completes.
93 $attachment = $ec2->attach_volume($volume_id,$instance_id,$device);
95 $attachment =
96 $ec2->attach_volume(-volume_id=>$volume_id,-instance_id=>$instance_id,-device=>$device);
97 Attaches the specified volume to the instance using the indicated
98 device. All arguments are required:
99 -volume_id -- ID of the volume to attach. The volume must be in
101 "available" state.
102 -instance_id -- ID of the instance to attach to. Both instance and
103 attachment must be in the same availability zone.
104 -device -- How the device is exposed to the instance, e.g.
105 '/dev/sdg'.
106 The result is a VM::EC2::BlockDevice::Attachment object which you can
108 monitor by calling current_status():
109 my $a = $ec2->attach_volume('vol-12345','i-12345','/dev/sdg');
111 while ($a->current_status ne 'attached') {
112 sleep 2;
113 }
114 print "volume is ready to go\n";
115 or more simply
117 my $a = $ec2->attach_volume('vol-12345','i-12345','/dev/sdg');
119 $ec2->wait_for_attachments($a);
120 $attachment = $ec2->detach_volume($volume_id)
122 $attachment =
123 $ec2->detach_volume(-volume_id=>$volume_id,-instance_id=>$instance_id,
124 -device=>$device, -force=>$force);
125 Detaches the specified volume from an instance.
126 -volume_id -- ID of the volume to detach. (required)
128 -instance_id -- ID of the instance to detach from. (optional)
129 -device -- How the device is exposed to the instance. (optional)
130 -force -- Force detachment, even if previous attempts were
131 unsuccessful. (optional)
132 The result is a VM::EC2::BlockDevice::Attachment object which you can
134 monitor by calling current_status():
135 my $a = $ec2->detach_volume('vol-12345');
137 while ($a->current_status ne 'detached') {
138 sleep 2;
139 }
140 print "volume is ready to go\n";
141 Or more simply:
143 my $a = $ec2->detach_volume('vol-12345');
145 $ec2->wait_for_attachments($a);
146 print "volume is ready to go\n" if $a->current_status eq 'detached';
147 $ec2->wait_for_attachments(@attachment)
149 Wait for all members of the provided list of
150 VM::EC2::BlockDevice::Attachment objects to reach some terminal state
151 ("attached" or "detached"), and then return a hash reference that maps
152 each attachment to its final state.
153 Typical usage:
155 my $i = 0;
157 my $instance = 'i-12345';
158 my @attach;
159 foreach (@volume) {
160 push @attach,$_->attach($instance,'/dev/sdf'.$i++;
161 }
162 my $s = $ec2->wait_for_attachments(@attach);
163 my @failed = grep($s->{$_} ne 'attached'} @attach;
164 warn "did not attach: ",join ', ',@failed;
165 If no terminal state is reached within a set timeout, then this method
167 returns undef and sets $ec2->error_str() to a suitable message. The
168 timeout, which defaults to 10 minutes (600 seconds), can be get or set
169 with $ec2->wait_for_timeout().
170 @v = $ec2->describe_volume_status(@volume_ids)
172 @v = $ec2->describe_volume_status(\%filters)
173 @v = $ec2->describe_volume_status(-volume_id=>\@ids,-filter=>\%filters)
174 Return a series of VM::EC2::Volume::StatusItem objects. Optional
175 arguments:
176 -volume_id The id of the volume to fetch, either a string
178 scalar or an arrayref.
179 -filter One or more filters to apply to the search
181 -max_results Maximum number of items to return (must be more than
183 5).
184 The -filter argument name can be omitted if there are no other
186 arguments you wish to pass.
187 The full list of volume filters can be found at:
189 http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeVolumeStatus.html
190 If -max_results is specified, then the call will return at most the
192 number of volume status items you requested. You may see whether there
193 are additional results by calling more_volume_status(), and then
194 retrieve the next set of results with additional call(s) to
195 describe_volume_status():
196 my @results = $ec2->describe_volume_status(-max_results => 10);
198 do_something(\@results);
199 while ($ec2->more_volume_status) {
200 @results = $ec2->describe_volume_status;
201 do_something(\@results);
202 }
203 $ec2->wait_for_volumes(@volumes)
205 Wait for all members of the provided list of volumes to reach some
206 terminal state ("available", "in-use", "deleted" or "error"), and then
207 return a hash reference that maps each volume ID to its final state.
208 If no terminal state is reached within a set timeout, then this method
210 returns undef and sets $ec2->error_str() to a suitable message. The
211 timeout, which defaults to 10 minutes (600 seconds), can be get or set
212 with $ec2->wait_for_timeout().
213 @data = $ec2->describe_volume_attribute($volume_id,$attribute)
215 This method returns volume attributes. Only one attribute can be
216 retrieved at a time. The following is the list of attributes that can
217 be retrieved:
218 autoEnableIO -- boolean
220 productCodes -- list of scalar
221 These values can be retrieved more conveniently from the
223 VM::EC2::Volume object returned from describe_volumes():
224 $volume->auto_enable_io(1);
226 @codes = $volume->product_codes;
227 $boolean = $ec2->enable_volume_io($volume_id)
229 $boolean = $ec2->enable_volume_io(-volume_id=>$volume_id)
230 Given the ID of a volume whose I/O has been disabled (e.g. due to
231 hardware degradation), this method will reenable the I/O and return
232 true if successful.
233 @snaps = $ec2->describe_snapshots(@snapshot_ids)
235 @snaps = $ec2->describe_snapshots(-snapshot_id=>\@ids,%other_args)
236 Returns a series of VM::EC2::Snapshot objects. All arguments are
237 optional:
238 -snapshot_id ID of the snapshot
240 -owner Filter by owner ID
242 -restorable_by Filter by IDs of a user who is allowed to restore
244 the snapshot
245 -filter Tags and other filters
247 The -filter argument name can be omitted if there are no other
249 arguments you wish to pass.
250 The full list of applicable filters can be found at
252 http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeSnapshots.html
253 @data = $ec2->describe_snapshot_attribute($snapshot_id,$attribute)
255 This method returns snapshot attributes. The first argument is the
256 snapshot ID, and the second is the name of the attribute to fetch.
257 Currently Amazon defines two attributes:
258 createVolumePermission -- return a list of user Ids who are
260 allowed to create volumes from this snapshot.
261 productCodes -- product codes for this snapshot
262 The result is a raw hash of attribute values. Please see
264 VM::EC2::Snapshot for a more convenient way of accessing and modifying
265 snapshot attributes.
266 $boolean = $ec2->modify_snapshot_attribute($snapshot_id,-$argument=>$value)
268 This method changes snapshot attributes. The first argument is the
269 snapshot ID, and this is followed by an attribute modification command
270 and the value to change it to.
271 Currently the only attribute that can be changed is the
273 createVolumeAttribute. This is done through the following arguments
274 -createvol_add_user -- scalar or arrayref of UserIds to grant create volume permissions to
276 -createvol_add_group -- scalar or arrayref of Groups to remove create volume permissions from
277 (only currently valid value is "all")
278 -createvol_remove_user -- scalar or arrayref of UserIds to remove from create volume permissions
279 -createvol_remove_group -- scalar or arrayref of Groups to remove from create volume permissions
280 You can abbreviate these to -add_user, -add_group, -remove_user,
282 -remove_group, etc.
283 See VM::EC2::Snapshot for more convenient methods for interrogating and
285 modifying the create volume permissions.
286 $boolean = $ec2->reset_snapshot_attribute($snapshot_id,$attribute)
288 This method resets an attribute of the given snapshot to its default
289 value. The only valid attribute at this time is
290 "createVolumePermission."
291 $snapshot = $ec2->create_snapshot($volume_id)
293 $snapshot = $ec2->create_snapshot(-volume_id=>$vol,-description=>$desc)
294 Snapshot the EBS volume and store it to S3 storage. To ensure a
295 consistent snapshot, the volume should be unmounted prior to initiating
296 this operation.
297 Arguments:
299 -volume_id -- ID of the volume to snapshot (required)
301 -description -- A description to add to the snapshot (optional)
303 The return value is a VM::EC2::Snapshot object that can be queried
305 through its current_status() interface to follow the progress of the
306 snapshot operation.
307 Another way to accomplish the same thing is through the VM::EC2::Volume
309 interface:
310 my $volume = $ec2->describe_volumes(-filter=>{'tag:Name'=>'AccountingData'});
312 $s = $volume->create_snapshot("Backed up at ".localtime);
313 while ($s->current_status eq 'pending') {
314 print "Progress: ",$s->progress,"% done\n";
315 }
316 print "Snapshot status: ",$s->current_status,"\n";
317 $boolean = $ec2->delete_snapshot($snapshot_id)
319 Delete the indicated snapshot and return true if the request was
320 successful.
321 $snapshot =
323 $ec2->copy_snapshot(-source_region=>$region,-source_snapshot_id=>$id,-description=>$desc)
324 $snapshot =
325 $ec2->copy_snapshot(-region=>$region,-snapshot_id=>$id,-description=>$desc)
326 Copies an existing snapshot within the same region or from one region
327 to another.
328 Required arguments:
330 -source_region -- The region the existing snapshot to copy resides in
332 -source_snapshot_id -- The snapshot ID of the snapshot to copy
333 -region -- Alias for -source_region
335 -snapshot_id -- Alias for -source_snapshot_id
336 Currently, the DestinationRegion and PresignedUrl API arguments are not
338 supported. Therefore, copying encrypted snapshots between regions is
339 not yet possible.
340 Optional arguments:
342 -description -- A description of the new snapshot
344 The return value is a VM::EC2::Snapshot object that can be queried
346 through its current_status() interface to follow the progress of the
347 snapshot operation.
348 $ec2->wait_for_snapshots(@snapshots)
350 Wait for all members of the provided list of snapshots to reach some
351 terminal state ("completed", "error"), and then return a hash reference
352 that maps each snapshot ID to its final state.
353 This method may potentially wait forever. It has no set timeout. Wrap
355 it in an eval{} and set alarm() if you wish to timeout.
356
358 VM::EC2
359
361 Lincoln Stein <lincoln.stein@gmail.com>.
362 Copyright (c) 2011 Ontario Institute for Cancer Research
364 This package and its accompanying libraries is free software; you can
366 redistribute it and/or modify it under the terms of the GPL (either
367 version 1, or at your option, any later version) or the Artistic
368 License 2.0. Refer to LICENSE for the full license text. In addition,
369 please see DISCLAIMER.txt for disclaimers of warranty.
370perl v5.38.0 2023-07-21 VM::EC2::REST::ebs(3pm)