============
ec2-metadata
============
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/ec2-metadata/main.yml?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/ec2-metadata/actions?workflow=CI
.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
:target: https://github.com/adamchainz/ec2-metadata/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/ec2-metadata.svg?style=for-the-badge
:target: https://pypi.org/project/ec2-metadata/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
An easy interface to query the EC2 metadata API (version 2), with caching.
A quick example:
.. code-block:: pycon
>>> 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
python -m pip install ec2-metadata
Python 3.8 to 3.12 supported.
----
**Working on a Django project?**
Improve your skills with `one of my books <https://adamj.eu/books/>`__.
----
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.
Instance Metadata Service Version 2
===================================
In November 2019, AWS released
`version 2 <https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/>`__
of the instance metadata service. It's more secure against Server Side Request
Forgery (SSRF) attacks.
``ec2-metadata`` now uses it exclusively. You can therefore consider disabling
version 1, as per
`AWS' guide <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html#instance-metadata-transition-to-version-2>`__.
**Note:** Instance Metadata Service v2 has a default IP hop limit of 1.
This can mean that you can see ``requests.exceptions.ReadTimeout`` errors from within Docker containers.
To solve this, reconfigure your EC2 instance’s metadata options to allow three hops with |aws ec2 modify-instance-metadata-options|__:
.. |aws ec2 modify-instance-metadata-options| replace:: ``aws ec2 modify-instance-metadata-options``
__ https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html
.. code-block:: bash
aws ec2 modify-instance-metadata-options --instance-id <instance-id> --http-put-response-hop-limit 3
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
<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html>`_
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:
.. code-block:: python
from ec2_metadata import ec2_metadata
ec2_metadata.region
The ``session`` argument, if provided, should be an instance of
``requests.Session``, allowing you to customize the way requests are made.
Most of the attributes are cached, except where noted below. This is because
they are mostly immutable, or at least require an instance stop to change.
However some cached attributes do represent things that can change without an
instance stop, but rarely do, such as network devices.
The caching is done with ``@cached_property``, so they cache on first access.
If you want to clear the cache of one attribute you can just `del` it:
.. code-block:: python
del ec2_metadata.network_interfaces
To 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'``.
``autoscaling_target_lifecycle_state: str | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Uncached.**
The target Auto Scaling lifecycle state that the instance is transitionioning to, or ``None`` if the instance is not in an autoscaling group.
See AWS docs page `Retrieve the target lifecycle state through instance metadata <https://docs.aws.amazon.com/autoscaling/ec2/userguide/retrieving-target-lifecycle-state-through-imds.html>`__.
``availability_zone: str``
~~~~~~~~~~~~~~~~~~~~~~~~~~
The name of the current AZ e.g. ``'eu-west-1a'``.
``availability_zone_id: str | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The unique, cross-account ID of the current AZ e.g. ``'use1-az6'``.
See AWS docs page `AZ IDs for your AWS resources
<https://docs.aws.amazon.com/ram/latest/userguide/working-with-az-ids.html>`__.
``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. This includes clearing the token used
to authenticate with the service.
``domain: str``
~~~~~~~~~~~~~~~
The domain for AWS resources for the region. E.g. ``'amazonaws.com'`` for the
standard AWS regions and GovCloud (US), or ``'amazonaws.com.cn'`` for China.
``iam_info: IamInfoDict | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A dictionary of data for the IAM role attached to the instance, or ``None`` if no role is attached.
The dict has this type, based on what the metadata service returns:
.. code-block:: python
class IamInfoDict(TypedDict):
InstanceProfileArn: str
InstanceProfileId: str
LastUpdated: str
``iam_security_credentials: IamSecurityCredentialsDict | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A dictionary of data for the security credentials associated with the IAM role attached to the instance, or ``None`` if no role is attached.
See the `AWS docs section “Retrieve security credentials from instance metadata” <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#instance-metadata-security-credentials>`__
for details.
The dict has this type, based on that document:
.. code-block:: python
class IamSecurityCredentialsDict(TypedDict):
LastUpdated: str
Type: str
AccessKeyId: str
SecretAccessKey: str
Token: str
Expiration: str
``instance_action: str``
~~~~~~~~~~~~~~~~~~~~~~~~
**Uncached.**
A state that notifies if the instance will reboot in preparation
for bundling. See the `AWS docs section “Instance Metadata Categories”
<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html>`_
for the valid values.
``instance_id: str``
~~~~~~~~~~~~~~~~~~~~
The current instance's ID, e.g. ``'i-123456'``
``instance_identity_document: InstanceIdentityDocumentDict``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A dictionary of dynamic data about the instance.
See the `AWS docs page “Instance Identity Documents” <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html>`__ for an explanation of the contents.
The dict has this type, based on that document:
.. code-block:: python
class InstanceIdentityDocumentDict(TypedDict):
accountId: str
architecture: Literal["i386", "x86_64", "arm64"]
availabilityZone: str
billingProducts: list[str] | None
marketplaceProductCodes: list[str] | None
imageId: str
instanceId: str
instanceType: str
kernelId: str | None
pendingTime: str
privateIp: str
ramdiskId: str | None
region: str
version: str
``instance_profile_arn: str | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ID of the IAM role/instance profile attached to the instance, taken from
``iam_info``, or ``None`` if no role is attached.
``instance_profile_name: str | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The instance profile name, extracted from ``instance_profile_arn``, or ``None`` if no role is attached.
``instance_type: str``
~~~~~~~~~~~~~~~~~~~~~~
The current instance's type, e.g. ``'t2.nano'``
``kernel_id: str | None``
~~~~~~~~~~~~~~~~~~~~~~~~~
The current instance's kernel ID, or ``None`` if it doesn't have one, e.g.
``'aki-dc9ed9af'``.
``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')}``
``partition: str``
~~~~~~~~~~~~~~~~~~
The AWS partition where the instance is running. E.g. ``'aws'`` for the
standard AWS regions, ``'aws-us-gov'`` for GovCloud (US), or ``'aws-cn'``
for China.
``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 | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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']``.
``spot_instance_action: SpotInstanceAction | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Uncached.**
An object describing an action about to happen to this spot instance.
Returns ``None`` if the instance is not spot, or not marked for termination.
The ``SpotInstanceAction`` object has two attributes:
* ``action: str`` - the action about to happen, one of ``"hibernate"``, ``"stop"``, or ``"terminate"``.
* ``time: datetime`` - the approximate UTC datetime when the action will occur.
See `AWS docs section <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-instance-termination-notices.html#instance-action-metadata>`__ for a little more information.
``tags: InstanceTags``
~~~~~~~~~~~~~~~~~~~~~~
A dict-like mapping of the tags for the instance (documented below).
This requires you to `explicitly enable the feature <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS>`__ for the instance.
If the feature is not enabled, accessing this attribute raises an error.
(It also seems that there is a bug where if the feature is enabled and then disabled, the metadata service returns an empty response.
This is indistinguishable from “no tags”, so beware that in that case, ``InstanceTags`` will just look like an empty mapping.)
``user_data: bytes | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The raw user data assigned to the instance (not base64 encoded), or ``None`` if
there is none.
``InstanceTags``
----------------
A dict-like mapping of tag names to values (both ``str``\s).
To avoid unnecessary requests, the mapping is lazy: values are only fetched when required.
(Names are known on construction though, from the first request in ``EC2Metadata.tags``.)
The metadata service will receive tag updates on some instance types, as per `the AWS documentation <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#work-with-tags-in-IMDS>`__:
If you add or remove an instance tag, the instance metadata is updated while the instance is running for instances built on the Nitro System, without needing to stop and then start the instance.
For all other instances, to update the tags in the instance metadata, you must stop and then start the instance.
Because ``InstanceTags`` is cached, it won’t reflect such updates on Nitro instances unless you clear it first:
.. code-block:: python
del ec2_metadata.tags
ec2_metadata.tags["Name"] # fresh
``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``.
``interface_id: str``
~~~~~~~~~~~~~~~~~~~~~
The unique id used to identify the Elastic Network Interface, e.g. ``'eni-12345'``.
``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']}``.
``ipv6s: list[str]``
~~~~~~~~~~~~~~~~~~~~
The IPv6 addresses associated with the interface, e.g.
``['2001:db8:abcd:ef00::1234']``.
``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 | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The IPv4 CIDR block of the subnet in which the interface resides, or ``None``
if there is none, e.g. ``'172.30.0.0/24'``.
``subnet_ipv6_cidr_blocks: list[str]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The list of IPv6 CIDR blocks of the subnet in which the interface resides, e.g.
``['2001:db8:abcd:ef00::/64']``. If the subnet does not have any IPv6 CIDR
blocks or the instance isn't in a VPC, the list will be empty, e.g. ``[]``.
``vpc_id: str``
~~~~~~~~~~~~~~~
The ID of the VPC in which the interface resides, e.g. ``'vpc-12345678'``.
``vpc_ipv4_cidr_block: str | None``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 e.g. ``['172.30.0.0/16']``. If the interface
doesn’t have any such CIDR blocks, the list will be empty.
``vpc_ipv6_cidr_blocks: list[str]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The list of IPv6 CIDR blocks of the VPC in which the interface resides, e.g.
``['2001:db8:abcd:ef00::/56']``. If the VPC does not have any IPv6 CIDR blocks
or the instance isn't in a VPC, the list will be empty, e.g. ``[]``.
Raw data
{
"_id": null,
"home_page": "https://github.com/adamchainz/ec2-metadata",
"name": "ec2-metadata",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "AWS,EC2,metadata",
"author": "Adam Johnson",
"author_email": "me@adamj.eu",
"download_url": "https://files.pythonhosted.org/packages/fd/b1/a5768b216e8b847a5dadecc06ea7653b5f8395f1a0fca3b542bc15318afb/ec2_metadata-2.13.0.tar.gz",
"platform": null,
"description": "============\nec2-metadata\n============\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/ec2-metadata/main.yml?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/ec2-metadata/actions?workflow=CI\n\n.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge\n :target: https://github.com/adamchainz/ec2-metadata/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/ec2-metadata.svg?style=for-the-badge\n :target: https://pypi.org/project/ec2-metadata/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\nAn easy interface to query the EC2 metadata API (version 2), with caching.\n\nA quick example:\n\n.. code-block:: pycon\n\n >>> from ec2_metadata import ec2_metadata\n >>> print(ec2_metadata.region)\n us-east-1\n >>> print(ec2_metadata.instance_id)\n i-123456\n\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: sh\n\n python -m pip install ec2-metadata\n\nPython 3.8 to 3.12 supported.\n\n----\n\n**Working on a Django project?**\nImprove your skills with `one of my books <https://adamj.eu/books/>`__.\n\n----\n\nWhy?\n====\n\n``boto`` came with a utility function to retrieve the instance metadata as a\nlazy loading dictionary, ``boto.utils.get_instance_metadata``, but this has not\nbeen ported to ``boto3``, as per `this issue\n<https://github.com/boto/boto3/issues/313>`_. I thought that rather than\nbuilding a new version inside ``boto3`` it would work well as a standalone\nlibrary.\n\nInstance Metadata Service Version 2\n===================================\n\nIn November 2019, AWS released\n`version 2 <https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/>`__\nof the instance metadata service. It's more secure against Server Side Request\nForgery (SSRF) attacks.\n\n``ec2-metadata`` now uses it exclusively. You can therefore consider disabling\nversion 1, as per\n`AWS' guide <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html#instance-metadata-transition-to-version-2>`__.\n\n**Note:** Instance Metadata Service v2 has a default IP hop limit of 1.\nThis can mean that you can see ``requests.exceptions.ReadTimeout`` errors from within Docker containers.\nTo solve this, reconfigure your EC2 instance\u2019s metadata options to allow three hops with |aws ec2 modify-instance-metadata-options|__:\n\n.. |aws ec2 modify-instance-metadata-options| replace:: ``aws ec2 modify-instance-metadata-options``\n__ https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html\n\n.. code-block:: bash\n\n aws ec2 modify-instance-metadata-options --instance-id <instance-id> --http-put-response-hop-limit 3\n\nAPI\n===\n\n``EC2Metadata(session=None)``\n-----------------------------\n\nA container that represents the data available on the EC2 metadata service.\nAttributes don't entirely correspond to the paths in the metadata service -\nthey have been 'cleaned up'. You may also want to refer to the `metadata\nservice docs\n<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html>`_\nto understand the exact contents.\n\nThere's a singleton instance of it at the name ``ec2_metadata`` which should\ncover 90% of use cases. Use it like:\n\n.. code-block:: python\n\n from ec2_metadata import ec2_metadata\n\n ec2_metadata.region\n\nThe ``session`` argument, if provided, should be an instance of\n``requests.Session``, allowing you to customize the way requests are made.\n\nMost of the attributes are cached, except where noted below. This is because\nthey are mostly immutable, or at least require an instance stop to change.\nHowever some cached attributes do represent things that can change without an\ninstance stop, but rarely do, such as network devices.\n\nThe caching is done with ``@cached_property``, so they cache on first access.\nIf you want to clear the cache of one attribute you can just `del` it:\n\n.. code-block:: python\n\n del ec2_metadata.network_interfaces\n\nTo clear all, use the ``clear_all()`` method as per below.\n\n\n``account_id: str``\n~~~~~~~~~~~~~~~~~~~\n\nThe current AWS account ID, e.g. ``'123456789012'``.\n\n``ami_id: str``\n~~~~~~~~~~~~~~~\n\nThe ID of the AMI used to launch the instance, e.g. ``'ami-123456'``.\n\n``autoscaling_target_lifecycle_state: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n**Uncached.**\nThe target Auto Scaling lifecycle state that the instance is transitionioning to, or ``None`` if the instance is not in an autoscaling group.\nSee AWS docs page `Retrieve the target lifecycle state through instance metadata <https://docs.aws.amazon.com/autoscaling/ec2/userguide/retrieving-target-lifecycle-state-through-imds.html>`__.\n\n``availability_zone: str``\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe name of the current AZ e.g. ``'eu-west-1a'``.\n\n``availability_zone_id: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe unique, cross-account ID of the current AZ e.g. ``'use1-az6'``.\nSee AWS docs page `AZ IDs for your AWS resources\n<https://docs.aws.amazon.com/ram/latest/userguide/working-with-az-ids.html>`__.\n\n``ami_launch_index: int``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe index of the instance in the launch request, zero-based, e.g. ``0``.\n\n``ami_manifest_path: str``\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe path to the AMI manifest file in Amazon S3, or ``'(unknown)'`` on\nEBS-backed AMI's.\n\n``clear_all() -> None``\n~~~~~~~~~~~~~~~~~~~~~~~\n\nClear all the cached attributes on the class, meaning their next access will\nre-fetch the data from the metadata API. This includes clearing the token used\nto authenticate with the service.\n\n``domain: str``\n~~~~~~~~~~~~~~~\n\nThe domain for AWS resources for the region. E.g. ``'amazonaws.com'`` for the\nstandard AWS regions and GovCloud (US), or ``'amazonaws.com.cn'`` for China.\n\n``iam_info: IamInfoDict | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA dictionary of data for the IAM role attached to the instance, or ``None`` if no role is attached.\nThe dict has this type, based on what the metadata service returns:\n\n.. code-block:: python\n\n class IamInfoDict(TypedDict):\n InstanceProfileArn: str\n InstanceProfileId: str\n LastUpdated: str\n\n``iam_security_credentials: IamSecurityCredentialsDict | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA dictionary of data for the security credentials associated with the IAM role attached to the instance, or ``None`` if no role is attached.\nSee the `AWS docs section \u201cRetrieve security credentials from instance metadata\u201d <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#instance-metadata-security-credentials>`__\nfor details.\nThe dict has this type, based on that document:\n\n.. code-block:: python\n\n class IamSecurityCredentialsDict(TypedDict):\n LastUpdated: str\n Type: str\n AccessKeyId: str\n SecretAccessKey: str\n Token: str\n Expiration: str\n\n``instance_action: str``\n~~~~~~~~~~~~~~~~~~~~~~~~\n\n**Uncached.**\nA state that notifies if the instance will reboot in preparation\nfor bundling. See the `AWS docs section \u201cInstance Metadata Categories\u201d\n<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html>`_\nfor the valid values.\n\n``instance_id: str``\n~~~~~~~~~~~~~~~~~~~~\n\nThe current instance's ID, e.g. ``'i-123456'``\n\n``instance_identity_document: InstanceIdentityDocumentDict``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA dictionary of dynamic data about the instance.\nSee the `AWS docs page \u201cInstance Identity Documents\u201d <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html>`__ for an explanation of the contents.\nThe dict has this type, based on that document:\n\n.. code-block:: python\n\n class InstanceIdentityDocumentDict(TypedDict):\n accountId: str\n architecture: Literal[\"i386\", \"x86_64\", \"arm64\"]\n availabilityZone: str\n billingProducts: list[str] | None\n marketplaceProductCodes: list[str] | None\n imageId: str\n instanceId: str\n instanceType: str\n kernelId: str | None\n pendingTime: str\n privateIp: str\n ramdiskId: str | None\n region: str\n version: str\n\n``instance_profile_arn: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ARN of the IAM role/instance profile attached to the instance, taken from\n``iam_info``, or ``None`` if no role is attached.\n\n``instance_profile_id: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ID of the IAM role/instance profile attached to the instance, taken from\n``iam_info``, or ``None`` if no role is attached.\n\n\n``instance_profile_name: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe instance profile name, extracted from ``instance_profile_arn``, or ``None`` if no role is attached.\n\n``instance_type: str``\n~~~~~~~~~~~~~~~~~~~~~~\n\nThe current instance's type, e.g. ``'t2.nano'``\n\n``kernel_id: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe current instance's kernel ID, or ``None`` if it doesn't have one, e.g.\n``'aki-dc9ed9af'``.\n\n``mac : str``\n~~~~~~~~~~~~~\n\nThe instance's MAC address, e.g. ``'0a:d2:ae:4d:f3:12'``\n\n``network_interfaces: dict[str, NetworkInterface]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA dictionary of mac address to ``NetworkInterface``, which represents the data\navailable on a network interface - see below. E.g.\n``{'01:23:45:67:89:ab': NetworkInterface('01:23:45:67:89:ab')}``\n\n``partition: str``\n~~~~~~~~~~~~~~~~~~\n\nThe AWS partition where the instance is running. E.g. ``'aws'`` for the\nstandard AWS regions, ``'aws-us-gov'`` for GovCloud (US), or ``'aws-cn'``\nfor China.\n\n``private_hostname : str``\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe private IPv4 DNS hostname of the instance, e.g.\n``'ip-172-30-0-0.eu-west-1.compute.internal'`` .\n\n``private_ipv4: str``\n~~~~~~~~~~~~~~~~~~~~~\n\nThe private IPv4 of the instance, e.g. ``'172.30.0.0'``.\n\n``public_hostname : str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe public DNS hostname of the instance, or ``None`` if the instance is not\npublic, e.g. ``'ec2-1-2-3-4.compute-1.amazonaws.com'``.\n\n``public_ipv4: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe public IPv4 address of the instance, or ``None`` if the instance is not\npublic, e.g. ``'1.2.3.4'``.\n\n``region: str``\n~~~~~~~~~~~~~~~\n\nThe region the instance is running in, e.g. ``'eu-west-1'``.\n\n``reservation_id: str``\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ID of the reservation used to launch the instance, e.g.\n``'r-12345678901234567'``.\n\n``security_groups : list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nList of security groups by name, e.g. ``['ssh-access', 'custom-sg-1']``.\n\n``spot_instance_action: SpotInstanceAction | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n**Uncached.**\nAn object describing an action about to happen to this spot instance.\nReturns ``None`` if the instance is not spot, or not marked for termination.\n\nThe ``SpotInstanceAction`` object has two attributes:\n\n* ``action: str`` - the action about to happen, one of ``\"hibernate\"``, ``\"stop\"``, or ``\"terminate\"``.\n* ``time: datetime`` - the approximate UTC datetime when the action will occur.\n\nSee `AWS docs section <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-instance-termination-notices.html#instance-action-metadata>`__ for a little more information.\n\n``tags: InstanceTags``\n~~~~~~~~~~~~~~~~~~~~~~\n\nA dict-like mapping of the tags for the instance (documented below).\nThis requires you to `explicitly enable the feature <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS>`__ for the instance.\nIf the feature is not enabled, accessing this attribute raises an error.\n\n(It also seems that there is a bug where if the feature is enabled and then disabled, the metadata service returns an empty response.\nThis is indistinguishable from \u201cno tags\u201d, so beware that in that case, ``InstanceTags`` will just look like an empty mapping.)\n\n``user_data: bytes | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe raw user data assigned to the instance (not base64 encoded), or ``None`` if\nthere is none.\n\n``InstanceTags``\n----------------\n\nA dict-like mapping of tag names to values (both ``str``\\s).\nTo avoid unnecessary requests, the mapping is lazy: values are only fetched when required.\n(Names are known on construction though, from the first request in ``EC2Metadata.tags``.)\n\nThe metadata service will receive tag updates on some instance types, as per `the AWS documentation <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#work-with-tags-in-IMDS>`__:\n\n If you add or remove an instance tag, the instance metadata is updated while the instance is running for instances built on the Nitro System, without needing to stop and then start the instance.\n For all other instances, to update the tags in the instance metadata, you must stop and then start the instance.\n\nBecause ``InstanceTags`` is cached, it won\u2019t reflect such updates on Nitro instances unless you clear it first:\n\n.. code-block:: python\n\n del ec2_metadata.tags\n ec2_metadata.tags[\"Name\"] # fresh\n\n``NetworkInterface``\n--------------------\n\nRepresents a single network interface, as retrieved from\n``EC2Metadata.network_interfaces``. Again like ``EC2Metadata`` all its\nattributes cache on first access, and can be cleared with ``del`` or\nits ``clear_all()`` method.\n\n``device_number: int``\n~~~~~~~~~~~~~~~~~~~~~~\n\nThe unique device number associated with that interface, e.g. ``0``.\n\n``interface_id: str``\n~~~~~~~~~~~~~~~~~~~~~\n\nThe unique id used to identify the Elastic Network Interface, e.g. ``'eni-12345'``.\n\n``ipv4_associations: dict[str, list[str]]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA dictionary mapping public IP addresses on the interface to the list of\nprivate IP addresses associated with that public IP, for each public IP that is\nassociated with the interface, e.g. ``{'54.0.0.1': ['172.30.0.0']}``.\n\n``ipv6s: list[str]``\n~~~~~~~~~~~~~~~~~~~~\n\nThe IPv6 addresses associated with the interface, e.g.\n``['2001:db8:abcd:ef00::1234']``.\n\n``mac: str``\n~~~~~~~~~~~~\n\nThe MAC address of the interface, e.g. ``'01:23:45:67:89:ab'``.\n\n``owner_id: str``\n~~~~~~~~~~~~~~~~~\n\nThe AWS Account ID of the owner of the network interface, e.g.\n``'123456789012'``.\n\n``private_hostname: str``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe interface's local/private hostname, e.g.\n``'ip-172-30-0-0.eu-west-1.compute.internal'``.\n\n``private_ipv4s: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe private IPv4 addresses associated with the interface, e.g.\n``['172.30.0.0']``.\n\n``public_hostname: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe interface's public DNS (IPv4), e.g.\n``'ec2-54-0-0-0.compute-1.amazonaws.com'``.\n\n``public_ipv4s: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Elastic IP addresses associated with the interface, e.g. ``['54.0.0.0']``.\n\n``security_groups: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe names of the security groups to which the network interface belongs, e.g.\n``['ssh-access', 'custom-sg-1']``.\n\n``security_group_ids: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe names of the security groups to which the network interface belongs, e.g.\n``['sg-12345678', 'sg-12345679']``.\n\n``subnet_id: str``\n~~~~~~~~~~~~~~~~~~\n\nThe ID of the subnet in which the interface resides, e.g.\n``'subnet-12345678'``.\n\n``subnet_ipv4_cidr_block: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe IPv4 CIDR block of the subnet in which the interface resides, or ``None``\nif there is none, e.g. ``'172.30.0.0/24'``.\n\n``subnet_ipv6_cidr_blocks: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe list of IPv6 CIDR blocks of the subnet in which the interface resides, e.g.\n``['2001:db8:abcd:ef00::/64']``. If the subnet does not have any IPv6 CIDR\nblocks or the instance isn't in a VPC, the list will be empty, e.g. ``[]``.\n\n``vpc_id: str``\n~~~~~~~~~~~~~~~\n\nThe ID of the VPC in which the interface resides, e.g. ``'vpc-12345678'``.\n\n``vpc_ipv4_cidr_block: str | None``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe IPv4 CIDR block of the VPC, or ``None`` if the instance isn't in a VPC,\ne.g. ``'172.30.0.0/16'``.\n\n``vpc_ipv4_cidr_blocks: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe list of IPv4 CIDR blocks e.g. ``['172.30.0.0/16']``. If the interface\ndoesn\u2019t have any such CIDR blocks, the list will be empty.\n\n``vpc_ipv6_cidr_blocks: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe list of IPv6 CIDR blocks of the VPC in which the interface resides, e.g.\n``['2001:db8:abcd:ef00::/56']``. If the VPC does not have any IPv6 CIDR blocks\nor the instance isn't in a VPC, the list will be empty, e.g. ``[]``.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An easy interface to query the EC2 metadata API, with caching.",
"version": "2.13.0",
"project_urls": {
"Changelog": "https://github.com/adamchainz/ec2-metadata/blob/main/CHANGELOG.rst",
"Homepage": "https://github.com/adamchainz/ec2-metadata",
"Mastodon": "https://fosstodon.org/@adamchainz",
"Twitter": "https://twitter.com/adamchainz"
},
"split_keywords": [
"aws",
"ec2",
"metadata"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e5c4fcff71841f9258bb5e909c80e65614d4236e8060749ab819ee84fe55bb96",
"md5": "50d011e7f10db7be3ca790c7611386b3",
"sha256": "9615ec916a1a68b19a11f94b1c8e90c448b198ecbdbd938f822adf33e50595cd"
},
"downloads": -1,
"filename": "ec2_metadata-2.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50d011e7f10db7be3ca790c7611386b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10679,
"upload_time": "2023-07-10T12:45:29",
"upload_time_iso_8601": "2023-07-10T12:45:29.422485Z",
"url": "https://files.pythonhosted.org/packages/e5/c4/fcff71841f9258bb5e909c80e65614d4236e8060749ab819ee84fe55bb96/ec2_metadata-2.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fdb1a5768b216e8b847a5dadecc06ea7653b5f8395f1a0fca3b542bc15318afb",
"md5": "f0dff7189876f20e238d78bf6c468039",
"sha256": "2c02c8f724cfbbf7a25cbfe18e0034454f9ad9be2cfb44c4daef5af3db55b94a"
},
"downloads": -1,
"filename": "ec2_metadata-2.13.0.tar.gz",
"has_sig": false,
"md5_digest": "f0dff7189876f20e238d78bf6c468039",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17340,
"upload_time": "2023-07-10T12:45:32",
"upload_time_iso_8601": "2023-07-10T12:45:32.804714Z",
"url": "https://files.pythonhosted.org/packages/fd/b1/a5768b216e8b847a5dadecc06ea7653b5f8395f1a0fca3b542bc15318afb/ec2_metadata-2.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 12:45:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamchainz",
"github_project": "ec2-metadata",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "ec2-metadata"
}
JSON
