Metadata-Version: 2.0
Name: ec2-metadata
Version: 1.1.0
Summary: An easy interface to query the EC2 metadata API, with caching.
Home-page: https://github.com/adamchainz/ec2-metadata
Author: Adam Johnson
Author-email: me@adamj.eu
License: ISC License
Keywords: A,W,S,,, ,E,C,2,,, ,m,e,t,a,d,a,t,a
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: cached-property
Requires-Dist: requests

============
ec2-metadata
============

.. image:: https://img.shields.io/travis/adamchainz/ec2-metadata/master.svg
        :target: https://travis-ci.org/adamchainz/ec2-metadata

.. image:: https://img.shields.io/pypi/v/ec2-metadata.svg
        :target: https://pypi.python.org/pypi/ec2-metadata

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

A quick example:

.. code-block:: python

    >>> from ec2_metadata import ec2_metadata
    >>> print(ec2_metadata.region)
    us-east-1
    >>> print(ec2_metadata.instance_id)
    i-123456


Installation
============

Use **pip**:

.. code-block:: sh

    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
<https://github.com/boto/boto3/issues/313>`_. 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:

.. code-block:: python

    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
<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html#instancedata-data-categories>`_
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 <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html>`_
``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
---------------

.. Insert new release notes below this line

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.


