Skip to main content

An easy interface to query the EC2 metadata API, with caching.

Project description

https://img.shields.io/travis/adamchainz/ec2-metadata/master.svg https://img.shields.io/pypi/v/ec2-metadata.svg

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-123456

Installation

Use pip:

pip install ec2-metadata

Tested 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.

Usage

There is a special singleton object in the module to import:

from ec2_metadata import ec2_metadata

This object has a number of lazy attributes that pull the respective data from the metadata service on first access, all documented below. They are all strings (Python 3 str) except where noted.

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.

Attribute Name

Contents

account_id

The current AWS account ID, e.g. '123456789012'

ami_id

The ID of the AMI used to launch the instance, e.g. 'ami-123456'

availability_zone

The name of the current AZ e.g. 'eu-west-1a'

ami_launch_index

The index of the instance in the launch request, zero-based, e.g. 0

ami_manifest_path

The path to the AMI manifest file in Amazon S3, or '(unknown)' on EBS-backed AMI’s

instance_id

The current instance’s ID, e.g. 'i-123456'

instance_identity_document

A dictionary of dynamic data, see AWS docs

instance_type

The current instance’s type, e.g. 't2.nano'

mac

The instance’s MAC address, e.g. '0a:d2:ae:4d:f3:12'

private_hostname

The private IPv4 DNS hostname of the instance, e.g. 'ip-172-30-0-0.eu-west-1.compute.internal'

private_ipv4

The private IPv4 of the instance, e.g. '172.30.0.0'

public_hostname

The public DNS hostname of the instance, e.g. 'ec2-1-2-3-4.compute-1.amazonaws.com'

public_ipv4

The public IPv4 address of the instance, e.g. '1.2.3.4'

region

The region the instance is running in, e.g. 'eu-west-1'

reservation_id

The ID of the reservation used to launch the instance, e.g. 'r-12345678901234567'

security_groups

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.

These values should all be safe to cache for the lifetime of your Python process, since they are (nearly entirely) immutable (some things can change, e.g. public_ipv4 when you attach an Elastic IP to the instance). If you need to flush the caching, you can call ec2_metadata.clear_all() to wipe it all.

History

Pending Release

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ec2-metadata-1.1.0.tar.gz (4.9 kB view hashes)

Uploaded Source

Built Distribution

ec2_metadata-1.1.0-py2.py3-none-any.whl (6.6 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page