1VM::EC2::Image(3) User Contributed Perl Documentation VM::EC2::Image(3)
2
6 VM::EC2::Image - Object describing an Amazon Machine Image (AMI)
7
9 use VM::EC2;
10 $ec2 = VM::EC2->new(...);
12 $image = $ec2->describe_images(-image_id=>'ami-12345');
13 $state = $image->imageState;
15 $owner = $image->imageOwnerId;
16 $rootdev = $image->rootDeviceName;
17 @devices = $image->blockDeviceMapping;
18 $tags = $image->tags;
19 @instances = $image->run_instances(-min_count=>10);
21
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
29 These object methods are supported:
30 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 In addition, the object supports the tags() method described in
66 VM::EC2::Generic:
67 print "ready for production\n" if $image->tags->{Released};
69 @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 All arguments are optional. See run_instances() in VM::EC2 for more
78 information.
79 -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 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 See VM::EC2 for details.
136 $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 $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 @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 @user_ids = $image->authorized_users
152 The same as launchPermissions.
153 $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 $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 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 See also authorized_users().
172 $copy = $image->copy(-region => $region, -name => $name, -description =>
174 $desc)
175 Copies the image to another region.
176 Required arguments:
178 -region The region to copy to
180 Optional arguments:
182 -name The name of the image.
184 -description The description of the image.
186 -client_token Unique identifier to ensure idempotency of the request
188 $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
195 When used in a string context, this object will interpolate the
196 imageId.
197
199 VM::EC2 VM::EC2::Generic VM::EC2::BlockDevice VM::EC2::StateReason
200 VM::EC2::Instance VM::EC2::Tag
201
203 Lincoln Stein <lincoln.stein@gmail.com>.
204 Copyright (c) 2011 Ontario Institute for Cancer Research
206 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.
212perl v5.32.0 2020-07-28 VM::EC2::Image(3)