VM::EC...etadata(3pm)

💖 VM::EC2::Instance::Metadata 💖

okay so bestie, welcome to VM::EC2::Instance::Metadata — it's a whole object describing the metadata of a running instance, and honestly? iconic. it's a perl thing. it's for reading your own EC2 instance's soul from the inside. let's get into it 🫶

---

✨ SYNOPSIS ✨

# For use within a running EC2 instance only!

use VM::EC2::Instance::Metadata;
my $meta = VM::EC2::Instance::Metadata->new;

# alternatively...
my $meta = VM::EC2->instance_metadata;
my $meta = $instance->metadata;

# image information
$image_id  = $meta->imageId;
$index     = $meta->imageLaunchIndex;
$path      = $meta->amiManifestPath;
$location  = $meta->imageLocation;    # same as previous
@ancestors = $meta->ancestorAmiIds;
@ancestors = $meta->imageAncestorIds; # same as previous
@codes     = $meta->productCodes;

# launch and runtime information
$inst_id   = $meta->instanceId;
$kern_id   = $meta->kernelId;
$rd_id     = $meta->ramdiskId;
$res_id    = $meta->reservationId;
$type      = $meta->instanceType;
$zone      = $meta->availabilityZone;
$userdata  = $meta->userData;
@groups    = $meta->securityGroups;
@keys      = $meta->publicKeys;
$block_dev = $meta->blockDeviceMapping; # a hashref

# Network information
$priv_name = $meta->localHostname;
$priv_name = $meta->privateDnsName;   # same as previous
$priv_ip   = $meta->localIpv4;
$priv_ip   = $meta->privateIpAddress;
$mac       = $meta->mac;
$pub_name  = $meta->publicHostname;
$pub_name  = $meta->dnsName;          # same as previous
$pub_ip    = $meta->publicIpv4;
$pub_ip    = $meta->ipAddress;
$interfaces= $meta->interfaces;       # a hashref

# IAM information
$iam_info   = $metadata->iam_info;         # a hashref
$iam_role   = $metadata->iam_role;         # name of the role
$credentials= $metadata->iam_credentials;  # VM::EC2::Security::Credentials object

# Undocumented fields
$action    = $meta->instanceAction;
$profile   = $meta->profile;

---

🌈 DESCRIPTION 🌈

So this is the interface to all the metadata that gets handed to a running instance through the http://169.254.169.254/latest URL — literally the vibe described over at http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?instancedata-data-categories.html. iykyk.

Every metadata object caches its values, so calling a method over and over costs you nothing, no cap. Methods hand you back scalars, lists, or hashrefs, whichever fits. 🎀

⚠️ bestie listen. these methods should only be called from inside a running EC2 instance. if you try to call them anywhere else, you're gonna sit there in long delays while the module tries to connect to an invalid hostname. it's giving "waiting forever in the group chat". don't do it. 😭

---

👑 METHODS 👑

$meta = VM::EC2::Instance::Metadata->new()

$meta = $ec2->instance_metadata()

$meta = $instance->metadata()

You can spin up a brand new metadata object any of these three ways, bestie:

• with this class's own new() constructor,
• by calling a VM::EC2 object's instance_metadata() method,
• or by calling a VM::EC2::Instance object's metadata () method.

pick your fighter. 💅

---

🌸 Methods that return scalar values 🌸

These ones all give you a single value back. one. singular. main character energy.

💜 Image information:

• imageId — the ID of the AMI that launched this instance
• imageLaunchIndex — this index's launch index. if four instances got launched by one $image->run_instances() call, they get numbered from 0 to 3.
• amiManifestPath — the S3 path to the image
• imageLocation — same as amiManifestPath(), kept around for consistency with VM::EC2::Image
• instanceId — the ID of this instance
• kernelId — the ID of this instance's kernel
• ramdiskId — this instance's ramdisk ID
• reservationId — this instance's reservation ID
• instanceType — the machine type, e.g. "m1.small"
• availabilityZone — this instance's availability zone
• region — this instance's region
• endpoint — this instance's endpoint
• userData — the user data you passed at launch time

💙 Network information:

• localHostname — the instance hostname that matches its internal EC2 IP address
• privateDnsName — same as localHostname(), for consistency with VM::EC2::Instance
• localIpv4 — the instance's IP address on the internal EC2 network
• privateIpAddress — same as localIpv4(), for consistency with VM::EC2::Instance
• mac — this instance's MAC (ethernet) address
• publicHostname — this instance's public hostname
• dnsName — same as publicHostname(), for consistency with VM::EC2::Instance
• publicIpv4 — this instance's public IP address
• ipAddress — same as publicIpv4(), for consistency with VM::EC2::Instance

