Merge "docs: Rework all things metadata'y"
This commit is contained in:
commit
68b2ec6fda
|
@ -1040,10 +1040,11 @@ Configure Guest OS
|
||||||
|
|
||||||
Metadata API
|
Metadata API
|
||||||
------------
|
------------
|
||||||
Nova provides a metadata api for servers to retrieve server specific metadata.
|
|
||||||
Neutron ensures this metadata api can be accessed through a predefined ip
|
Nova provides a metadata API for servers to retrieve server specific metadata.
|
||||||
address (169.254.169.254). For more details, see :nova-doc:`Metadata Service
|
Neutron ensures this metadata API can be accessed through a predefined IP
|
||||||
<user/metadata-service.html>`.
|
address, ``169.254.169.254``. For more details, refer to the :nova-doc:`user
|
||||||
|
guide <user/metadata.html>`.
|
||||||
|
|
||||||
Config Drive
|
Config Drive
|
||||||
------------
|
------------
|
||||||
|
@ -1051,20 +1052,19 @@ Config Drive
|
||||||
Nova is able to write metadata to a special configuration drive that attaches
|
Nova is able to write metadata to a special configuration drive that attaches
|
||||||
to the server when it boots. The server can mount this drive and read files
|
to the server when it boots. The server can mount this drive and read files
|
||||||
from it to get information that is normally available through the metadata
|
from it to get information that is normally available through the metadata
|
||||||
service. For more details, see :nova-doc:`Config Drive
|
service. For more details, refer to the :nova-doc:`user guide
|
||||||
<user/config-drive.html>`.
|
<user/metadata.html>`.
|
||||||
|
|
||||||
User data
|
User data
|
||||||
---------
|
---------
|
||||||
|
|
||||||
A user data file is a special key in the metadata service that holds a file
|
A user data file is a special key in the metadata service that holds a file
|
||||||
that cloud-aware applications in the server can access.
|
that cloud-aware applications in the server can access.
|
||||||
|
|
||||||
Nova has two ways to send user data to the deployed server, one is by
|
This information can be accessed via the metadata API or a config drive. The
|
||||||
metadata service to let server able to access to its metadata through
|
latter allows the deployed server to consume it by active engines such as
|
||||||
a predefined ip address (169.254.169.254), then other way is to use config
|
cloud-init during its boot process, where network connectivity may not be an
|
||||||
drive which will wrap metadata into a iso9660 or vfat format disk so that
|
option.
|
||||||
the deployed server can consume it by active engines such as cloud-init
|
|
||||||
during its boot process.
|
|
||||||
|
|
||||||
Server personality
|
Server personality
|
||||||
------------------
|
------------------
|
||||||
|
|
|
@ -1,10 +1,3 @@
|
||||||
# The following is generated with:
|
|
||||||
#
|
|
||||||
# git log --follow --name-status --format='%H' 2d0dfc632f.. -- doc/source | \
|
|
||||||
# grep ^R | grep .rst | cut -f2- | \
|
|
||||||
# sed -e 's|doc/source/|redirectmatch 301 ^/nova/([^/]+)/|' -e 's|doc/source/|/nova/$1/|' -e 's/.rst/.html$/' -e 's/.rst/.html/' | \
|
|
||||||
# sort
|
|
||||||
|
|
||||||
redirectmatch 301 ^/nova/([^/]+)/addmethod.openstackapi.html$ /nova/$1/contributor/api-2.html
|
redirectmatch 301 ^/nova/([^/]+)/addmethod.openstackapi.html$ /nova/$1/contributor/api-2.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/admin/flavors2.html$ /nova/$1/admin/flavors.html
|
redirectmatch 301 ^/nova/([^/]+)/admin/flavors2.html$ /nova/$1/admin/flavors.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/admin/numa.html$ /nova/$1/admin/cpu-topologies.html
|
redirectmatch 301 ^/nova/([^/]+)/admin/numa.html$ /nova/$1/admin/cpu-topologies.html
|
||||||
|
@ -71,8 +64,12 @@ redirectmatch 301 ^/nova/([^/]+)/testing/serial-console.html$ /nova/$1/contribut
|
||||||
redirectmatch 301 ^/nova/([^/]+)/testing/zero-downtime-upgrade.html$ /nova/$1/contributor/testing/zero-downtime-upgrade.html
|
redirectmatch 301 ^/nova/([^/]+)/testing/zero-downtime-upgrade.html$ /nova/$1/contributor/testing/zero-downtime-upgrade.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/threading.html$ /nova/$1/reference/threading.html
|
redirectmatch 301 ^/nova/([^/]+)/threading.html$ /nova/$1/reference/threading.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/upgrade.html$ /nova/$1/user/upgrade.html
|
redirectmatch 301 ^/nova/([^/]+)/upgrade.html$ /nova/$1/user/upgrade.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/vendordata.html$ /nova/$1/user/vendordata.html
|
redirectmatch 301 ^/nova/([^/]+)/user/cellsv2_layout.html$ /nova/$1/user/cellsv2-layout.html
|
||||||
|
redirectmatch 301 ^/nova/([^/]+)/user/config-drive.html$ /nova/$1/user/metadata.html
|
||||||
|
redirectmatch 301 ^/nova/([^/]+)/user/metadata-service.html$ /nova/$1/user/metadata.html
|
||||||
|
redirectmatch 301 ^/nova/([^/]+)/user/placement.html$ /placement/$1/
|
||||||
|
redirectmatch 301 ^/nova/([^/]+)/user/user-data.html$ /nova/$1/user/metadata.html
|
||||||
|
redirectmatch 301 ^/nova/([^/]+)/user/vendordata.html$ /nova/$1/user/metadata.html
|
||||||
|
redirectmatch 301 ^/nova/([^/]+)/vendordata.html$ /nova/$1/user/metadata.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/vmstates.html$ /nova/$1/reference/vm-states.html
|
redirectmatch 301 ^/nova/([^/]+)/vmstates.html$ /nova/$1/reference/vm-states.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/wsgi.html$ /nova/$1/user/wsgi.html
|
redirectmatch 301 ^/nova/([^/]+)/wsgi.html$ /nova/$1/user/wsgi.html
|
||||||
redirectmatch 301 ^/nova/([^/]+)/user/cellsv2_layout.html$ /nova/$1/user/cellsv2-layout.html
|
|
||||||
redirectmatch 301 ^/nova/latest/user/placement.html$ /placement/latest/
|
|
||||||
|
|
|
@ -0,0 +1,115 @@
|
||||||
|
=============
|
||||||
|
Config drives
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This section provides deployment information about the config drive feature.
|
||||||
|
For end-user information about the config drive feature and instance metadata
|
||||||
|
in general, refer to the :doc:`user guide </user/metadata>`.
|
||||||
|
|
||||||
|
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 :doc:`the metadata service
|
||||||
|
</admin/metadata-service>`.
|
||||||
|
|
||||||
|
There are many use cases for the config drive. One such use case is to pass a
|
||||||
|
networking configuration when you do not use DHCP to assign IP addresses to
|
||||||
|
instances. For example, you might pass the IP address configuration for the
|
||||||
|
instance through the config drive, which the instance can mount and access
|
||||||
|
before you configure the network settings for the instance. Another common
|
||||||
|
reason to use config drives is load. If running something like the OpenStack
|
||||||
|
puppet providers in your instances, they can hit the :doc:`metadata servers
|
||||||
|
</admin/metadata-service>` every fifteen minutes, simultaneously for every
|
||||||
|
instance you have. They are just checking in, and building facts, but it's not
|
||||||
|
insignificant load. With a config drive, that becomes a local (cached) disk
|
||||||
|
read. Finally, using a config drive means you're not dependent on the metadata
|
||||||
|
service being up, reachable, or performing well to do things like reboot your
|
||||||
|
instance that runs `cloud-init`_ at the beginning.
|
||||||
|
|
||||||
|
Any modern guest operating system that is capable of mounting an ISO 9660 or
|
||||||
|
VFAT file system can use the config drive.
|
||||||
|
|
||||||
|
|
||||||
|
Requirements and guidelines
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
To use the config drive, you must follow the following requirements for the
|
||||||
|
compute host and image.
|
||||||
|
|
||||||
|
.. rubric:: Compute host requirements
|
||||||
|
|
||||||
|
The following virt drivers support the config drive: libvirt, XenServer,
|
||||||
|
Hyper-V, VMware, and (since 17.0.0 Queens) PowerVM. The Bare Metal service also
|
||||||
|
supports the config drive.
|
||||||
|
|
||||||
|
- To use config drives with libvirt, XenServer, or VMware, you must first
|
||||||
|
install the :command:`genisoimage` package on each compute host. Use the
|
||||||
|
:oslo.config:option:`mkisofs_cmd` config option to set the path where you
|
||||||
|
install the :command:`genisoimage` program. If :command:`genisoimage` is in
|
||||||
|
the same path as the :program:`nova-compute` service, you do not need to set
|
||||||
|
this flag.
|
||||||
|
|
||||||
|
- To use config drives with Hyper-V, you must set the
|
||||||
|
:oslo.config:option:`mkisofs_cmd` config option to the full path to an
|
||||||
|
:command:`mkisofs.exe` installation. Additionally, you must set the
|
||||||
|
:oslo.config:option:`hyperv.qemu_img_cmd` config option to the full path to an
|
||||||
|
:command:`qemu-img` command installation.
|
||||||
|
|
||||||
|
- To use config drives with PowerVM or the Bare Metal service, you do not need
|
||||||
|
to prepare anything.
|
||||||
|
|
||||||
|
.. rubric:: Image requirements
|
||||||
|
|
||||||
|
An image built with a recent version of the `cloud-init`_ package can
|
||||||
|
automatically access metadata passed through the config drive. The cloud-init
|
||||||
|
package version 0.7.1 works with Ubuntu, Fedora based images (such as Red Hat
|
||||||
|
Enterprise Linux) and openSUSE based images (such as SUSE Linux Enterprise
|
||||||
|
Server). If an image does not have the cloud-init package installed, you must
|
||||||
|
customize the image to run a script that mounts the config drive on boot, reads
|
||||||
|
the data from the drive, and takes appropriate action such as adding the public
|
||||||
|
key to an account. For more details about how data is organized on the config
|
||||||
|
drive, refer to the :ref:`user guide <metadata-config-drive>`.
|
||||||
|
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
-------------
|
||||||
|
|
||||||
|
The :program:`nova-compute` service accepts the following config drive-related
|
||||||
|
options:
|
||||||
|
|
||||||
|
- :oslo.config:option:`api.config_drive_skip_versions`
|
||||||
|
- :oslo.config:option:`force_config_drive`
|
||||||
|
- :oslo.config:option:`config_drive_format`
|
||||||
|
|
||||||
|
If using the HyperV compute driver, the following additional options are
|
||||||
|
supported:
|
||||||
|
|
||||||
|
- :oslo.config:option:`hyperv.config_drive_cdrom`
|
||||||
|
|
||||||
|
For example, to ensure nova always provides a config drive to instances but
|
||||||
|
versions ``2018-08-27`` (Rocky) and ``2017-02-22`` (Ocata) are skipped, add the
|
||||||
|
following to :file:`nova.conf`:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[DEFAULT]
|
||||||
|
force_config_drive = True
|
||||||
|
|
||||||
|
[api]
|
||||||
|
config_drive_skip_versions = 2018-08-27 2017-02-22
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The ``img_config_drive`` image metadata property can be used to force enable
|
||||||
|
the config drive. In addition, users can explicitly request a config drive
|
||||||
|
when booting instances. For more information, refer to the :ref:`user guide
|
||||||
|
<metadata-config-drive>`.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
If using Xen with a config drive, you must use the
|
||||||
|
:oslo.config:option:`xenserver.disable_agent` config option to disable the
|
||||||
|
agent.
|
||||||
|
|
||||||
|
.. _cloud-init: https://cloudinit.readthedocs.io/en/latest/
|
|
@ -23,6 +23,7 @@ operating system, and exposes functionality over a web-based API.
|
||||||
arch.rst
|
arch.rst
|
||||||
availability-zones.rst
|
availability-zones.rst
|
||||||
cells.rst
|
cells.rst
|
||||||
|
config-drive.rst
|
||||||
configuration/index.rst
|
configuration/index.rst
|
||||||
configuring-migrations.rst
|
configuring-migrations.rst
|
||||||
cpu-topologies.rst
|
cpu-topologies.rst
|
||||||
|
@ -35,6 +36,7 @@ operating system, and exposes functionality over a web-based API.
|
||||||
manage-the-cloud.rst
|
manage-the-cloud.rst
|
||||||
manage-users.rst
|
manage-users.rst
|
||||||
manage-volumes.rst
|
manage-volumes.rst
|
||||||
|
metadata-service.rst
|
||||||
migration.rst
|
migration.rst
|
||||||
migrate-instance-with-snapshot.rst
|
migrate-instance-with-snapshot.rst
|
||||||
networking-nova.rst
|
networking-nova.rst
|
||||||
|
@ -54,3 +56,4 @@ operating system, and exposes functionality over a web-based API.
|
||||||
system-admin.rst
|
system-admin.rst
|
||||||
secure-live-migration-with-qemu-native-tls.rst
|
secure-live-migration-with-qemu-native-tls.rst
|
||||||
mitigation-for-Intel-MDS-security-flaws.rst
|
mitigation-for-Intel-MDS-security-flaws.rst
|
||||||
|
vendordata.rst
|
||||||
|
|
|
@ -0,0 +1,193 @@
|
||||||
|
================
|
||||||
|
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 :ref:`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
|
||||||
|
:program:`nova-network` service.
|
||||||
|
|
||||||
|
For information about deploying the metadata service with the
|
||||||
|
:program:`nova-network` service, refer to the :ref:`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 :program:`nova-api`
|
||||||
|
application, or on a per-cell basis, as part of the standalone
|
||||||
|
:program:`nova-api-metadata` application. A detailed comparison is provided in
|
||||||
|
the :ref:`cells V2 guide <cells-v2-layout-metadata-api>`.
|
||||||
|
|
||||||
|
.. versionchanged:: 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 :program:`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:
|
||||||
|
|
||||||
|
#. Instance sends a HTTP request for metadata to ``169.254.169.254``.
|
||||||
|
|
||||||
|
#. This request either hits the router or DHCP namespace depending on the route
|
||||||
|
in the instance
|
||||||
|
|
||||||
|
#. 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)
|
||||||
|
|
||||||
|
#. The metadata proxy service sends this request to the metadata agent (outside
|
||||||
|
the namespace) via a UNIX domain socket.
|
||||||
|
|
||||||
|
#. The :program:`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.config:option:`neutron.metadata_proxy_shared_secret` config option in nova
|
||||||
|
and the equivalent ``metadata_proxy_shared_secret`` config option in neutron.
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
-------------
|
||||||
|
|
||||||
|
The :program:`nova-api` application accepts the following metadata
|
||||||
|
service-related options:
|
||||||
|
|
||||||
|
- :oslo.config:option:`enabled_apis`
|
||||||
|
- :oslo.config:option:`enabled_ssl_apis`
|
||||||
|
- :oslo.config:option:`neutron.service_metadata_proxy`
|
||||||
|
- :oslo.config:option:`neutron.metadata_proxy_shared_secret`
|
||||||
|
- :oslo.config:option:`api.metadata_cache_expiration`
|
||||||
|
- :oslo.config:option:`api.use_forwarded_for`
|
||||||
|
- :oslo.config:option:`api.local_metadata_per_cell`
|
||||||
|
- :oslo.config:option:`api.dhcp_domain`
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This list excludes configuration options related to the vendordata feature.
|
||||||
|
Refer to :doc:`vendordata feature documentation </admin/vendordata>` for
|
||||||
|
information on configuring this.
|
||||||
|
|
||||||
|
For example, to configure the :program:`nova-api` application to serve the
|
||||||
|
metadata API, without SSL, using the ``StaticJSON`` vendordata provider, add the
|
||||||
|
following to a :file:`nova-api.conf` file:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[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.config:option:`api.auth_strategy`.
|
||||||
|
|
||||||
|
Configuring the application to use the ``DynamicJSON`` vendordata provider is
|
||||||
|
more involved and is not covered here.
|
||||||
|
|
||||||
|
The :program:`nova-api-metadata` application accepts almost the same options:
|
||||||
|
|
||||||
|
- :oslo.config:option:`neutron.service_metadata_proxy`
|
||||||
|
- :oslo.config:option:`neutron.metadata_proxy_shared_secret`
|
||||||
|
- :oslo.config:option:`api.metadata_cache_expiration`
|
||||||
|
- :oslo.config:option:`api.use_forwarded_for`
|
||||||
|
- :oslo.config:option:`api.local_metadata_per_cell`
|
||||||
|
- :oslo.config:option:`api.dhcp_domain`
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This list excludes configuration options related to the vendordata feature.
|
||||||
|
Refer to :doc:`vendordata feature documentation </admin/vendordata>` for
|
||||||
|
information on configuring this.
|
||||||
|
|
||||||
|
For example, to configure the :program:`nova-api-metadata` application to serve
|
||||||
|
the metadata API, without SSL, add the following to a :file:`nova-api.conf`
|
||||||
|
file:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[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.config:option:`api.auth_strategy`.
|
||||||
|
|
||||||
|
For information about configuring the neutron side of the metadata service,
|
||||||
|
refer to the :neutron-doc:`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 :doc:`/admin/config-drive` and the :ref:`user guide <metadata-config-drive>`.
|
||||||
|
|
||||||
|
|
||||||
|
Vendordata
|
||||||
|
----------
|
||||||
|
|
||||||
|
Vendordata provides a way to pass vendor or deployment-specific information to
|
||||||
|
instances. For more information, refer to :doc:`/admin/vendordata` and the
|
||||||
|
:ref:`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 :ref:`the user guide
|
||||||
|
<metadata-userdata>`.
|
|
@ -311,12 +311,16 @@ command:
|
||||||
Metadata service
|
Metadata service
|
||||||
~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
.. TODO: This should be moved into its own document once we add information
|
.. note::
|
||||||
about integrating this with neutron rather than nova-network.
|
|
||||||
|
|
||||||
This section provides deployment information about the metadata service. For
|
This section provides deployment information about the metadata service
|
||||||
end-user information about the metadata service, see the
|
using the deprecated :program:`nova-network` service.
|
||||||
:doc:`user guide </user/metadata-service>`.
|
|
||||||
|
For information about deploying the metadata service with neutron, refer to
|
||||||
|
the :doc:`metadata service documentation </admin/metadata-service>`.
|
||||||
|
|
||||||
|
For end-user information about the metadata service and instance metadata in
|
||||||
|
general, refer to the :doc:`user guide </user/metadata>`.
|
||||||
|
|
||||||
The metadata service is implemented by either the ``nova-api`` service or the
|
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
|
``nova-api-metadata`` service. Note that the ``nova-api-metadata`` service is
|
||||||
|
@ -349,9 +353,6 @@ The default Compute service settings assume that ``nova-network`` and
|
||||||
``metadata_host`` configuration option to the IP address of the host where
|
``metadata_host`` configuration option to the IP address of the host where
|
||||||
``nova-api`` is running.
|
``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
|
.. list-table:: Description of metadata configuration options
|
||||||
:header-rows: 2
|
:header-rows: 2
|
||||||
|
|
||||||
|
@ -380,7 +381,7 @@ The default Compute service settings assume that ``nova-network`` and
|
||||||
changes to take effect.
|
changes to take effect.
|
||||||
* - :oslo.config:option:`vendordata_providers <api.vendordata_providers>` = StaticJSON
|
* - :oslo.config:option:`vendordata_providers <api.vendordata_providers>` = StaticJSON
|
||||||
- (ListOpt) A list of vendordata providers. See
|
- (ListOpt) A list of vendordata providers. See
|
||||||
:doc:`Vendordata </user/vendordata>` for more information.
|
:doc:`Vendordata </admin/vendordata>` for more information.
|
||||||
* - :oslo.config:option:`vendordata_jsonfile_path <api.vendordata_jsonfile_path>` = None
|
* - :oslo.config:option:`vendordata_jsonfile_path <api.vendordata_jsonfile_path>` = None
|
||||||
- (StrOpt) File to load JSON formatted vendor data from
|
- (StrOpt) File to load JSON formatted vendor data from
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,178 @@
|
||||||
|
==========
|
||||||
|
Vendordata
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This section provides deployment information about the vendordata feature.
|
||||||
|
For end-user information about the vendordata feature and instance metadata
|
||||||
|
in general, refer to the :doc:`user guide </user/metadata>`.
|
||||||
|
|
||||||
|
The *vendordata* feature provides a way to pass vendor or deployment-specific
|
||||||
|
information to instances. This can be accessed by users using :doc:`the metadata
|
||||||
|
service </admin/metadata-service>` or with :doc:`config drives
|
||||||
|
</admin/config-drive>`.
|
||||||
|
|
||||||
|
There are two vendordata modules provided with nova: ``StaticJSON`` and
|
||||||
|
``DynamicJSON``.
|
||||||
|
|
||||||
|
|
||||||
|
``StaticJSON``
|
||||||
|
--------------
|
||||||
|
|
||||||
|
The ``StaticJSON`` module includes the contents of a static JSON file loaded
|
||||||
|
from disk. This can be used for things which don't change between instances,
|
||||||
|
such as the location of the corporate puppet server. It is the default provider.
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The service you must configure to enable the ``StaticJSON`` vendordata module
|
||||||
|
depends on how guests are accessing vendordata. If using the metadata service,
|
||||||
|
configuration applies to either :program:`nova-api` or
|
||||||
|
:program:`nova-api-metadata`, depending on the deployment, while if using
|
||||||
|
config drives, configuration applies to :program:`nova-compute`. However,
|
||||||
|
configuration is otherwise the same and the following options apply:
|
||||||
|
|
||||||
|
- :oslo.config:option:`api.vendordata_providers`
|
||||||
|
- :oslo.config:option:`api.vendordata_jsonfile_path`
|
||||||
|
|
||||||
|
Refer to the :doc:`metadata service </admin/metadata-service>` and :doc:`config
|
||||||
|
drive </admin/config-drive>` documentation for more information on how to
|
||||||
|
configure the required services.
|
||||||
|
|
||||||
|
|
||||||
|
``DynamicJSON``
|
||||||
|
---------------
|
||||||
|
|
||||||
|
The ``DynamicJSON`` module can make a request to an external REST service to
|
||||||
|
determine what metadata to add to an instance. This is how we recommend you
|
||||||
|
generate things like Active Directory tokens which change per instance.
|
||||||
|
|
||||||
|
When used, the ``DynamicJSON`` module will make a request to any REST services
|
||||||
|
listed in the :oslo.config:option:`api.vendordata_dynamic_targets` configuration
|
||||||
|
option. There can be more than one of these but note that they will be queried
|
||||||
|
once per metadata request from the instance which can mean a lot of traffic
|
||||||
|
depending on your configuration and the configuration of the instance.
|
||||||
|
|
||||||
|
The following data is passed to your REST service as a JSON encoded POST:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Key
|
||||||
|
- Description
|
||||||
|
* - ``project-id``
|
||||||
|
- The ID of the project that owns this instance.
|
||||||
|
* - ``instance-id``
|
||||||
|
- The UUID of this instance.
|
||||||
|
* - ``image-id``
|
||||||
|
- The ID of the image used to boot this instance.
|
||||||
|
* - ``user-data``
|
||||||
|
- As specified by the user at boot time.
|
||||||
|
* - ``hostname``
|
||||||
|
- The hostname of the instance.
|
||||||
|
* - ``metadata``
|
||||||
|
- As specified by the user at boot time.
|
||||||
|
|
||||||
|
Metadata fetched from the REST service will appear in the metadata service at a
|
||||||
|
new file called ``vendordata2.json``, with a path (either in the metadata service
|
||||||
|
URL or in the config drive) like this::
|
||||||
|
|
||||||
|
openstack/latest/vendor_data2.json
|
||||||
|
|
||||||
|
For each dynamic target, there will be an entry in the JSON file named after
|
||||||
|
that target. For example:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"testing": {
|
||||||
|
"value1": 1,
|
||||||
|
"value2": 2,
|
||||||
|
"value3": "three"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
The `novajoin`__ project provides a dynamic vendordata service to manage host
|
||||||
|
instantiation in an IPA server.
|
||||||
|
|
||||||
|
__ https://github.com/openstack/novajoin
|
||||||
|
|
||||||
|
Deployment considerations
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Nova provides authentication to external metadata services in order to provide
|
||||||
|
some level of certainty that the request came from nova. This is done by
|
||||||
|
providing a service token with the request -- you can then just deploy your
|
||||||
|
metadata service with the keystone authentication WSGI middleware. This is
|
||||||
|
configured using the keystone authentication parameters in the
|
||||||
|
:oslo.config:group:`vendordata_dynamic_auth` configuration group.
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
As with ``StaticJSON``, the service you must configure to enable the
|
||||||
|
``DynamicJSON`` vendordata module depends on how guests are accessing
|
||||||
|
vendordata. If using the metadata service, configuration applies to either
|
||||||
|
:program:`nova-api` or :program:`nova-api-metadata`, depending on the
|
||||||
|
deployment, while if using configuration drives, configuration applies to
|
||||||
|
:program:`nova-compute`. However, configuration is otherwise the same and the
|
||||||
|
following options apply:
|
||||||
|
|
||||||
|
- :oslo.config:option:`api.vendordata_providers`
|
||||||
|
- :oslo.config:option:`api.vendordata_dynamic_ssl_certfile`
|
||||||
|
- :oslo.config:option:`api.vendordata_dynamic_connect_timeout`
|
||||||
|
- :oslo.config:option:`api.vendordata_dynamic_read_timeout`
|
||||||
|
- :oslo.config:option:`api.vendordata_dynamic_failure_fatal`
|
||||||
|
- :oslo.config:option:`api.vendordata_dynamic_targets`
|
||||||
|
|
||||||
|
Refer to the :doc:`metadata service </admin/metadata-service>` and :doc:`config
|
||||||
|
drive </admin/config-drive>` documentation for more information on how to
|
||||||
|
configure the required services.
|
||||||
|
|
||||||
|
In addition, there are also many options related to authentication. These are
|
||||||
|
provided by :keystone-doc:`keystone <>` but are listed below for completeness:
|
||||||
|
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.cafile`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.certfile`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.keyfile`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.insecure`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.timeout`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.collect_timing`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.split_loggers`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.auth_type`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.auth_section`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.auth_url`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.system_scope`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.domain_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.domain_name`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.project_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.project_name`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.project_domain_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.project_domain_name`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.trust_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.default_domain_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.default_domain_name`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.user_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.username`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.user_domain_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.user_domain_name`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.password`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.tenant_id`
|
||||||
|
- :oslo.config:option:`vendordata_dynamic_auth.tenant_name`
|
||||||
|
|
||||||
|
Refer to the :keystone-doc:`keystone documentation </configuration/index.html>`
|
||||||
|
for information on configuring these.
|
||||||
|
|
||||||
|
|
||||||
|
References
|
||||||
|
----------
|
||||||
|
|
||||||
|
* Michael Still's talk from the Queens summit in Sydney, `Metadata, User Data,
|
||||||
|
Vendor Data, oh my!`__
|
||||||
|
* Michael's blog post on `deploying a simple vendordata service`__ which
|
||||||
|
provides more details and sample code to supplement the documentation above.
|
||||||
|
|
||||||
|
__ https://www.openstack.org/videos/sydney-2017/metadata-user-data-vendor-data-oh-my
|
||||||
|
__ https://www.madebymikal.com/nova-vendordata-deployment-an-excessively-detailed-guide/
|
|
@ -84,8 +84,8 @@ resources will help you get started with consuming the API directly.
|
||||||
* :doc:`Block Device Mapping </user/block-device-mapping>`: One of the trickier
|
* :doc:`Block Device Mapping </user/block-device-mapping>`: One of the trickier
|
||||||
parts to understand is the Block Device Mapping parameters used to connect
|
parts to understand is the Block Device Mapping parameters used to connect
|
||||||
specific block devices to computes. This deserves its own deep dive.
|
specific block devices to computes. This deserves its own deep dive.
|
||||||
* :doc:`Configuration drive </user/config-drive>`: Provide information to the
|
* :doc:`Metadata </user/metadata>`: Provide information to the guest instance
|
||||||
guest instance when it is created.
|
when it is created.
|
||||||
|
|
||||||
Nova can be configured to emit notifications over RPC.
|
Nova can be configured to emit notifications over RPC.
|
||||||
|
|
||||||
|
@ -158,9 +158,10 @@ Once you are running nova, the following information is extremely useful.
|
||||||
configured, and how that will impact where compute instances land in your
|
configured, and how that will impact where compute instances land in your
|
||||||
environment. If you are seeing unexpected distribution of compute instances
|
environment. If you are seeing unexpected distribution of compute instances
|
||||||
in your hosts, you'll want to dive into this configuration.
|
in your hosts, you'll want to dive into this configuration.
|
||||||
* :doc:`Exposing custom metadata to compute instances </user/vendordata>`: How and
|
* :doc:`Exposing custom metadata to compute instances </admin/vendordata>`: How
|
||||||
when you might want to extend the basic metadata exposed to compute instances
|
and when you might want to extend the basic metadata exposed to compute
|
||||||
(either via metadata server or config drive) for your specific purposes.
|
instances (either via metadata server or config drive) for your specific
|
||||||
|
purposes.
|
||||||
|
|
||||||
Reference Material
|
Reference Material
|
||||||
------------------
|
------------------
|
||||||
|
@ -244,7 +245,6 @@ looking parts of our architecture. These are collected below.
|
||||||
user/cellsv2-layout
|
user/cellsv2-layout
|
||||||
user/certificate-validation
|
user/certificate-validation
|
||||||
user/conductor
|
user/conductor
|
||||||
user/config-drive
|
|
||||||
user/feature-classification
|
user/feature-classification
|
||||||
user/filter-scheduler
|
user/filter-scheduler
|
||||||
user/flavors
|
user/flavors
|
||||||
|
@ -252,8 +252,6 @@ looking parts of our architecture. These are collected below.
|
||||||
user/quotas
|
user/quotas
|
||||||
user/support-matrix
|
user/support-matrix
|
||||||
user/upgrade
|
user/upgrade
|
||||||
user/user-data
|
|
||||||
user/vendordata
|
|
||||||
user/wsgi
|
user/wsgi
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -294,8 +294,8 @@ details.
|
||||||
Nova Metadata API service
|
Nova Metadata API service
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Starting from the Stein release, the Nova Metadata API service
|
Starting from the Stein release, the :doc:`nova metadata API service
|
||||||
can be run either globally or per cell using the
|
</admin/metadata-service>` can be run either globally or per cell using the
|
||||||
:oslo.config:option:`api.local_metadata_per_cell` configuration option.
|
:oslo.config:option:`api.local_metadata_per_cell` configuration option.
|
||||||
|
|
||||||
**Global**
|
**Global**
|
||||||
|
@ -303,20 +303,20 @@ can be run either globally or per cell using the
|
||||||
If you have networks that span cells, you might need to run Nova metadata API
|
If you have networks that span cells, you might need to run Nova metadata API
|
||||||
globally. When running globally, it should be configured as an API-level
|
globally. When running globally, it should be configured as an API-level
|
||||||
service with access to the :oslo.config:option:`api_database.connection`
|
service with access to the :oslo.config:option:`api_database.connection`
|
||||||
information. The nova metadata API service must not be run as a standalone
|
information. The nova metadata API service **must not** be run as a standalone
|
||||||
service in this case (e.g. must not be run via the nova-api-metadata script).
|
service, using the :program:`nova-api-metadata` service, in this case.
|
||||||
|
|
||||||
**Local per cell**
|
**Local per cell**
|
||||||
|
|
||||||
Running Nova metadata API per cell can have better performance and data
|
Running Nova metadata API per cell can have better performance and data
|
||||||
isolation in a muli-cell deployment. If your networks are segmented along
|
isolation in a multi-cell deployment. If your networks are segmented along
|
||||||
cell boundaries, then you can run Nova metadata API service per cell. If
|
cell boundaries, then you can run Nova metadata API service per cell. If you
|
||||||
you choose to run it per cell, you should also configure each
|
choose to run it per cell, you should also configure each
|
||||||
`Neutron metadata-agent`_ to point to the corresponding nova-metadata-api.
|
:neutron-doc:`neutron-metadata-agent
|
||||||
The nova metadata API service must be run as a standalone service in this
|
<configuration/metadata-agent.html?#DEFAULT.nova_metadata_host>` service to
|
||||||
case (e.g. must be run via the nova-api-metadata script).
|
point to the corresponding :program:`nova-api-metadata`. The nova metadata API
|
||||||
|
service **must** be run as a standalone service, using the
|
||||||
.. _Neutron metadata-agent: https://docs.openstack.org/neutron/latest/configuration/metadata-agent.html?#DEFAULT.nova_metadata_host
|
:program:`nova-api-metadata` service, in this case.
|
||||||
|
|
||||||
|
|
||||||
Operations Requiring upcalls
|
Operations Requiring upcalls
|
||||||
|
|
|
@ -1,296 +0,0 @@
|
||||||
=======================================
|
|
||||||
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 :doc:`metadata service </user/metadata-service>`.
|
|
||||||
This metadata is different from the :doc:`user data </user/user-data>`.
|
|
||||||
|
|
||||||
One use case for using the configuration drive is to pass a networking
|
|
||||||
configuration when you do not use DHCP to assign IP addresses to
|
|
||||||
instances. For example, you might pass the IP address configuration for
|
|
||||||
the instance through the configuration drive, which the instance can
|
|
||||||
mount and access before you configure the network settings for the
|
|
||||||
instance.
|
|
||||||
|
|
||||||
Any modern guest operating system that is capable of mounting an ISO
|
|
||||||
9660 or VFAT file system can use the configuration drive.
|
|
||||||
|
|
||||||
Requirements and guidelines
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
To use the configuration drive, you must follow the following
|
|
||||||
requirements for the compute host and image.
|
|
||||||
|
|
||||||
**Compute host requirements**
|
|
||||||
|
|
||||||
- The following hypervisors support the configuration drive: libvirt,
|
|
||||||
XenServer, Hyper-V, VMware, and (since 17.0.0 Queens) PowerVM.
|
|
||||||
|
|
||||||
Also, the Bare Metal service supports the configuration drive.
|
|
||||||
|
|
||||||
- To use configuration drive with libvirt, XenServer, or VMware, you
|
|
||||||
must first install the genisoimage package on each compute host.
|
|
||||||
Otherwise, instances do not boot properly.
|
|
||||||
|
|
||||||
Use the ``mkisofs_cmd`` flag to set the path where you install the
|
|
||||||
genisoimage program. If genisoimage is in same path as the
|
|
||||||
``nova-compute`` service, you do not need to set this flag.
|
|
||||||
|
|
||||||
- To use configuration drive with Hyper-V, you must set the
|
|
||||||
``mkisofs_cmd`` value to the full path to an ``mkisofs.exe``
|
|
||||||
installation. Additionally, you must set the ``qemu_img_cmd`` value
|
|
||||||
in the ``hyperv`` configuration section to the full path to an
|
|
||||||
:command:`qemu-img` command installation.
|
|
||||||
|
|
||||||
- To use configuration drive with PowerVM or the Bare Metal service,
|
|
||||||
you do not need to prepare anything because these treat the configuration
|
|
||||||
drive properly.
|
|
||||||
|
|
||||||
**Image requirements**
|
|
||||||
|
|
||||||
- An image built with a recent version of the cloud-init package can
|
|
||||||
automatically access metadata passed through the configuration drive.
|
|
||||||
The cloud-init package version 0.7.1 works with Ubuntu, Fedora
|
|
||||||
based images (such as Red Hat Enterprise Linux) and openSUSE based
|
|
||||||
images (such as SUSE Linux Enterprise Server).
|
|
||||||
|
|
||||||
- If an image does not have the cloud-init package installed, you must
|
|
||||||
customize the image to run a script that mounts the configuration
|
|
||||||
drive on boot, reads the data from the drive, and takes appropriate
|
|
||||||
action such as adding the public key to an account. You can read more
|
|
||||||
details about how data is organized on the configuration drive.
|
|
||||||
|
|
||||||
- If you use Xen with a configuration drive, use the
|
|
||||||
:oslo.config:option:`xenserver.disable_agent` configuration parameter to
|
|
||||||
disable the agent.
|
|
||||||
|
|
||||||
**Guidelines**
|
|
||||||
|
|
||||||
- Do not rely on the presence of the EC2 metadata in the configuration
|
|
||||||
drive, because this content might be removed in a future release. For
|
|
||||||
example, do not rely on files in the ``ec2`` directory.
|
|
||||||
|
|
||||||
- When you create images that access configuration drive data and
|
|
||||||
multiple directories are under the ``openstack`` directory, always
|
|
||||||
select the highest API version by date that your consumer supports.
|
|
||||||
For example, if your guest image supports the 2012-03-05, 2012-08-05,
|
|
||||||
and 2013-04-13 versions, try 2013-04-13 first and fall back to a
|
|
||||||
previous version if 2013-04-13 is not present.
|
|
||||||
|
|
||||||
Enable and access the configuration drive
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
#. To enable the configuration drive, pass the ``--config-drive true``
|
|
||||||
parameter to the :command:`openstack server create` command.
|
|
||||||
|
|
||||||
The following example enables the configuration drive and passes user
|
|
||||||
data, a user data file, and two key/value metadata pairs, all of which are
|
|
||||||
accessible from the configuration drive:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ openstack server create --config-drive true --image my-image-name \
|
|
||||||
--flavor 1 --key-name mykey --user-data ./my-user-data.txt \
|
|
||||||
--property role=webservers --property essential=false MYINSTANCE
|
|
||||||
|
|
||||||
You can also configure the Compute service to always create a
|
|
||||||
configuration drive by setting the following option in the
|
|
||||||
``/etc/nova/nova.conf`` file:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
force_config_drive = true
|
|
||||||
|
|
||||||
It is also possible to force the config drive by specifying the
|
|
||||||
``img_config_drive=mandatory`` property in the image.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
If a user passes the ``--config-drive true`` flag to the
|
|
||||||
:command:`openstack server create` command, an administrator cannot
|
|
||||||
disable the configuration drive.
|
|
||||||
|
|
||||||
#. If your guest operating system supports accessing disk by label, you
|
|
||||||
can mount the configuration drive as the
|
|
||||||
``/dev/disk/by-label/configurationDriveVolumeLabel`` device. In the
|
|
||||||
following example, the configuration drive has the ``config-2``
|
|
||||||
volume label:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
# mkdir -p /mnt/config
|
|
||||||
# mount /dev/disk/by-label/config-2 /mnt/config
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Ensure that you use at least version 0.3.1 of CirrOS for
|
|
||||||
configuration drive support.
|
|
||||||
|
|
||||||
If your guest operating system does not use ``udev``, the
|
|
||||||
``/dev/disk/by-label`` directory is not present.
|
|
||||||
|
|
||||||
You can use the :command:`blkid` command to identify the block device that
|
|
||||||
corresponds to the configuration drive. For example, when you boot
|
|
||||||
the CirrOS image with the ``m1.tiny`` flavor, the device is
|
|
||||||
``/dev/vdb``:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
# blkid -t LABEL="config-2" -odevice
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
/dev/vdb
|
|
||||||
|
|
||||||
Once identified, you can mount the device:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
# mkdir -p /mnt/config
|
|
||||||
# mount /dev/vdb /mnt/config
|
|
||||||
|
|
||||||
Configuration drive contents
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
In this example, the contents of the configuration drive are as follows::
|
|
||||||
|
|
||||||
ec2/2009-04-04/meta-data.json
|
|
||||||
ec2/2009-04-04/user-data
|
|
||||||
ec2/latest/meta-data.json
|
|
||||||
ec2/latest/user-data
|
|
||||||
openstack/2012-08-10/meta_data.json
|
|
||||||
openstack/2012-08-10/user_data
|
|
||||||
openstack/content
|
|
||||||
openstack/content/0000
|
|
||||||
openstack/content/0001
|
|
||||||
openstack/latest/meta_data.json
|
|
||||||
openstack/latest/user_data
|
|
||||||
|
|
||||||
The files that appear on the configuration drive depend on the arguments
|
|
||||||
that you pass to the :command:`openstack server create` command.
|
|
||||||
|
|
||||||
Vendor-specific data can also be exposed to a guest in the configuration
|
|
||||||
drive. See :doc:`Vendordata </user/vendordata>` for details.
|
|
||||||
|
|
||||||
OpenStack metadata format
|
|
||||||
-------------------------
|
|
||||||
|
|
||||||
The following example shows the contents of the
|
|
||||||
``openstack/2012-08-10/meta_data.json`` and
|
|
||||||
``openstack/latest/meta_data.json`` files. These files are identical.
|
|
||||||
The file contents are formatted for readability.
|
|
||||||
|
|
||||||
.. code-block:: json
|
|
||||||
|
|
||||||
{
|
|
||||||
"availability_zone": "nova",
|
|
||||||
"hostname": "test.novalocal",
|
|
||||||
"launch_index": 0,
|
|
||||||
"name": "test",
|
|
||||||
"meta": {
|
|
||||||
"role": "webservers",
|
|
||||||
"essential": "false"
|
|
||||||
},
|
|
||||||
"public_keys": {
|
|
||||||
"mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
|
|
||||||
},
|
|
||||||
"uuid": "83679162-1378-4288-a2d4-70e13ec132aa"
|
|
||||||
}
|
|
||||||
|
|
||||||
EC2 metadata format
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
The following example shows the contents of the
|
|
||||||
``ec2/2009-04-04/meta-data.json`` and the ``ec2/latest/meta-data.json``
|
|
||||||
files. These files are identical. The file contents are formatted to
|
|
||||||
improve readability.
|
|
||||||
|
|
||||||
.. code-block:: json
|
|
||||||
|
|
||||||
{
|
|
||||||
"ami-id": "ami-00000001",
|
|
||||||
"ami-launch-index": 0,
|
|
||||||
"ami-manifest-path": "FIXME",
|
|
||||||
"block-device-mapping": {
|
|
||||||
"ami": "sda1",
|
|
||||||
"ephemeral0": "sda2",
|
|
||||||
"root": "/dev/sda1",
|
|
||||||
"swap": "sda3"
|
|
||||||
},
|
|
||||||
"hostname": "test.novalocal",
|
|
||||||
"instance-action": "none",
|
|
||||||
"instance-id": "i-00000001",
|
|
||||||
"instance-type": "m1.tiny",
|
|
||||||
"kernel-id": "aki-00000002",
|
|
||||||
"local-hostname": "test.novalocal",
|
|
||||||
"local-ipv4": null,
|
|
||||||
"placement": {
|
|
||||||
"availability-zone": "nova"
|
|
||||||
},
|
|
||||||
"public-hostname": "test.novalocal",
|
|
||||||
"public-ipv4": "",
|
|
||||||
"public-keys": {
|
|
||||||
"0": {
|
|
||||||
"openssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"ramdisk-id": "ari-00000003",
|
|
||||||
"reservation-id": "r-7lfps8wj",
|
|
||||||
"security-groups": [
|
|
||||||
"default"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
|
|
||||||
User data
|
|
||||||
---------
|
|
||||||
|
|
||||||
The ``openstack/2012-08-10/user_data``, ``openstack/latest/user_data``,
|
|
||||||
``ec2/2009-04-04/user-data``, and ``ec2/latest/user-data`` file are
|
|
||||||
present only if the ``--user-data`` flag and the contents of the user
|
|
||||||
data file are passed to the :command:`openstack server create` command.
|
|
||||||
|
|
||||||
Configuration drive format
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
The default format of the configuration drive as an ISO 9660 file
|
|
||||||
system. To explicitly specify the ISO 9660 format, add the following
|
|
||||||
line to the ``/etc/nova/nova.conf`` file:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
config_drive_format=iso9660
|
|
||||||
|
|
||||||
By default, you cannot attach the configuration drive image as a CD
|
|
||||||
drive instead of as a disk drive. To attach a CD drive, add the
|
|
||||||
following line to the ``/etc/nova/nova.conf`` file:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
[hyperv]
|
|
||||||
config_drive_cdrom=true
|
|
||||||
|
|
||||||
.. note:: Attaching a configuration drive as a CD drive is only supported
|
|
||||||
by the Hyper-V compute driver.
|
|
||||||
|
|
||||||
For legacy reasons, you can configure the configuration drive to use
|
|
||||||
VFAT format instead of ISO 9660. It is unlikely that you would require
|
|
||||||
VFAT format because ISO 9660 is widely supported across operating
|
|
||||||
systems. However, to use the VFAT format, add the following line to the
|
|
||||||
``/etc/nova/nova.conf`` file:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
config_drive_format=vfat
|
|
||||||
|
|
||||||
If you choose VFAT, the configuration drive is 64 MB.
|
|
||||||
|
|
||||||
.. deprecated:: 19.0.0
|
|
||||||
|
|
||||||
The :oslo.config:option:`config_drive_format` option was deprecated in 19.0.0
|
|
||||||
(Stein). The option was originally added as a workaround for a bug in
|
|
||||||
libvirt, `#1246201`__, that was resolved in libvirt v1.2.17. As a result,
|
|
||||||
this option is no longer necessary or useful.
|
|
||||||
|
|
||||||
__ https://bugs.launchpad.net/nova/+bug/1246201
|
|
|
@ -337,7 +337,7 @@ notes=This ensures the user data provided by the user when booting
|
||||||
a server is available in one of the expected config drive locations.
|
a server is available in one of the expected config drive locations.
|
||||||
maturity=complete
|
maturity=complete
|
||||||
api_doc_link=http://developer.openstack.org/api-ref/compute/#create-server
|
api_doc_link=http://developer.openstack.org/api-ref/compute/#create-server
|
||||||
admin_doc_link=https://docs.openstack.org/nova/latest/user/config-drive.html
|
admin_doc_link=https://docs.openstack.org/nova/latest/admin/config-drive.html
|
||||||
tempest_test_uuids=7fff3fb3-91d8-4fd0-bd7d-0204f1f180ba
|
tempest_test_uuids=7fff3fb3-91d8-4fd0-bd7d-0204f1f180ba
|
||||||
cli=
|
cli=
|
||||||
libvirt-kvm=complete
|
libvirt-kvm=complete
|
||||||
|
|
|
@ -9,8 +9,7 @@ End user guide
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
launch-instances
|
launch-instances
|
||||||
config-drive
|
metadata
|
||||||
metadata-service
|
|
||||||
certificate-validation
|
certificate-validation
|
||||||
resize
|
resize
|
||||||
reboot
|
reboot
|
||||||
|
@ -80,6 +79,7 @@ Once you are running nova, the following information is extremely useful.
|
||||||
environment. If you are seeing unexpected distribution of compute instances
|
environment. If you are seeing unexpected distribution of compute instances
|
||||||
in your hosts, you'll want to dive into this configuration.
|
in your hosts, you'll want to dive into this configuration.
|
||||||
|
|
||||||
* :doc:`Exposing custom metadata to compute instances </user/vendordata>`: How and
|
* :doc:`Exposing custom metadata to compute instances </admin/vendordata>`: How
|
||||||
when you might want to extend the basic metadata exposed to compute instances
|
and when you might want to extend the basic metadata exposed to compute
|
||||||
(either via metadata server or config drive) for your specific purposes.
|
instances (either via metadata server or config drive) for your specific
|
||||||
|
purposes.
|
||||||
|
|
|
@ -18,8 +18,8 @@ Follow the steps below to launch an instance from an image.
|
||||||
For example, you can add a description for your server by providing the
|
For example, you can add a description for your server by providing the
|
||||||
``--property description="My Server"`` parameter.
|
``--property description="My Server"`` parameter.
|
||||||
|
|
||||||
You can pass :doc:`user data </user/user-data>` in a local file at instance
|
You can pass :ref:`user data <metadata-userdata>` in a local file at
|
||||||
launch by using the ``--user-data USER-DATA-FILE`` parameter.
|
instance launch by using the ``--user-data USER-DATA-FILE`` parameter.
|
||||||
|
|
||||||
.. important::
|
.. important::
|
||||||
|
|
||||||
|
|
|
@ -16,7 +16,7 @@ Before you can launch an instance, gather the following parameters:
|
||||||
available hardware configuration for a server. It defines the size of
|
available hardware configuration for a server. It defines the size of
|
||||||
a virtual server that can be launched.
|
a virtual server that can be launched.
|
||||||
|
|
||||||
- Any **user data** files. A :doc:`user data </user/user-data>` file is a
|
- Any **user data** files. A :ref:`user data <metadata-userdata>` file is a
|
||||||
special key in the metadata service that holds a file that cloud-aware
|
special key in the metadata service that holds a file that cloud-aware
|
||||||
applications in the guest instance can access. For example, one application
|
applications in the guest instance can access. For example, one application
|
||||||
that uses user data is the
|
that uses user data is the
|
||||||
|
|
|
@ -1,199 +0,0 @@
|
||||||
================
|
|
||||||
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/2018-08-27/meta_data.json``:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ curl http://169.254.169.254/openstack/2018-08-27/meta_data.json
|
|
||||||
|
|
||||||
.. code-block:: json
|
|
||||||
|
|
||||||
{
|
|
||||||
"random_seed": "yu5ZnkqF2CqnDZVAfZgarGLoFubhcK5wHG4fcNfVZEtie/bTV8k2dDXK\
|
|
||||||
C7krP2cjp9A7g9LIWe5+WSaZ3zpvQ03hp/4mMNy9V1U/mnRMZyQ3W4Fn\
|
|
||||||
Nex7UP/0Smjb9rVzfUb2HrVUCN61Yo4jHySTd7UeEasF0nxBrx6NFY6e\
|
|
||||||
KRoELGPPr1S6+ZDcDT1Sp7pRoHqwVbzyJZc80ICndqxGkZOuvwDgVKZD\
|
|
||||||
B6O3kFSLuqOfNRaL8y79gJizw/MHI7YjOxtPMr6g0upIBHFl8Vt1VKjR\
|
|
||||||
s3zB+c3WkC6JsopjcToHeR4tPK0RtdIp6G2Bbls5cblQUAc/zG0a8BAm\
|
|
||||||
p6Pream9XRpaQBDk4iXtjIn8Bf56SCANOFfeI5BgBeTwfdDGoM0Ptml6\
|
|
||||||
BJQiyFtc3APfXVVswrCq2SuJop+spgrpiKXOzXvve+gEWVhyfbigI52e\
|
|
||||||
l1VyMoyZ7/pbdnX0LCGHOdAU8KRnBoo99ZOErv+p7sROEIN4Yywq/U/C\
|
|
||||||
xXtQ5BNCtae389+3yT5ZCV7fYzLYChgDMJSZ9ds9fDFIWKmsRu3N+wUg\
|
|
||||||
eL4klxAjRgzQ7MMlap5kppnIYRxXVy0a5j1qOaBAzJB5LLJ7r3/Om38x\
|
|
||||||
Z4+XGWjqd6KbSwhUVs1aqzxpep1Sp3nTurQCuYjgMchjslt0O5oJjh5Z\
|
|
||||||
hbCZT3YUc8M=\n",
|
|
||||||
"uuid": "d8e02d56-2648-49a3-bf97-6be8f1204f38",
|
|
||||||
"availability_zone": "nova",
|
|
||||||
"keys": [
|
|
||||||
{
|
|
||||||
"data": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKV\
|
|
||||||
VRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTH\
|
|
||||||
bsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCe\
|
|
||||||
uMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova\n",
|
|
||||||
"type": "ssh",
|
|
||||||
"name": "mykey"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"hostname": "test.novalocal",
|
|
||||||
"launch_index": 0,
|
|
||||||
"meta": {
|
|
||||||
"priority": "low",
|
|
||||||
"role": "webserver"
|
|
||||||
},
|
|
||||||
"devices": [
|
|
||||||
{
|
|
||||||
"type": "nic",
|
|
||||||
"bus": "pci",
|
|
||||||
"address": "0000:00:02.0",
|
|
||||||
"mac": "00:11:22:33:44:55",
|
|
||||||
"tags": ["trusted"]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "disk",
|
|
||||||
"bus": "ide",
|
|
||||||
"address": "0:0",
|
|
||||||
"serial": "disk-vol-2352423",
|
|
||||||
"path": "/dev/sda",
|
|
||||||
"tags": ["baz"]
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"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 :doc:`user data </user/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/2018-08-27/user_data``:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ curl http://169.254.169.254/openstack/2018-08-27/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
|
|
||||||
<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.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'
|
|
|
@ -0,0 +1,504 @@
|
||||||
|
========
|
||||||
|
Metadata
|
||||||
|
========
|
||||||
|
|
||||||
|
Nova presents configuration information to instances it starts via a mechanism
|
||||||
|
called metadata. These mechanisms are widely used via helpers such as
|
||||||
|
`cloud-init`_ to specify things like the root password the instance should use.
|
||||||
|
|
||||||
|
This metadata is made available via either a *config drive* or the *metadata
|
||||||
|
service* and can be somewhat customised by the user using the *user data*
|
||||||
|
feature. This guide provides an overview of these features along with a summary
|
||||||
|
of the types of metadata available.
|
||||||
|
|
||||||
|
.. _cloud-init: https://cloudinit.readthedocs.io/en/latest/
|
||||||
|
|
||||||
|
|
||||||
|
Types of metadata
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
There are three separate groups of users who need to be able to specify
|
||||||
|
metadata for an instance.
|
||||||
|
|
||||||
|
User provided data
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The user who booted the instance can pass metadata to the instance in several
|
||||||
|
ways. For authentication keypairs, the keypairs functionality of the nova API
|
||||||
|
can be used to upload a key and then specify that key during the nova boot API
|
||||||
|
request. For less structured data, a small opaque blob of data may be passed
|
||||||
|
via the :ref:`user data <metadata-userdata>` feature of the nova API. Examples
|
||||||
|
of such unstructured data would be the puppet role that the instance should use,
|
||||||
|
or the HTTP address of a server from which to fetch post-boot configuration
|
||||||
|
information.
|
||||||
|
|
||||||
|
Nova provided data
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Nova itself needs to pass information to the instance via its internal
|
||||||
|
implementation of the metadata system. Such information includes the requested
|
||||||
|
hostname for the instance and the availability zone the instance is in. This
|
||||||
|
happens by default and requires no configuration by the user or deployer.
|
||||||
|
|
||||||
|
Nova provides both an :ref:`OpenStack metadata API <metadata-openstack-format>`
|
||||||
|
and an :ref:`EC2-compatible API <metadata-ec2-format>`. Both the OpenStack
|
||||||
|
metadata and EC2-compatible APIs are versioned by date. These are described
|
||||||
|
later.
|
||||||
|
|
||||||
|
Deployer provided data
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
A deployer of OpenStack may need to pass data to an instance. It is also
|
||||||
|
possible that this data is not known to the user starting the instance. An
|
||||||
|
example might be a cryptographic token to be used to register the instance with
|
||||||
|
Active Directory post boot -- the user starting the instance should not have
|
||||||
|
access to Active Directory to create this token, but the nova deployment might
|
||||||
|
have permissions to generate the token on the user's behalf. This is possible
|
||||||
|
using the :ref:`vendordata <metadata-vendordata>` feature, which must be
|
||||||
|
configured by your cloud operator.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _metadata-service:
|
||||||
|
|
||||||
|
The metadata service
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This section provides end user information about the metadata service. For
|
||||||
|
deployment information about the metadata service, refer to the :doc:`admin
|
||||||
|
guide </admin/metadata-service>`.
|
||||||
|
|
||||||
|
The *metadata service* provides a way for instances to retrieve
|
||||||
|
instance-specific data via a REST API. Instances access this service at
|
||||||
|
``169.254.169.254`` and all types of metadata, be it user-, nova- or
|
||||||
|
vendor-provided, can be accessed via this service.
|
||||||
|
|
||||||
|
Using the metadata service
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
To retrieve a list of supported versions for the :ref:`OpenStack metadata API
|
||||||
|
<metadata-openstack-format>`, make a GET request to
|
||||||
|
``http://169.254.169.254/openstack``, which will return a list of directories:
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
|
||||||
|
Refer to :ref:`OpenStack format metadata <metadata-openstack-format>` for
|
||||||
|
information on the contents and structure of these directories.
|
||||||
|
|
||||||
|
To list supported versions for the :ref:`EC2-compatible metadata API
|
||||||
|
<metadata-ec2-format>`, make a GET request to ``http://169.254.169.254``, which
|
||||||
|
will, once again, return a list of directories:
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
|
||||||
|
Refer to :ref:`EC2-compatible metadata <metadata-ec2-format>` for information on
|
||||||
|
the contents and structure of these directories.
|
||||||
|
|
||||||
|
|
||||||
|
.. _metadata-config-drive:
|
||||||
|
|
||||||
|
Config drives
|
||||||
|
-------------
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This section provides end user information about config drives. For
|
||||||
|
deployment information about the config drive feature, refer to the
|
||||||
|
:doc:`admin guide </admin/config-drive>`.
|
||||||
|
|
||||||
|
*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.
|
||||||
|
|
||||||
|
One use case for using the config drive is to pass a networking configuration
|
||||||
|
when you do not use DHCP to assign IP addresses to instances. For example, you
|
||||||
|
might pass the IP address configuration for the instance through the config
|
||||||
|
drive, which the instance can mount and access before you configure the network
|
||||||
|
settings for the instance.
|
||||||
|
|
||||||
|
Using the config drive
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
To enable the config drive for an instance, pass the ``--config-drive true``
|
||||||
|
parameter to the :command:`openstack server create` command.
|
||||||
|
|
||||||
|
The following example enables the config drive and passes a user data file and
|
||||||
|
two key/value metadata pairs, all of which are accessible from the config
|
||||||
|
drive:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ openstack server create --config-drive true --image my-image-name \
|
||||||
|
--flavor 1 --key-name mykey --user-data ./my-user-data.txt \
|
||||||
|
--property role=webservers --property essential=false MYINSTANCE
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The Compute service can be configured to always create a config drive. For
|
||||||
|
more information, refer to :doc:`the admin guide </admin/config-drive>`.
|
||||||
|
|
||||||
|
If your guest operating system supports accessing disk by label, you can mount
|
||||||
|
the config drive as the ``/dev/disk/by-label/configurationDriveVolumeLabel``
|
||||||
|
device. In the following example, the config drive has the ``config-2`` volume
|
||||||
|
label:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
# mkdir -p /mnt/config
|
||||||
|
# mount /dev/disk/by-label/config-2 /mnt/config
|
||||||
|
|
||||||
|
If your guest operating system does not use ``udev``, the ``/dev/disk/by-label``
|
||||||
|
directory is not present. You can use the :command:`blkid` command to identify
|
||||||
|
the block device that corresponds to the config drive. For example:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
# blkid -t LABEL="config-2" -odevice
|
||||||
|
/dev/vdb
|
||||||
|
|
||||||
|
Once identified, you can mount the device:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
# mkdir -p /mnt/config
|
||||||
|
# mount /dev/vdb /mnt/config
|
||||||
|
|
||||||
|
Once mounted, you can examine the contents of the config drive:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ cd /mnt/config
|
||||||
|
$ find . -maxdepth 2
|
||||||
|
.
|
||||||
|
./ec2
|
||||||
|
./ec2/2009-04-04
|
||||||
|
./ec2/latest
|
||||||
|
./openstack
|
||||||
|
./openstack/2012-08-10
|
||||||
|
./openstack/2013-04-04
|
||||||
|
./openstack/2013-10-17
|
||||||
|
./openstack/2015-10-15
|
||||||
|
./openstack/2016-06-30
|
||||||
|
./openstack/2016-10-06
|
||||||
|
./openstack/2017-02-22
|
||||||
|
./openstack/latest
|
||||||
|
|
||||||
|
The files that appear on the config drive depend on the arguments that you pass
|
||||||
|
to the :command:`openstack server create` command. The format of this directory
|
||||||
|
is the same as that provided by the :ref:`metadata service <metadata-service>`,
|
||||||
|
with the exception that the EC2-compatible metadata is now located in the
|
||||||
|
``ec2`` directory instead of the root (``/``) directory. Refer to the
|
||||||
|
:ref:`metadata-openstack-format` and :ref:`metadata-ec2-format` sections for
|
||||||
|
information about the format of the files and subdirectories within these
|
||||||
|
directories.
|
||||||
|
|
||||||
|
|
||||||
|
Nova metadata
|
||||||
|
-------------
|
||||||
|
|
||||||
|
As noted previously, nova provides its metadata in two formats: OpenStack format
|
||||||
|
and EC2-compatible format.
|
||||||
|
|
||||||
|
.. _metadata-openstack-format:
|
||||||
|
|
||||||
|
OpenStack format metadata
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. versionchanged:: 12.0.0
|
||||||
|
|
||||||
|
Support for network metadata was added in the Liberty release.
|
||||||
|
|
||||||
|
Metadata from the OpenStack API is distributed in JSON format. There are two
|
||||||
|
files provided for each version: ``meta_data.json`` and ``network_data.json``.
|
||||||
|
The ``meta_data.json`` file contains nova-specific information, while the
|
||||||
|
``network_data.json`` file contains information retrieved from neutron. For
|
||||||
|
example:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ curl http://169.254.169.254/openstack/2018-08-27/meta_data.json
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"random_seed": "yu5ZnkqF2CqnDZVAfZgarGLoFubhcK5wHG4fcNfVZEtie/bTV8k2dDXK\
|
||||||
|
C7krP2cjp9A7g9LIWe5+WSaZ3zpvQ03hp/4mMNy9V1U/mnRMZyQ3W4Fn\
|
||||||
|
Nex7UP/0Smjb9rVzfUb2HrVUCN61Yo4jHySTd7UeEasF0nxBrx6NFY6e\
|
||||||
|
KRoELGPPr1S6+ZDcDT1Sp7pRoHqwVbzyJZc80ICndqxGkZOuvwDgVKZD\
|
||||||
|
B6O3kFSLuqOfNRaL8y79gJizw/MHI7YjOxtPMr6g0upIBHFl8Vt1VKjR\
|
||||||
|
s3zB+c3WkC6JsopjcToHeR4tPK0RtdIp6G2Bbls5cblQUAc/zG0a8BAm\
|
||||||
|
p6Pream9XRpaQBDk4iXtjIn8Bf56SCANOFfeI5BgBeTwfdDGoM0Ptml6\
|
||||||
|
BJQiyFtc3APfXVVswrCq2SuJop+spgrpiKXOzXvve+gEWVhyfbigI52e\
|
||||||
|
l1VyMoyZ7/pbdnX0LCGHOdAU8KRnBoo99ZOErv+p7sROEIN4Yywq/U/C\
|
||||||
|
xXtQ5BNCtae389+3yT5ZCV7fYzLYChgDMJSZ9ds9fDFIWKmsRu3N+wUg\
|
||||||
|
eL4klxAjRgzQ7MMlap5kppnIYRxXVy0a5j1qOaBAzJB5LLJ7r3/Om38x\
|
||||||
|
Z4+XGWjqd6KbSwhUVs1aqzxpep1Sp3nTurQCuYjgMchjslt0O5oJjh5Z\
|
||||||
|
hbCZT3YUc8M=\n",
|
||||||
|
"uuid": "d8e02d56-2648-49a3-bf97-6be8f1204f38",
|
||||||
|
"availability_zone": "nova",
|
||||||
|
"keys": [
|
||||||
|
{
|
||||||
|
"data": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKV\
|
||||||
|
VRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTH\
|
||||||
|
bsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCe\
|
||||||
|
uMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova\n",
|
||||||
|
"type": "ssh",
|
||||||
|
"name": "mykey"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"hostname": "test.novalocal",
|
||||||
|
"launch_index": 0,
|
||||||
|
"meta": {
|
||||||
|
"priority": "low",
|
||||||
|
"role": "webserver"
|
||||||
|
},
|
||||||
|
"devices": [
|
||||||
|
{
|
||||||
|
"type": "nic",
|
||||||
|
"bus": "pci",
|
||||||
|
"address": "0000:00:02.0",
|
||||||
|
"mac": "00:11:22:33:44:55",
|
||||||
|
"tags": ["trusted"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "disk",
|
||||||
|
"bus": "ide",
|
||||||
|
"address": "0:0",
|
||||||
|
"serial": "disk-vol-2352423",
|
||||||
|
"path": "/dev/sda",
|
||||||
|
"tags": ["baz"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"project_id": "f7ac731cc11f40efbc03a9f9e1d1d21f",
|
||||||
|
"public_keys": {
|
||||||
|
"mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKV\
|
||||||
|
VRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTH\
|
||||||
|
bsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCe\
|
||||||
|
uMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova\n"
|
||||||
|
},
|
||||||
|
"name": "test"
|
||||||
|
}
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ curl http://169.254.169.254/openstack/2018-08-27/network_data.json
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"links": [
|
||||||
|
{
|
||||||
|
"ethernet_mac_address": "fa:16:3e:9c:bf:3d",
|
||||||
|
"id": "tapcd9f6d46-4a",
|
||||||
|
"mtu": null,
|
||||||
|
"type": "bridge",
|
||||||
|
"vif_id": "cd9f6d46-4a3a-43ab-a466-994af9db96fc"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"networks": [
|
||||||
|
{
|
||||||
|
"id": "network0",
|
||||||
|
"link": "tapcd9f6d46-4a",
|
||||||
|
"network_id": "99e88329-f20d-4741-9593-25bf07847b16",
|
||||||
|
"type": "ipv4_dhcp"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"services": [
|
||||||
|
{
|
||||||
|
"address": "8.8.8.8",
|
||||||
|
"type": "dns"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
.. _metadata-ec2-format:
|
||||||
|
|
||||||
|
EC2-compatible metadata
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The EC2-compatible API is compatible with version 2009-04-04 of the `Amazon EC2
|
||||||
|
metadata service`__ 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/``. For example:
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
|
||||||
|
__ https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
|
||||||
|
|
||||||
|
|
||||||
|
.. _metadata-userdata:
|
||||||
|
|
||||||
|
User data
|
||||||
|
---------
|
||||||
|
|
||||||
|
*User data* is a blob of data that the user can specify when they launch an
|
||||||
|
instance. The instance can access this data through the metadata service or
|
||||||
|
config drive. Commonly used to pass a shell script that the instance runs on
|
||||||
|
boot.
|
||||||
|
|
||||||
|
For example, one application that uses user data is the `cloud-init
|
||||||
|
<https://help.ubuntu.com/community/CloudInit>`__ system, which is an open-source
|
||||||
|
package from Ubuntu that is available on various Linux distributions and which
|
||||||
|
handles early initialization of a cloud instance.
|
||||||
|
|
||||||
|
You can place user data in a local file and pass it through the ``--user-data
|
||||||
|
<user-data-file>`` parameter at instance creation.
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ openstack server create --image ubuntu-cloudimage --flavor 1 \
|
||||||
|
--user-data mydata.file VM_INSTANCE
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The provided user data must be base64 encoded and is restricted to 65535
|
||||||
|
bytes.
|
||||||
|
|
||||||
|
Once booted, you can access this data from the instance using either the
|
||||||
|
metadata service or the config drive. To access it via the metadata service,
|
||||||
|
make a GET request to either
|
||||||
|
``http://169.254.169.254/openstack/{version}/user_data`` (OpenStack API) or
|
||||||
|
``http://169.254.169.254/{version}/user-data`` (EC2-compatible API). For
|
||||||
|
example:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ curl http://169.254.169.254/openstack/2018-08-27/user_data
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
#!/bin/bash
|
||||||
|
echo 'Extra user data here'
|
||||||
|
|
||||||
|
|
||||||
|
.. _metadata-vendordata:
|
||||||
|
|
||||||
|
Vendordata
|
||||||
|
----------
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This section provides end user information about the vendordata feature. For
|
||||||
|
deployment information about this feature, refer to the :doc:`admin guide
|
||||||
|
</admin/vendordata>`.
|
||||||
|
|
||||||
|
.. versionchanged:: 14.0.0
|
||||||
|
|
||||||
|
Support for dynamic vendor data was added in the Newton release.
|
||||||
|
|
||||||
|
**Where configured**, instances can retrieve vendor-specific data from the
|
||||||
|
metadata service or config drive. To access it via the metadata service, make a
|
||||||
|
GET request to either
|
||||||
|
``http://169.254.169.254/openstack/{version}/vendor_data.json`` or
|
||||||
|
``http://169.254.169.254/openstack/{version}/vendor_data2.json``, depending on
|
||||||
|
the deployment. For example:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ curl http://169.254.169.254/openstack/2018-08-27/vendor_data2.json
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"testing": {
|
||||||
|
"value1": 1,
|
||||||
|
"value2": 2,
|
||||||
|
"value3": "three"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The presence and contents of this file will vary from deployment to
|
||||||
|
deployment.
|
||||||
|
|
||||||
|
|
||||||
|
General guidelines
|
||||||
|
------------------
|
||||||
|
|
||||||
|
- Do not rely on the presence of the EC2 metadata in the metadata API or
|
||||||
|
config drive, because this content might be removed in a future release. For
|
||||||
|
example, do not rely on files in the ``ec2`` directory.
|
||||||
|
|
||||||
|
- When you create images that access metadata service or config drive data and
|
||||||
|
multiple directories are under the ``openstack`` directory, always select the
|
||||||
|
highest API version by date that your consumer supports. For example, if your
|
||||||
|
guest image supports the ``2012-03-05``, ``2012-08-05``, and ``2013-04-13``
|
||||||
|
versions, try ``2013-04-13`` first and fall back to a previous version if
|
||||||
|
``2013-04-13`` is not present.
|
|
@ -1,25 +0,0 @@
|
||||||
==============================
|
|
||||||
Provide user data to instances
|
|
||||||
==============================
|
|
||||||
|
|
||||||
*User data* is a blob of data that the user can specify when they launch an
|
|
||||||
instance. The instance can access this data through the metadata service or
|
|
||||||
config drive. Commonly used to pass a shell script that the instance runs on
|
|
||||||
boot.
|
|
||||||
|
|
||||||
For example, one application that uses user data is the
|
|
||||||
`cloud-init <https://help.ubuntu.com/community/CloudInit>`__ system,
|
|
||||||
which is an open-source package from Ubuntu that is available on various
|
|
||||||
Linux distributions and which handles early initialization of a cloud
|
|
||||||
instance.
|
|
||||||
|
|
||||||
You can place user data in a local file and pass it through the
|
|
||||||
``--user-data <user-data-file>`` parameter at instance creation.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ openstack server create --image ubuntu-cloudimage --flavor 1 \
|
|
||||||
--user-data mydata.file VM_INSTANCE
|
|
||||||
|
|
||||||
.. note:: The provided user data must be base64 encoded and is restricted to
|
|
||||||
65535 bytes.
|
|
|
@ -1,140 +0,0 @@
|
||||||
==========
|
|
||||||
Vendordata
|
|
||||||
==========
|
|
||||||
|
|
||||||
Nova presents configuration information to instances it starts via a mechanism
|
|
||||||
called metadata. This metadata is made available via either a configdrive, or
|
|
||||||
the metadata service. These mechanisms are widely used via helpers such as
|
|
||||||
cloud-init to specify things like the root password the instance should use.
|
|
||||||
There are three separate groups of people who need to be able to specify
|
|
||||||
metadata for an instance.
|
|
||||||
|
|
||||||
User provided data
|
|
||||||
------------------
|
|
||||||
|
|
||||||
The user who booted the instance can pass metadata to the instance in several
|
|
||||||
ways. For authentication keypairs, the keypairs functionality of the Nova APIs
|
|
||||||
can be used to upload a key and then specify that key during the Nova boot API
|
|
||||||
request. For less structured data, a small opaque blob of data may be passed
|
|
||||||
via the :doc:`user data </user/user-data>` feature of the Nova API. Examples of
|
|
||||||
such unstructured data would be the puppet role that the instance should use,
|
|
||||||
or the HTTP address of a server to fetch post-boot configuration information
|
|
||||||
from.
|
|
||||||
|
|
||||||
Nova provided data
|
|
||||||
------------------
|
|
||||||
|
|
||||||
Nova itself needs to pass information to the instance via its internal
|
|
||||||
implementation of the metadata system. Such information includes the network
|
|
||||||
configuration for the instance, as well as the requested hostname for the
|
|
||||||
instance. This happens by default and requires no configuration by the user or
|
|
||||||
deployer.
|
|
||||||
|
|
||||||
Deployer provided data
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
There is however a third type of data. It is possible that the deployer of
|
|
||||||
OpenStack needs to pass data to an instance. It is also possible that this data
|
|
||||||
is not known to the user starting the instance. An example might be a
|
|
||||||
cryptographic token to be used to register the instance with Active Directory
|
|
||||||
post boot -- the user starting the instance should not have access to Active
|
|
||||||
Directory to create this token, but the Nova deployment might have permissions
|
|
||||||
to generate the token on the user's behalf.
|
|
||||||
|
|
||||||
Nova supports a mechanism to add "vendordata" to the metadata handed to
|
|
||||||
instances. This is done by loading named modules, which must appear in the nova
|
|
||||||
source code. We provide two such modules:
|
|
||||||
|
|
||||||
- StaticJSON: a module which can include the contents of a static JSON file
|
|
||||||
loaded from disk, configurable via the
|
|
||||||
:oslo.config:option:`api.vendordata_jsonfile_path` option. This can be used
|
|
||||||
for things which don't change between instances, such as the location of the
|
|
||||||
corporate puppet server. This is the default provider.
|
|
||||||
|
|
||||||
- DynamicJSON: a module which will make a request to an external REST service
|
|
||||||
to determine what metadata to add to an instance. This is how we recommend
|
|
||||||
you generate things like Active Directory tokens which change per instance.
|
|
||||||
|
|
||||||
The vendordata providers are configured via the
|
|
||||||
:oslo.config:option:`api.vendordata_providers` option.
|
|
||||||
|
|
||||||
Tell me more about DynamicJSON
|
|
||||||
==============================
|
|
||||||
|
|
||||||
To use DynamicJSON, you configure it like this:
|
|
||||||
|
|
||||||
- Add "DynamicJSON" to the :oslo.config:option:`api.vendordata_providers`
|
|
||||||
configuration option. This can also include "StaticJSON" if you'd like.
|
|
||||||
- Specify the REST services to be contacted to generate metadata in the
|
|
||||||
:oslo.config:option:`api.vendordata_dynamic_targets` configuration option.
|
|
||||||
There can be more than one of these, but note that they will be queried once
|
|
||||||
per metadata request from the instance, which can mean a fair bit of traffic
|
|
||||||
depending on your configuration and the configuration of the instance.
|
|
||||||
|
|
||||||
The format for an entry in *vendordata_dynamic_targets* is like this::
|
|
||||||
|
|
||||||
<name>@<url>
|
|
||||||
|
|
||||||
Where name is a short string not including the '@' character, and where the
|
|
||||||
URL can include a port number if so required. An example would be::
|
|
||||||
|
|
||||||
testing@http://127.0.0.1:125
|
|
||||||
|
|
||||||
Metadata fetched from this target will appear in the metadata service at a
|
|
||||||
new file called *vendordata2.json*, with a path (either in the metadata service
|
|
||||||
URL or in the config drive) like this::
|
|
||||||
|
|
||||||
openstack/2016-10-06/vendor_data2.json
|
|
||||||
|
|
||||||
For each dynamic target, there will be an entry in the JSON file named after
|
|
||||||
that target. For example::
|
|
||||||
|
|
||||||
{
|
|
||||||
"testing": {
|
|
||||||
"value1": 1,
|
|
||||||
"value2": 2,
|
|
||||||
"value3": "three"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
Do not specify the same name more than once. If you do, we will ignore
|
|
||||||
subsequent uses of a previously used name.
|
|
||||||
|
|
||||||
The following data is passed to your REST service as a JSON encoded POST:
|
|
||||||
|
|
||||||
+-------------+-------------------------------------------------+
|
|
||||||
| Key | Description |
|
|
||||||
+=============+=================================================+
|
|
||||||
| project-id | The ID of the project that owns this instance. |
|
|
||||||
+-------------+-------------------------------------------------+
|
|
||||||
| instance-id | The UUID of this instance. |
|
|
||||||
+-------------+-------------------------------------------------+
|
|
||||||
| image-id | The ID of the image used to boot this instance. |
|
|
||||||
+-------------+-------------------------------------------------+
|
|
||||||
| user-data | As specified by the user at boot time. |
|
|
||||||
+-------------+-------------------------------------------------+
|
|
||||||
| hostname | The hostname of the instance. |
|
|
||||||
+-------------+-------------------------------------------------+
|
|
||||||
| metadata | As specified by the user at boot time. |
|
|
||||||
+-------------+-------------------------------------------------+
|
|
||||||
|
|
||||||
Deployment considerations
|
|
||||||
=========================
|
|
||||||
|
|
||||||
Nova provides authentication to external metadata services in order to provide
|
|
||||||
some level of certainty that the request came from nova. This is done by
|
|
||||||
providing a service token with the request -- you can then just deploy your
|
|
||||||
metadata service with the keystone authentication WSGI middleware. This is
|
|
||||||
configured using the keystone authentication parameters in the
|
|
||||||
:oslo.config:group:`vendordata_dynamic_auth` configuration group.
|
|
||||||
|
|
||||||
References
|
|
||||||
==========
|
|
||||||
|
|
||||||
* Michael Still's talk from the Queens summit in Sydney:
|
|
||||||
`Metadata, User Data, Vendor Data, oh my!`_
|
|
||||||
* Michael's blog post on `deploying a simple vendordata service`_ which
|
|
||||||
provides more details and sample code to supplement the documentation above.
|
|
||||||
|
|
||||||
.. _Metadata, User Data, Vendor Data, oh my!: https://www.openstack.org/videos/sydney-2017/metadata-user-data-vendor-data-oh-my
|
|
||||||
.. _deploying a simple vendordata service: http://www.stillhq.com/openstack/000022.html
|
|
|
@ -64,8 +64,12 @@
|
||||||
/nova/latest/testing/zero-downtime-upgrade.html 301 /nova/latest/contributor/testing/zero-downtime-upgrade.html
|
/nova/latest/testing/zero-downtime-upgrade.html 301 /nova/latest/contributor/testing/zero-downtime-upgrade.html
|
||||||
/nova/latest/threading.html 301 /nova/latest/reference/threading.html
|
/nova/latest/threading.html 301 /nova/latest/reference/threading.html
|
||||||
/nova/latest/upgrade.html 301 /nova/latest/user/upgrade.html
|
/nova/latest/upgrade.html 301 /nova/latest/user/upgrade.html
|
||||||
/nova/latest/vendordata.html 301 /nova/latest/user/vendordata.html
|
/nova/latest/user/cellsv2_layout.html 301 /nova/latest/user/cellsv2-layout.html
|
||||||
|
/nova/latest/user/config-drive.html 301 /nova/latest/user/metadata.html
|
||||||
|
/nova/latest/user/metadata-service.html 301 /nova/latest/user/metadata.html
|
||||||
|
/nova/latest/user/placement.html 301 /placement/latest/
|
||||||
|
/nova/latest/user/user-data.html 301 /nova/latest/user/metadata.html
|
||||||
|
/nova/latest/user/vendordata.html 301 /nova/latest/user/metadata.html
|
||||||
|
/nova/latest/vendordata.html 301 /nova/latest/user/metadata.html
|
||||||
/nova/latest/vmstates.html 301 /nova/latest/reference/vm-states.html
|
/nova/latest/vmstates.html 301 /nova/latest/reference/vm-states.html
|
||||||
/nova/latest/wsgi.html 301 /nova/latest/user/wsgi.html
|
/nova/latest/wsgi.html 301 /nova/latest/user/wsgi.html
|
||||||
/nova/latest/user/cellsv2_layout.html 301 /nova/latest/user/cellsv2-layout.html
|
|
||||||
/nova/latest/user/placement.html 301 /placement/latest/
|
|
||||||
|
|
|
@ -61,8 +61,8 @@ VERSIONS = [
|
||||||
# hidden from the listing, but can still be requested explicitly, which is
|
# hidden from the listing, but can still be requested explicitly, which is
|
||||||
# required for testing purposes. We know this isn't great, but its inherited
|
# required for testing purposes. We know this isn't great, but its inherited
|
||||||
# from EC2, which this needs to be compatible with.
|
# from EC2, which this needs to be compatible with.
|
||||||
# NOTE(jichen): please update doc/source/user/metadata-service.rst on the
|
# NOTE(jichen): please update doc/source/user/metadata.rst on the metadata
|
||||||
# metadata output when new version is created in order to make doc up-to-date.
|
# output when new version is created in order to make doc up-to-date.
|
||||||
FOLSOM = '2012-08-10'
|
FOLSOM = '2012-08-10'
|
||||||
GRIZZLY = '2013-04-04'
|
GRIZZLY = '2013-04-04'
|
||||||
HAVANA = '2013-10-17'
|
HAVANA = '2013-10-17'
|
||||||
|
|
Loading…
Reference in New Issue