1VM::EC2::Instance::MetaUdsaetra(C3o)ntributed Perl DocumVeMn:t:aEtCi2o:n:Instance::Metadata(3)
2
3
4

NAME

6       VM::EC2::Instance::Metadata - Object describing the metadata of a
7       running instance
8

SYNOPSIS

10        # For use within a running EC2 instance only!
11
12        use VM::EC2::Instance::Metadata;
13        my $meta = VM::EC2::Instance::Metadata->new;
14
15        # alternatively...
16        my $meta = VM::EC2->instance_metadata;
17        my $meta = $instance->metadata;
18
19        # 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
28        # 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
40        # 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
52        # 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
57        # Undocumented fields
58        $action    = $meta->instanceAction;
59        $profile   = $meta->profile;
60

DESCRIPTION

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
66       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
70       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

METHODS

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
83   Methods that return scalar values
84       The following methods all return single-valued results:
85
86       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
95       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
106       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
122       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
128           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
132            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
140       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
145   Methods that return lists
146       The following methods all return lists.
147
148       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
154       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
160   Methods that return a hashref
161       The following methods return a hashref for representing complex data
162       structures:
163
164       $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
169            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
178           For reasons that are not entirely clear, the swap device is
179           reported as "sda3" rather than as "/dev/sda3".
180
181       $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
188            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
198           For example:
199
200                                                                                                                                                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

SEE ALSO

218       VM::EC2 VM::EC2::Generic VM::EC2::BlockDevice VM::EC2::State::Reason
219       VM::EC2::State VM::EC2::Instance VM::EC2::Tag
220

AUTHOR

222       Lincoln Stein <lincoln.stein@gmail.com>.
223
224       Copyright (c) 2011 Ontario Institute for Cancer Research
225
226       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.
231
232
233
234perl v5.36.0                      2023-01-20    VM::EC2::Instance::Metadata(3)
Impressum