wait, i grouped those above under image info and network info — and the launch/runtime scalars are sitting right there too, so let's not lose them: instanceId, kernelId, ramdiskId, reservationId, instanceType, availabilityZone, region, endpoint, userData. all present and accounted for, periodt. 💅

🧚 IAM information 🧚

These routines hand you info about the instance's IAM role, if it even has one. They also give you temporary security credentials for making EC2 calls, just like it says over here: http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/UsingIAM.html. 🦋

🚨 heads up bestie: these routines require you to have the perl JSON module installed, and if that module can't be loaded, it will cause a fatal error. no cap.

• iam_info — returns a hash with the fields 'LastUpdated', 'InstanceProfileArn', and 'InstanceProfileId'. these give you info about the instance's IAM role.
• iam_role — returns the IAM role name for the currently running instance
• iam_credentials — returns a VM::EC2::Security::Credentials object that you can pass to VM::EC2->new(-security_token=>$credentials)

🙈 Unknown information:

• profile — an undocumented field that holds the virtualization type, in the form "default-paravirtual"
• instanceAction — an undocumented metadata field named "instance-action"

---

🎀 Methods that return lists 🎀

these ones hand you back a whole list. more is more, bestie.

🌸 Image information

• ancestorAmiIds — list of AMIs that the current one was derived from
• imageAncestorIds — same as ancestorAmiIds() but easier to read
• productCodes — list of product codes that apply to the image this instance was launched from

💙 Launch and runtime information

• securityGroups — list of security groups this instance is assigned to. for non-VPC instances this is the security group name. for VPC instances it's the security group ID.
• publicKeys — list of public key pair names attached to this instance

---

🦋 Methods that return a hashref 🦋

these return a hashref, because the data structures are complex and honestly they're doing their best.

$devices = $meta->blockDeviceMapping

This gives you a hashref where the keys are the names of instance block devices — stuff like "/dev/sda1" — and the values are the EC2 virtual machine names. for example:

x $meta->blockDeviceMapping
0  HASH(0x9b4f2f8)
  '/dev/sda1' => 'root'
  '/dev/sda2' => 'ephemeral0'
  '/dev/sdg' => 'ebs1'
  '/dev/sdh' => 'ebs9'
  '/dev/sdi' => 'ebs10'
  'sda3' => 'swap'

for reasons that are not entirely clear, the swap device gets reported as "sda3" rather than as "/dev/sda3". it's giving mystery. we don't question it. 💀

$interfaces = $meta->interfaces

Returns a mapping of every virtual ethernet device owned by this instance. this is mostly useful for VPC instances, which can have more than one device. the hash keys are the MAC addresses of each ethernet device, and the values are hashes with these keys:

• mac
• localHostname
• localIpv4s (an array ref)
• publicIpv4s (an array ref)
• securityGroupIds (an array ref)
• subnetId
• subnetIpv4CidrBlock
• vpcId
• vpcIpv4CidrBlock

for example:

                                                                                                                                            D
x $meta->interfaces
0 HASH(0x9b4f518)
  '12:31:38:01:b8:97' => HASH(0x9eaa090)
     'localHostname' => 'domU-12-31-38-01-B8-97.compute-1.internal'
     'localIpv4s' => ARRAY(0x9b4f8a8)
        0  '10.253.191.101'
     'mac' => '12:31:38:01:b8:97'
     'publicIpv4s' => ARRAY(0x9ea9e40)
        0  '184.73.241.210'
     'securityGroupIds' => ARRAY(0x9eaa490)
          empty array
     'subnetId' => undef
     'subnetIpv4CidrBlock' => undef
     'vpcId' => undef
     'vpcIpv4CidrBlock' => undef

---

⭐ SEE ALSO ⭐

go read these next, bestie, they're the whole friend group:

• VM::EC2
• VM::EC2::Generic
• VM::EC2::BlockDevice
• VM::EC2::State::Reason
• VM::EC2::State
• VM::EC2::Instance
• VM::EC2::Tag

---

💌 AUTHOR 💌

Lincoln Stein <lincoln.stein@gmail.com>.

Copyright (c) 2011 Ontario Institute for Cancer Research

This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty.

---

okay that's the whole thing, no notes, we ate 🍓✨ and just so you know where this came from — it's from perl v5.38.2, dated 2024-08-10, and it's VM::EC...etadata(3pm) from the User Contributed Perl Documentation. slay, bye bestie 💖🦋👑