1VM::EC2::Image(3)     User Contributed Perl Documentation    VM::EC2::Image(3)
2
3
4

NAME

6       VM::EC2::Image - Object describing an Amazon Machine Image (AMI)
7

SYNOPSIS

9         use VM::EC2;
10
11         $ec2     = VM::EC2->new(...);
12         $image   = $ec2->describe_images(-image_id=>'ami-12345');
13
14         $state   = $image->imageState;
15         $owner   = $image->imageOwnerId;
16         $rootdev = $image->rootDeviceName;
17         @devices = $image->blockDeviceMapping;
18         $tags    = $image->tags;
19
20         @instances = $image->run_instances(-min_count=>10);
21

DESCRIPTION

23       This object represents an Amazon Machine Image (AMI), and is returned
24       by VM::EC2->describe_images(). In addition to methods to query the
25       image's attributes, the run_instances() method allows you to launch and
26       configure EC2 instances based on the AMI.
27

METHODS

29       These object methods are supported:
30
31        imageId       -- AMI ID
32        imageLocation -- Location of the AMI
33        imageState    -- Current state of the AMI. One of "available",
34                         "pending" or "failed". Only "available" AMIs
35                         can be launched.
36        imageOwnerId  -- AWS account ID of the image owner.
37        isPublic      -- Returns true if this image has public launch
38                         permissions. Note that this is a Perl boolean,
39                         and not the string "true".
40        productCodes  -- A list of product codes associated with the image.
41        architecture  -- The architecture of the image.
42        imageType     -- The image type (machine, kernel or RAM disk).
43        kernelId      -- The kernel associated with the image.
44        ramdiskId     -- The RAM disk associated with the image.
45        platform      -- "Windows" for Windows AMIs, otherwise undef.
46        sriovNetSupport -- Specifies whether enhanced networking is enabled.
47                           "simple" if enabled.
48        stateReason   -- Explanation of a "failed" imageState. This is
49                         a VM::EC2::Instance::State::Reason
50                         object.
51        imageOwnerAlias -The AWS account alias (e.g. "self") or AWS
52                         account ID that owns the AMI.
53        name          -- Name of the AMI provided during image creation.
54        description   -- Description of the AMI provided during image
55                         creation.
56        rootDeviceType -- The root device type. One of "ebs" or
57                         "instance-store".
58        rootDeviceName -- Name of the root device, e.g. "/dev/sda1"
59        blockDeviceMapping -- List of block devices attached to this
60                          image. Each element is a
61                          VM::EC2::BlockDevice.
62        virtualizationType -- One of "paravirtual" or "hvm".
63        hypervisor     -- One of "ovm" or "xen"
64
65       In addition, the object supports the tags() method described in
66       VM::EC2::Generic:
67
68        print "ready for production\n" if $image->tags->{Released};
69
70   @instances = $image->run_instances(%args)
71       The run_instance() method will launch one or more instances based on
72       this AMI. The method takes all the arguments recognized by
73       VM::EC2->run_instances(), except for the -image_id argument. The method
74       returns a list of VM::EC2::Instance objects, which you may monitor
75       periodically until they are up and running.
76
77       All arguments are optional. See run_instances() in VM::EC2 for more
78       information.
79
80         -min_count         Minimum number of instances to launch [1]
81         -max_count         Maximum number of instances to launch [1]
82         -key_name          Name of the keypair to use
83         -security_group_id Security group ID to use for this instance.
84                            Use an arrayref for multiple group IDs
85         -security_group    Security group name to use for this instance.
86                            Use an arrayref for multiple values.
87         -user_data         User data to pass to the instances. Do NOT base64
88                            encode this. It will be done for you.
89         -instance_type     Type of the instance to use. See below for a
90                            list.
91         -placement_zone    The availability zone you want to launch the
92                            instance into. Call $ec2->regions for a list.
93         -placement_group   An existing placement group to launch the
94                            instance into. Applicable to cluster instances
95                            only.
96         -placement_tenancy Specify 'dedicated' to launch the instance on a
97                            dedicated server. Only applicable for VPC
98                            instances.
99         -kernel_id         ID of the kernel to use for the instances,
100                            overriding the kernel specified in the image.
101         -ramdisk_id        ID of the ramdisk to use for the instances,
102                            overriding the ramdisk specified in the image.
103         -block_devices     Specify block devices to map onto the instances,
104                            overriding the values specified in the image.
105                            This can be a scalar string or an arrayref for
106                            multiple mappings:
107                            Example:
108                            ['/dev/sdb=ephemeral0','/dev/sdc=snap-12345:80:false']
109         -monitoring        Pass a true value to enable detailed monitoring.
110         -subnet_id         ID of the subnet to launch the instance
111                            into. Only applicable for VPC instances.
112         -termination_protection  Pass true to lock the instance so that it
113                            cannot be terminated using the API. Use
114                            modify_instance() to unset this if youu wish to
115                            terminate the instance later.
116         -disable_api_termination -- Same as above.
117         -shutdown_behavior Pass "stop" (the default) to stop the instance
118                            and save its disk state when "shutdown" is called
119                            from within the instance. Stopped instances can
120                            be restarted later. Pass "terminate" to
121                            instead terminate the instance and discard its
122                            state completely.
123         -instance_initiated_shutdown_behavior -- Same as above.
124         -private_ip_address Assign the instance to a specific IP address
125                            from a VPC subnet (VPC only).
126         -client_token      Unique identifier that you can provide to ensure
127                            idempotency of the request. You can use
128                            $ec2->token() to generate a suitable identifier.
129                            See http://docs.amazonwebservices.com/AWSEC2/
130                                latest/UserGuide/Run_Instance_Idempotency.html
131
132       Note that after launching an instance, you may need to wait a few
133       seconds before adding tags to it or performing other operations.
134
135       See VM::EC2 for details.
136
137   $boolean = $image->make_public($public)
138       Change the isPublic flag. Provide a true value to make the image
139       public, a false one to make it private.
140
141   $state  = $image->current_status
142       Refreshes the object and then calls imageState() to return one of
143       "pending", "available" or "failed." You can use this to monitor an
144       image_creation process in progress.
145
146   @user_ids = $image->launchPermissions
147       Returns a list of user IDs with launch permission for this image. Note
148       that the AWS API calls this "launchPermission", but this module makes
149       it plural to emphasize that the result is a list.
150
151   @user_ids = $image->authorized_users
152       The same as launchPermissions.
153
154   $boolean = $image->add_authorized_users($id1,$id2,...)
155   $boolean = $image->remove_authorized_users($id1,$id2,...)
156       These methods add and remove user accounts which have launch
157       permissions for the image. The result code indicates whether the list
158       of user IDs were successfully added or removed.
159
160   $boolean = $image->add_authorized_users($id1,$id2,...)
161   $boolean = $image->remove_authorized_users($id1,$id2,...)
162   $boolean = $image->reset_authorized_users
163       These methods add and remove user accounts which have launch
164       permissions for the image. The result code indicates whether the list
165       of user IDs were successfully added or removed.
166
167       reset_authorized_users() resets the list users authored to launch
168       instances from this image to empty, effectively granting launch
169       privileges to the owner only.
170
171       See also authorized_users().
172
173   $copy = $image->copy(-region => $region, -name => $name, -description =>
174       $desc)
175       Copies the image to another region.
176
177       Required arguments:
178
179        -region           The region to copy to
180
181       Optional arguments:
182
183        -name             The name of the image.
184
185        -description      The description of the image.
186
187        -client_token     Unique identifier to ensure idempotency of the request
188
189   $image->refresh
190       This method will refresh the object from AWS, updating all values to
191       their current ones. You can call it after tagging or otherwise changing
192       image attributes.
193

STRING OVERLOADING

195       When used in a string context, this object will interpolate the
196       imageId.
197

SEE ALSO

199       VM::EC2 VM::EC2::Generic VM::EC2::BlockDevice VM::EC2::StateReason
200       VM::EC2::Instance VM::EC2::Tag
201

AUTHOR

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