openstack/nova
Code Issues Proposed changes
52cc4bfa0a
nova/doc/source/admin/metadata-service.rst
Stephen Finucane 92a432fde7 docs: Rework all things metadata'y 
Turns out we've a *lot* of disparate metadata systems. Attempt to both
link them somewhat through extensive cross-referencing and extract out
deployment-specific stuff from user-facing docs. Lots of changes here,
but in summary:

- Split out admin-focused content from the metadata API, config drive,
  user data and vendordata docs.

- Merge the config drive, metadata service, vendordata and user-data
  user docs, which are mostly talking about the same thing and are
  fairly barren without the deployment components

- Make use of various oslo.config and Sphinx roles

Side note: I miss when we have tech writers to do this stuff for us :(

Change-Id: I4fb2b628bd93358a752e2397ae353221758e2984
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
2019-06-20 18:22:34 +01:00

6.8 KiB
Raw Blame History

Metadata service

Note

This section provides deployment information about the metadata service. For end-user information about the metadata service and instance metadata in general, refer to the user guide <metadata-service>.

Note

This section provides deployment information about the metadata service using neutron. This functions very differently when deployed with the deprecated nova-network service.

For information about deploying the metadata service with the nova-network service, refer to the nova-network documentation <metadata-service-deploy>

The metadata service provides a way for 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 - and also exposes vendordata and user data. Both the OpenStack metadata and EC2-compatible APIs are versioned by date.

The metadata service can be run globally, as part of the nova-api application, or on a per-cell basis, as part of the standalone nova-api-metadata application. A detailed comparison is provided in the cells V2 guide <cells-v2-layout-metadata-api>.

19.0.0

The ability to run the nova metadata API service on a per-cell basis was added in Stein. For versions prior to this release, you should not use the standalone nova-api-metadata application for multiple cells.

Guests access the service at 169.254.169.254. The networking service, neutron, is responsible for intercepting these requests and adding HTTP headers which uniquely identify the source of the request before forwarding it to the metadata API server. For the Open vSwitch and Linux Bridge backends provided with neutron, the flow looks something like so:

  1. Instance sends a HTTP request for metadata to 169.254.169.254.
  2. This request either hits the router or DHCP namespace depending on the route in the instance
  3. The metadata proxy service in the namespace adds the following info to the request:
    • Instance IP (X-Forwarded-For header)
    • Router or Network-ID (X-Neutron-Network-Id or X-Neutron-Router-Id header)
  4. The metadata proxy service sends this request to the metadata agent (outside the namespace) via a UNIX domain socket.
  5. The neutron-metadata-agent application forwards the request to the nova metadata API service by adding some new headers (instance ID and Tenant ID) to the request.

This flow may vary if a different networking backend is used.

Neutron and nova must be configured to communicate together with a shared secret. Neutron uses this secret to sign the Instance-ID header of the metadata request to prevent spoofing. This secret is configured through the :oslo.configneutron.metadata_proxy_shared_secret config option in nova and the equivalent metadata_proxy_shared_secret config option in neutron.

Configuration

The nova-api application accepts the following metadata service-related options:

  • :oslo.configenabled_apis
  • :oslo.configenabled_ssl_apis
  • :oslo.configneutron.service_metadata_proxy
  • :oslo.configneutron.metadata_proxy_shared_secret
  • :oslo.configapi.metadata_cache_expiration
  • :oslo.configapi.use_forwarded_for
  • :oslo.configapi.local_metadata_per_cell
  • :oslo.configapi.dhcp_domain

Note

This list excludes configuration options related to the vendordata feature. Refer to vendordata feature documentation </admin/vendordata> for information on configuring this.

For example, to configure the nova-api application to serve the metadata API, without SSL, using the StaticJSON vendordata provider, add the following to a nova-api.conf file:

[DEFAULT]
enabled_apis = osapi_compute,metadata
enabled_ssl_apis =
metadata_listen = 0.0.0.0
metadata_listen_port = 0
metadata_workers = 4

[neutron]
service_metadata_proxy = True

[api]
dhcp_domain =
metadata_cache_expiration = 15
use_forwarded_for = False
local_metadata_per_cell = False
vendordata_providers = StaticJSON
vendordata_jsonfile_path = /etc/nova/vendor_data.json

Note

This does not include configuration options that are not metadata-specific but are nonetheless required, such as :oslo.configapi.auth_strategy.

Configuring the application to use the DynamicJSON vendordata provider is more involved and is not covered here.

The nova-api-metadata application accepts almost the same options:

  • :oslo.configneutron.service_metadata_proxy
  • :oslo.configneutron.metadata_proxy_shared_secret
  • :oslo.configapi.metadata_cache_expiration
  • :oslo.configapi.use_forwarded_for
  • :oslo.configapi.local_metadata_per_cell
  • :oslo.configapi.dhcp_domain

Note

This list excludes configuration options related to the vendordata feature. Refer to vendordata feature documentation </admin/vendordata> for information on configuring this.

For example, to configure the nova-api-metadata application to serve the metadata API, without SSL, add the following to a nova-api.conf file:

[DEFAULT]
metadata_listen = 0.0.0.0
metadata_listen_port = 0
metadata_workers = 4

[neutron]
service_metadata_proxy = True

[api]
dhcp_domain =
metadata_cache_expiration = 15
use_forwarded_for = False
local_metadata_per_cell = False

Note

This does not include configuration options that are not metadata-specific but are nonetheless required, such as :oslo.configapi.auth_strategy.

For information about configuring the neutron side of the metadata service, refer to the neutron configuration guide <configuration/metadata-agent.html>

Config drives

Config drives are special drives that are attached to an instance when it boots. The instance can mount this drive and read files from it to get information that is normally available through the metadata service. For more information, refer to /admin/config-drive and the user guide <metadata-config-drive>.

Vendordata

Vendordata provides a way to pass vendor or deployment-specific information to instances. For more information, refer to /admin/vendordata and the user guide <metadata-vendordata>.

User data

User data is a blob of data that the user can specify when they launch an instance. For more information, refer to the user guide <metadata-userdata>.