1VM::EC2::REST::ebs(3pm)User Contributed Perl DocumentatioVnM::EC2::REST::ebs(3pm)
2
3
4

NAME

6       VM::EC2::REST::ebs - Modules for EC2 EBS volumes
7

SYNOPSIS

9        use VM::EC2 ':standard';
10

METHODS

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

SEE ALSO

358       VM::EC2
359

AUTHOR

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.38.0                      2023-07-21           VM::EC2::REST::ebs(3pm)
Impressum