1VM::EC2::Instance::MetaUdsaetra(C3o)ntributed Perl DocumVeMn:t:aEtCi2o:n:Instance::Metadata(3)
2
6 VM::EC2::Instance::Metadata - Object describing the metadata of a
7 running instance
8
10 # For use within a running EC2 instance only!
11 use VM::EC2::Instance::Metadata;
13 my $meta = VM::EC2::Instance::Metadata->new;
14 # alternatively...
16 my $meta = VM::EC2->instance_metadata;
17 my $meta = $instance->metadata;
18 # image information
20 $image_id = $meta->imageId;
21 $index = $meta->imageLaunchIndex;
22 $path = $meta->amiManifestPath;
23 $location = $meta->imageLocation; # same as previous
24 @ancestors = $meta->ancestorAmiIds;
25 @ancestors = $meta->imageAncestorIds; # same as previous
26 @codes = $meta->productCodes;
27 # launch and runtime information
29 $inst_id = $meta->instanceId;
30 $kern_id = $meta->kernelId;
31 $rd_id = $meta->ramdiskId;
32 $res_id = $meta->reservationId;
33 $type = $meta->instanceType;
34 $zone = $meta->availabilityZone;
35 $userdata = $meta->userData;
36 @groups = $meta->securityGroups;
37 @keys = $meta->publicKeys;
38 $block_dev = $meta->blockDeviceMapping; # a hashref
39 # Network information
41 $priv_name = $meta->localHostname;
42 $priv_name = $meta->privateDnsName; # same as previous
43 $priv_ip = $meta->localIpv4;
44 $priv_ip = $meta->privateIpAddress;
45 $mac = $meta->mac;
46 $pub_name = $meta->publicHostname;
47 $pub_name = $meta->dnsName; # same as previous
48 $pub_ip = $meta->publicIpv4;
49 $pub_ip = $meta->ipAddress;
50 $interfaces= $meta->interfaces; # a hashref
51 # IAM information
53 $iam_info = $metadata->iam_info; # a hashref
54 $iam_role = $metadata->iam_role; # name of the role
55 $credentials= $metadata->iam_credentials; # VM::EC2::Security::Credentials object
56 # Undocumented fields
58 $action = $meta->instanceAction;
59 $profile = $meta->profile;
60
62 This is an interface to the metadata that is provided to a running
63 instance via the http://169.254.169.254/latest URL, as described in
64 http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?instancedata-data-categories.html.
65 Each metadata object caches its values, so there is no overhead in
67 calling a method repeatedly. Methods return scalar values, lists and
68 hashrefs as appropriate.
69 The methods from this class should only be called within the context of
71 a running EC2 instance. Attempts to call outside of this context will
72 result in long delays as the module attempts to connect to an invalid
73 hostname.
74
76 $meta = VM::EC2::Instance::Metadata->new()
77 $meta = $ec2->instance_metadata()
78 $meta = $instance->metadata()
79 You can create a new metadata object either using this class's new()
80 constructor, or by calling an VM::EC2 object's instance_metadata()
81 method, or by calling a VM::EC2::Instance object's metadata () method.
82 Methods that return scalar values
84 The following methods all return single-valued results:
85 Image information:
87 imageId -- ID of AMI used to launch this instance
88 imageLaunchIndex -- This index's launch index. If four instances
89 were launched by one $image->run_instances()
90 call, they will be numbered from 0 to 3.
91 amiManifestPath -- S3 path to the image
92 imageLocation -- Same as amiManifestPath(), for consistency with
93 VM::EC2::Image
94 Launch and runtime information:
96 instanceId -- ID of this instance
97 kernelId -- ID of this instance's kernel.
98 ramdiskId -- This instance's ramdisk ID
99 reservationId -- This instance's reservation ID
100 instanceType -- Machine type, e.g. "m1.small"
101 availabilityZone -- This instance's availability zone.
102 region -- This instance's region.
103 endpoint -- This instance's endpoint.
104 userData -- User data passed at launch time.
105 Network information:
107 localHostname -- The instance hostname corresponding to its
108 internal EC2 IP address.
109 privateDnsName -- Same as localHostname(), for consistency with
110 VM::EC2::Instance
111 localIpv4 -- The instance IP address on the internal EC2 network.
112 privateIpAddress -- Same as localIpv4(), for consistency with
113 VM::EC2::Instance.
114 mac -- This instance's MAC (ethernet) address.
115 publicHostname -- This instance's public hostname.
116 dnsName -- Same as publicHostname() for consistency with
117 VM::EC2::Instance.
118 publicIpv4 -- This instance's public IP address.
119 ipAddress -- Same as publicIpv4() for consistency with
120 VM::EC2::Instance.
121 IAM information
123 These routines return information about the instance's IAM role, if
124 any. These calls also provide a temporary security credentials for
125 making EC2 calls, as described here:
126 http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/UsingIAM.html.
127 Note that these routines require installation of the perl JSON
129 module, and will cause a fatal error if this module cannot be
130 loaded.
131 iam_info -- Returns a hash containing the fields 'LastUpdated',
133 'InstanceProfileArn', and 'InstanceProfileId'. These
134 provide information about the instance's IAM role.
135 iam_role -- Returns the IAM role name for the currently running
136 instance.
137 iam_credentials -- Returns a VM::EC2::Security::Credentials object that can
138 be passed to VM::EC2->new(-security_token=>$credentials).
139 Unknown information:
141 profile -- An undocumented field that contains the virtualization
142 type in the form "default-paravirtual".
143 instanceAction -- Undocumented metadata field named "instance-action"
144 Methods that return lists
146 The following methods all return lists.
147 Image information
149 ancestorAmiIds -- List of AMIs from which the current one was derived
150 imageAncestorIds -- Same as ancestorAmiIds() but easier to read.
151 productCodes -- List of product codes applying to the image from which
152 this instance was launched.
153 Launch and runtime information
155 securityGroups -- List of security groups to which this instance is assigned.
156 For non-VPC instances, this will be the security group
157 name. For VPC instances, this will be the security group ID.
158 publicKeys -- List of public key pair names attached to this instance.
159 Methods that return a hashref
161 The following methods return a hashref for representing complex data
162 structures:
163 $devices = $meta->blockDeviceMapping
165 This returns a hashref in which the keys are the names of instance
166 block devices, such as "/dev/sda1", and the values are the EC2
167 virtual machine names. For example:
168 x $meta->blockDeviceMapping
170 0 HASH(0x9b4f2f8)
171 '/dev/sda1' => 'root'
172 '/dev/sda2' => 'ephemeral0'
173 '/dev/sdg' => 'ebs1'
174 '/dev/sdh' => 'ebs9'
175 '/dev/sdi' => 'ebs10'
176 'sda3' => 'swap'
177 For reasons that are not entirely clear, the swap device is
179 reported as "sda3" rather than as "/dev/sda3".
180 $interfaces = $meta->interfaces
182 Returns a mapping of all virtual ethernet devices owned by this
183 instance. This is primarily useful for VPC instances, which can
184 have more than one device. The hash keys are the MAC addresses of
185 each ethernet device, and the values are hashes that have the
186 following keys:
187 mac
189 localHostname
190 localIpv4s (an array ref)
191 publicIpv4s (an array ref)
192 securityGroupIds (an array ref)
193 subnetId
194 subnetIpv4CidrBlock
195 vpcId
196 vpcIpv4CidrBlock
197 For example:
199 D
201 x $meta->interfaces
202 0 HASH(0x9b4f518)
203 '12:31:38:01:b8:97' => HASH(0x9eaa090)
204 'localHostname' => 'domU-12-31-38-01-B8-97.compute-1.internal'
205 'localIpv4s' => ARRAY(0x9b4f8a8)
206 0 '10.253.191.101'
207 'mac' => '12:31:38:01:b8:97'
208 'publicIpv4s' => ARRAY(0x9ea9e40)
209 0 '184.73.241.210'
210 'securityGroupIds' => ARRAY(0x9eaa490)
211 empty array
212 'subnetId' => undef
213 'subnetIpv4CidrBlock' => undef
214 'vpcId' => undef
215 'vpcIpv4CidrBlock' => undef
216
218 VM::EC2 VM::EC2::Generic VM::EC2::BlockDevice VM::EC2::State::Reason
219 VM::EC2::State VM::EC2::Instance VM::EC2::Tag
220
222 Lincoln Stein <lincoln.stein@gmail.com>.
223 Copyright (c) 2011 Ontario Institute for Cancer Research
225 This package and its accompanying libraries is free software; you can
227 redistribute it and/or modify it under the terms of the GPL (either
228 version 1, or at your option, any later version) or the Artistic
229 License 2.0. Refer to LICENSE for the full license text. In addition,
230 please see DISCLAIMER.txt for disclaimers of warranty.
231perl v5.36.0 2023-01-20 VM::EC2::Instance::Metadata(3)