An easy interface to query the EC2 metadata API, with caching.
Project description
An easy interface to query the EC2 metadata API, with caching.
A quick example:
>>> from ec2_metadata import ec2_metadata
>>> print(ec2_metadata.region)
us-east-1
>>> print(ec2_metadata.instance_id)
i-123456Installation
Use pip:
pip install ec2-metadataTested on Python 2.7 and Python 3.6.
Why?
boto came with a utility function to retrieve the instance metadata as a lazy loading dictionary, boto.utils.get_instance_metadata, but this has not been ported to boto3, as per this issue. I thought that rather than building a new version inside boto3 it would work well as a standalone library.
API
EC2Metadata(session=None)
A container that represents the data available on the EC2 metadata service. Attributes don’t entirely correspond to the paths in the metadata service - they have been ‘cleaned up’. You may also want to refer to the metadata service docs to understand the exact contents.
There’s a singleton instance of it at the name ec2_metadata which should cover 90% of use cases. Use it like:
from ec2_metadata import ec2_metadata
ec2_metadata.regionThe session argument, if provided, should be an instance of requests.Session, allowing you to customize the way requests are made.
All the attributes cache on first access, since they are mostly immutable, or at least require an instance stop to change, however some properties like network interfaces can change over the lifetime of an instance. If you want to clear the cache of one attribute you can just del it:
del ec2_metadata.network_interfacesTo clear all, use the clear_all() method as per below.
account_id: str
The current AWS account ID, e.g. '123456789012'.
ami_id: str
The ID of the AMI used to launch the instance, e.g. 'ami-123456'.
availability_zone: str
The name of the current AZ e.g. 'eu-west-1a'.
ami_launch_index: int
The index of the instance in the launch request, zero-based, e.g. 0.
ami_manifest_path: str
The path to the AMI manifest file in Amazon S3, or '(unknown)' on EBS-backed AMI’s.
clear_all() -> None
Clear all the cached attributes on the class, meaning their next access will re-fetch the data from the metadata API.
iam_info: dict
A dictionary of data for the IAM role attached to the instance, or None if no role is attached.
instance_id: str
The current instance’s ID, e.g. 'i-123456'
instance_identity_document: dict
A dictionary of dynamic data - see AWS docs.
instance_profile_arn: str
The ARN of the IAM role/instance profile attached to the instance, taken from iam_info, or None if no role is attached.
instance_profile_id: str
The ID of the IAM role/instance profile attached to the instance, taken from iam_info, or None if no role is attached.
instance_type: str
The current instance’s type, e.g. 't2.nano'
mac : str
The instance’s MAC address, e.g. '0a:d2:ae:4d:f3:12'
network_interfaces: Dict[str, NetworkInterface]
A dictionary of mac address to NetworkInterface, which represents the data available on a network interface - see below. E.g. {'01:23:45:67:89:ab': NetworkInterface('01:23:45:67:89:ab')}
private_hostname : str
The private IPv4 DNS hostname of the instance, e.g. 'ip-172-30-0-0.eu-west-1.compute.internal' .
private_ipv4: str
The private IPv4 of the instance, e.g. '172.30.0.0'.
public_hostname : str
The public DNS hostname of the instance, or None if the instance is not public, e.g. 'ec2-1-2-3-4.compute-1.amazonaws.com'.
public_ipv4: str
The public IPv4 address of the instance, or None if the instance is not public, e.g. '1.2.3.4'.
region: str
The region the instance is running in, e.g. 'eu-west-1'.
reservation_id: str
The ID of the reservation used to launch the instance, e.g. 'r-12345678901234567'.
security_groups : List[str]
List of security groups by name, e.g. ['ssh-access', 'custom-sg-1'].
user_data: bytes
The raw user data assigned to the instance (not base64 encoded), or None if there is none.
NetworkInterface
Represents a single network interface, as retrieved from EC2Metadata.network_interfaces. Again like EC2Metadata all its attributes cache on first access, and can be cleared with del or its clear_all() method.
device_number: int
The unique device number associated with that interface, e.g. 0.
ipv4_associations: Dict[str, List[str]]
A dictionary mapping public IP addresses on the interface to the list of private IP addresses associated with that public IP, for each public IP that is associated with the interface, e.g. {'54.0.0.1': ['172.30.0.0']}.
mac: str
The MAC address of the interface, e.g. '01:23:45:67:89:ab'.
owner_id: str
The AWS Account ID of the owner of the network interface, e.g. '123456789012'.
private_hostname: str
The interface’s local/private hostname, e.g. 'ip-172-30-0-0.eu-west-1.compute.internal'.
private_ipv4s: List[str]
The private IPv4 addresses associated with the interface, e.g. ['172.30.0.0'].
public_hostname: str
The interface’s public DNS (IPv4), e.g. 'ec2-54-0-0-0.compute-1.amazonaws.com'.
public_ipv4s: List[str]
The Elastic IP addresses associated with the interface, e.g. ['54.0.0.0'].
security_groups: List[str]
The names of the security groups to which the network interface belongs, e.g. ['ssh-access', 'custom-sg-1'].
security_group_ids: List[str]
The names of the security groups to which the network interface belongs, e.g. ['sg-12345678', 'sg-12345679'].
subnet_id: str
The ID of the subnet in which the interface resides, e.g. 'subnet-12345678'.
subnet_ipv4_cidr_block: str
The IPv4 CIDR block of the subnet in which the interface resides, e.g. '172.30.0.0/24'.
vpc_id: str
The ID of the VPC in which the interface resides, e.g. 'vpc-12345678'.
vpc_ipv4_cidr_block: str
The IPv4 CIDR block of the VPC, or None if the instance isn’t in a VPC, e.g. '172.30.0.0/16'.
vpc_ipv4_cidr_blocks: List[str]
The list of IPv4 CIDR blocks, or None if the instance isn’t in a VPC, e.g. ['172.30.0.0/16'].
History
Pending Release
1.4.0 (2017-10-24)
Add iam_info, instance_profile_arn and instance_profile_id attributes
Refactor handling non-200 responses to be more strict for attributes where 404’s are allowed.
1.3.1 (2017-10-17)
Fix rendering of docs on PyPI.
1.3.0 (2017-10-17)
All methods can now raise requests.exceptions.HTTPError if the metadata API returns a bad response, rather than failing during parsing or silently returning data from non-200 responses.
EC2Metadata can now be passed a requests.Session object for customization of the way requests are made.
1.2.1 (2017-08-31)
Make public_* properties return None for instances that aren’t public.
1.2.0 (2017-08-26)
Add network_interfaces attribute which is a list of NetworkInterface instances, which have many attributes themselves.
1.1.0 (2017-08-07)
Add security_groups and user_data attributes.
1.0.0 (2017-06-16)
First release on PyPI, featuring ec2_metadata object.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ec2_metadata-1.4.0-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 017a121b41f763a7b23976c8195cb7121a4a8f81cad4d0c90dbffcdf469474e6 |
|
| MD5 | 55da326b6f950e9fd5afe38f2814829f |
|
| BLAKE2b-256 | a390dd308e9f5654f2a94d3f9b207a057a932551bb443a937975c8a4de8e8a03 |
