openstack/nova
Code Issues Proposed changes

Re-work the metadata service docs

Browse Source 
The metadata service docs were hard to find since they were nested
down in some nova-network admin guide docs, and they were a mix of
end user and admin deployment guide information.

This change splits out the end-user facing content into a user
guide and leaves the deployment-specific information in the admin
guide, and links are updated appropriately.

The admin guide portion also referenced some config options that no
longer exist, so those are also removed and vendordata_providers
is added with a link to the vendordata guide. The options themselves
are cleaned up for their current groups and linked to the config option
docs.

Change-Id: I66035366f3a7ca62ea12d6afa74d13db01ec9f8d
This commit is contained in:
Matt Riedemann 2018-03-06 15:42:41 -05:00
parent 01333a7f18
commit 43f91a87cb
5 changed files with 184 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
doc/source/admin/networking-nova.rst
View File

@ -306,156 +306,17 @@ command:
* - use_ipv6 = False
- (BoolOpt) Use IPv6
.. _metadata-service:
.. _metadata-service-deploy:
Metadata service
~~~~~~~~~~~~~~~~
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.
.. TODO: This should be moved into its own document once we add information
about integrating this with neutron rather than nova-network.
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
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'
This section provides deployment information about the metadata service. For
end-user information about the metadata service, see the
:doc:`user guide </user/metadata-service>`.
The metadata service is implemented by either the ``nova-api`` service or the
``nova-api-metadata`` service. Note that the ``nova-api-metadata`` service is
@ -488,6 +349,9 @@ The default Compute service settings assume that ``nova-network`` and
``metadata_host`` configuration option to the IP address of the host where
``nova-api`` is running.
.. TODO: Consider grouping the metadata options into the same [metadata]
group and then we can just link to that in the generated config option doc.
.. list-table:: Description of metadata configuration options
:header-rows: 2
@ -495,27 +359,29 @@ The default Compute service settings assume that ``nova-network`` and
- Description
* - [DEFAULT]
-
* - metadata_cache_expiration = 15
* - :oslo.config:option:`metadata_host` = $my_ip
- (StrOpt) The IP address for the metadata API server
* - :oslo.config:option:`metadata_listen` = 0.0.0.0
- (StrOpt) The IP address on which the metadata API will listen.
* - :oslo.config:option:`metadata_listen_port` = 8775
- (IntOpt) The port on which the metadata API will listen.
* - :oslo.config:option:`metadata_port` = 8775
- (IntOpt) The port for the metadata API port
* - :oslo.config:option:`metadata_workers` = None
- (IntOpt) Number of workers for metadata service. The default will be
the number of CPUs available.
* - **[api]**
-
* - :oslo.config:option:`metadata_cache_expiration <api.metadata_cache_expiration>` = 15
- (IntOpt) Time in seconds to cache metadata; 0 to disable metadata
caching entirely (not recommended). Increasing this should improve
response times of the metadata API when under heavy load. Higher values
may increase memory usage and result in longer times for host metadata
changes to take effect.
* - metadata_host = $my_ip
- (StrOpt) The IP address for the metadata API server
* - metadata_listen = 0.0.0.0
- (StrOpt) The IP address on which the metadata API will listen.
* - metadata_listen_port = 8775
- (IntOpt) The port on which the metadata API will listen.
* - metadata_manager = nova.api.manager.MetadataManager
- (StrOpt) OpenStack metadata service manager
* - metadata_port = 8775
- (IntOpt) The port for the metadata API port
* - metadata_workers = None
- (IntOpt) Number of workers for metadata service. The default will be the number of CPUs available.
* - vendordata_driver = nova.api.metadata.vendordata_json.JsonFileVendorData
- (StrOpt) Driver to use for vendor data
* - vendordata_jsonfile_path = None
* - :oslo.config:option:`vendordata_providers <api.vendordata_providers>` = StaticJSON
- (ListOpt) A list of vendordata providers. See
:doc:`Vendordata </user/vendordata>` for more information.
* - :oslo.config:option:`vendordata_jsonfile_path <api.vendordata_jsonfile_path>` = None
- (StrOpt) File to load JSON formatted vendor data from
Enable ping and SSH on VMs

2
doc/source/install/get-started-compute.rst
View File

@ -25,7 +25,7 @@ OpenStack Compute consists of the following areas and their components:
``nova-api-metadata`` service
Accepts metadata requests from instances. The ``nova-api-metadata`` service
is generally used when you run in multi-host mode with ``nova-network``
installations. For details, see :ref:`metadata-service`
installations. For details, see :ref:`metadata-service-deploy`
in the Compute Administrator Guide.
``nova-compute`` service

2
doc/source/user/config-drive.rst
View File

@ -4,7 +4,7 @@ Store metadata on a configuration drive
You can configure OpenStack to write metadata to a special configuration drive
that attaches to the instance when it boots. The instance can mount this drive
and read files from it to get information that is normally available through
the :ref:`metadata service <metadata-service>`.
the :doc:`metadata service </user/metadata-service>`.
This metadata is different from the user data.
One use case for using the configuration drive is to pass a networking

2
doc/source/user/index.rst
View File

@ -9,6 +9,8 @@ End user guide
:maxdepth: 1
launch-instances
config-drive
metadata-service
.. todo:: The rest of this document should probably move to the admin guide.

153
doc/source/user/metadata-service.rst Normal file
View File

@ -0,0 +1,153 @@
================
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
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'