1VM::EC2::REST::ebs(3) User Contributed Perl DocumentationVM::EC2::REST::ebs(3)
2
3
4
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
16 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
34 Unimplemented:
35 (none)
36
37 @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
41 -volume_id The id of the volume to fetch, either a string
42 scalar or an arrayref.
43
44 -filter One or more filters to apply to the search
45
46 The -filter argument name can be omitted if there are no other
47 arguments you wish to pass.
48
49 The full list of volume filters can be found at:
50 http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeVolumes.html
51
52 $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
57 Arguments:
58
59 -availability_zone -- An availability zone from
60 describe_availability_zones (required)
61
62 -snapshot_id -- ID of a snapshot to use to build volume from.
63
64 -size -- Size of the volume, in GB (between 1 and 1024).
65
66 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
70 Optional Arguments:
71
72 -volume_type -- The volume type. "standard", "io1", or "gp2"
73 Default is "standard"
74
75 -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
80 -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
87 The returned object is a VM::EC2::Volume object.
88
89 $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
94 $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
100 -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
107 The result is a VM::EC2::BlockDevice::Attachment object which you can
108 monitor by calling current_status():
109
110 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
116 or more simply
117
118 my $a = $ec2->attach_volume('vol-12345','i-12345','/dev/sdg');
119 $ec2->wait_for_attachments($a);
120
121 $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
127 -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
133 The result is a VM::EC2::BlockDevice::Attachment object which you can
134 monitor by calling current_status():
135
136 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
142 Or more simply:
143
144 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
148 $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
154 Typical usage:
155
156 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
166 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
171 @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
177 -volume_id The id of the volume to fetch, either a string
178 scalar or an arrayref.
179
180 -filter One or more filters to apply to the search
181
182 -max_results Maximum number of items to return (must be more than
183 5).
184
185 The -filter argument name can be omitted if there are no other
186 arguments you wish to pass.
187
188 The full list of volume filters can be found at:
189 http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeVolumeStatus.html
190
191 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
197 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
204 $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
209 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
214 @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
219 autoEnableIO -- boolean
220 productCodes -- list of scalar
221
222 These values can be retrieved more conveniently from the
223 VM::EC2::Volume object returned from describe_volumes():
224
225 $volume->auto_enable_io(1);
226 @codes = $volume->product_codes;
227
228 $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
234 @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
239 -snapshot_id ID of the snapshot
240
241 -owner Filter by owner ID
242
243 -restorable_by Filter by IDs of a user who is allowed to restore
244 the snapshot
245
246 -filter Tags and other filters
247
248 The -filter argument name can be omitted if there are no other
249 arguments you wish to pass.
250
251 The full list of applicable filters can be found at
252 http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeSnapshots.html
253
254 @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
259 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
263 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
267 $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
272 Currently the only attribute that can be changed is the
273 createVolumeAttribute. This is done through the following arguments
274
275 -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
281 You can abbreviate these to -add_user, -add_group, -remove_user,
282 -remove_group, etc.
283
284 See VM::EC2::Snapshot for more convenient methods for interrogating and
285 modifying the create volume permissions.
286
287 $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
292 $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
298 Arguments:
299
300 -volume_id -- ID of the volume to snapshot (required)
301
302 -description -- A description to add to the snapshot (optional)
303
304 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
308 Another way to accomplish the same thing is through the VM::EC2::Volume
309 interface:
310
311 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
318 $boolean = $ec2->delete_snapshot($snapshot_id)
319 Delete the indicated snapshot and return true if the request was
320 successful.
321
322 $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
329 Required arguments:
330
331 -source_region -- The region the existing snapshot to copy resides in
332 -source_snapshot_id -- The snapshot ID of the snapshot to copy
333
334 -region -- Alias for -source_region
335 -snapshot_id -- Alias for -source_snapshot_id
336
337 Currently, the DestinationRegion and PresignedUrl API arguments are not
338 supported. Therefore, copying encrypted snapshots between regions is
339 not yet possible.
340
341 Optional arguments:
342
343 -description -- A description of the new snapshot
344
345 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
349 $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
354 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
363 Copyright (c) 2011 Ontario Institute for Cancer Research
364
365 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.
370
371
372
373perl v5.34.0 2021-07-27 VM::EC2::REST::ebs(3)