================
Metadata service
================

This document provides end user information about the metadata service. For
deployment information about the metadata service, see the
:ref:`admin guide <metadata-service-deploy>`.

Compute uses a metadata service for virtual machine instances to retrieve
instance-specific data. Instances access the metadata service at
``http://169.254.169.254``. The metadata service supports two sets of APIs: an
OpenStack metadata API and an EC2-compatible API. Both APIs are versioned by
date.

To retrieve a list of supported versions for the OpenStack metadata API, make a
GET request to ``http://169.254.169.254/openstack``:

.. code-block:: console

   $ curl http://169.254.169.254/openstack
   2012-08-10
   2013-04-04
   2013-10-17
   2015-10-15
   2016-06-30
   2016-10-06
   2017-02-22
   2018-08-27
   latest

To list supported versions for the EC2-compatible metadata API, make a GET
request to ``http://169.254.169.254``:

.. code-block:: console

   $ curl http://169.254.169.254
   1.0
   2007-01-19
   2007-03-01
   2007-08-29
   2007-10-10
   2007-12-15
   2008-02-01
   2008-09-01
   2009-04-04
   latest

If you write a consumer for one of these APIs, always attempt to access the
most recent API version supported by your consumer first, then fall back to an
earlier version if the most recent one is not available.

Metadata from the OpenStack API is distributed in JSON format. To retrieve the
metadata, make a GET request to
``http://169.254.169.254/openstack/2012-08-10/meta_data.json``:

.. code-block:: console

   $ curl http://169.254.169.254/openstack/2012-08-10/meta_data.json

.. code-block:: json

   {
      "uuid": "d8e02d56-2648-49a3-bf97-6be8f1204f38",
      "availability_zone": "nova",
      "hostname": "test.novalocal",
      "launch_index": 0,
      "meta": {
         "priority": "low",
         "role": "webserver"
      },
      "project_id": "f7ac731cc11f40efbc03a9f9e1d1d21f",
      "public_keys": {
          "mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKV\
                    VRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTH\
                    bsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCe\
                    uMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova\n"
      },
      "name": "test"
   }

Instances also retrieve user data (passed as the ``user_data`` parameter in the
API call or by the ``--user_data`` flag in the :command:`openstack server
create` command) through the metadata service, by making a GET request to
``http://169.254.169.254/openstack/2012-08-10/user_data``:

.. code-block:: console

   $ curl http://169.254.169.254/openstack/2012-08-10/user_data
   #!/bin/bash
   echo 'Extra user data here'

The metadata service has an API that is compatible with version 2009-04-04 of
the `Amazon EC2 metadata service
<http://docs.amazonwebservices.com/AWSEC2/2009-04-04/UserGuide/AESDG-chapter-instancedata.html>`__.
This means that virtual machine images designed for EC2 will work properly with
OpenStack.

The EC2 API exposes a separate URL for each metadata element. Retrieve a
listing of these elements by making a GET query to
``http://169.254.169.254/2009-04-04/meta-data/``:

.. code-block:: console

   $ curl http://169.254.169.254/2009-04-04/meta-data/
   ami-id
   ami-launch-index
   ami-manifest-path
   block-device-mapping/
   hostname
   instance-action
   instance-id
   instance-type
   kernel-id
   local-hostname
   local-ipv4
   placement/
   public-hostname
   public-ipv4
   public-keys/
   ramdisk-id
   reservation-id
   security-groups

.. code-block:: console

   $ curl http://169.254.169.254/2009-04-04/meta-data/block-device-mapping/
   ami

.. code-block:: console

   $ curl http://169.254.169.254/2009-04-04/meta-data/placement/
   availability-zone

.. code-block:: console

   $ curl http://169.254.169.254/2009-04-04/meta-data/public-keys/
   0=mykey

Instances can retrieve the public SSH key (identified by keypair name when a
user requests a new instance) by making a GET request to
``http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key``:

.. code-block:: console

   $ curl http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key
   ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+US\
   LGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3B\
   ISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated\
   by Nova

Instances can retrieve user data by making a GET request to
``http://169.254.169.254/2009-04-04/user-data``:

.. code-block:: console

   $ curl http://169.254.169.254/2009-04-04/user-data
   #!/bin/bash
   echo 'Extra user data here'