3abffb4fd7
Fix a disproportionally long line in dns-sd. Change-Id: I9137ce1780e971824bffdd4e6557ddeb44c4db0b
131 lines
4.9 KiB
ReStructuredText
131 lines
4.9 KiB
ReStructuredText
DNS-based Service Discovery
|
|
===========================
|
|
|
|
The normal way to discover OpenStack services is via the :doc:`service catalog
|
|
<consuming-catalog>`. However, in some edge cases it may be convenient to use
|
|
DNS-based discovery, for example:
|
|
|
|
#. Initial discovery of the Identity service endpoint via DNS.
|
|
#. Discovery of a service on the local network, especially in standalone case.
|
|
|
|
.. warning::
|
|
This guideline does not endorse any services to implement any DNS-based
|
|
discovery, but rather serves as guidance for services and deployments
|
|
that need it.
|
|
|
|
This guideline is heavily based on two IETF documents:
|
|
|
|
* `RFC 6763`_ defines DNS service discovery.
|
|
* `RFC 6762`_ defines the Multicast DNS protocol (or mDNS).
|
|
|
|
Service Type
|
|
------------
|
|
|
|
`RFC 6763`_ section 7 defines a fully qualified domain name for a service in
|
|
the following format::
|
|
|
|
<instance>.<servicename>._tcp.<domain>.
|
|
|
|
where:
|
|
|
|
``domain``
|
|
is a parent domain that the service belong to. It must be ``local`` for
|
|
multicast DNS.
|
|
``servicename``
|
|
is a service-specific protocol name, which in case of OpenStack API
|
|
discovery MUST be ``_openstack``.
|
|
``instance``
|
|
is an instance of a service, which in case of OpenStack API discovery MUST
|
|
be an OpenStack service type, such as ``compute``, ``identity`` or
|
|
``baremetal``. Project code names, such as ``nova``, MUST NOT be used.
|
|
|
|
Service Information
|
|
-------------------
|
|
|
|
The DNS ``SRV`` record will provide a host and port number for the service.
|
|
DNS ``TXT`` records SHOULD be used to communicate the remaining parts required
|
|
to access a service. `RFC 6763`_ defines the format of these records to be
|
|
key-value pairs separated by ``=``. This guideline defines the following keys:
|
|
|
|
``path``
|
|
SHOULD be used to specify the path part of the endpoint. If missing, ``/``
|
|
MUST be assumed.
|
|
|
|
.. note::
|
|
It's tempting to prefix the keys defined here with something like
|
|
``os_``, but ``path`` is used in the examples in `RFC 6763`_ in exactly
|
|
the same role, so it may be familiar enough to potential consumers
|
|
and tools.
|
|
``protocol``
|
|
SHOULD be used to specify whether to use HTTP or HTTPS. If present, it MUST
|
|
be ``http`` or ``https``. If absent, a consumer SHOULD use the port to
|
|
decide which protocol to use:
|
|
|
|
* if port is 80, use HTTP,
|
|
* if port is 443, use HTTPS,
|
|
|
|
If port is not one of 443 and 80, a consumer SHOULD try HTTPS and MAY fall
|
|
back to HTTP if it fails.
|
|
``txtvers``
|
|
SHOULD be used as defined in `RFC 6763`_ to designate the version of the
|
|
format. If present, its value MUST be ``1``.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Identity discovery for a provider
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
As a new user of OpenStack provider ``mystack.example.com``, I would like to
|
|
discover the ``auth_url`` to use.
|
|
|
|
I issue a DNS request to retrieve ``SRV`` and ``TXT`` records::
|
|
|
|
$ nslookup -query=any "identity._openstack._tcp.mystack.example.com"
|
|
identity._openstack._tcp.mystack.example.com service = 0 0 443 os.mystack.example.com
|
|
identity._openstack._tcp.mystack.example.com text = "txtvers=1" "path=/"
|
|
|
|
Now I know that I have to connect to ``os.mystack.example.com``, port 443.
|
|
From the ``TXT`` records I know that I should use the root path. The protocol
|
|
is not specified, so from port 443 I derive using HTTPS.
|
|
|
|
Result: ``auth_url`` is ``https://os.mystack.example.com/``.
|
|
|
|
Local discovery of ironic
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ironic service ramdisk needs to discover baremetal (ironic) and baremetal
|
|
introspection (ironic-inspector) API endpoints after start up. The service
|
|
catalog is not available to it.
|
|
|
|
The ramdisk issues a multicast DNS request to list OpenStack services. An
|
|
equivalent Avahi_ (FOSS mDNS and DNS-SD implementation) command would be::
|
|
|
|
$ avahi-browse -rt _openstack._tcp
|
|
+ eth1 IPv4 baremetal _openstack._tcp local
|
|
+ eth1 IPv4 baremetal-introspection _openstack._tcp local
|
|
= eth1 IPv4 baremetal _openstack._tcp local
|
|
hostname = [baremetal._openstack._tcp.local]
|
|
address = [192.168.42.17]
|
|
port = [80]
|
|
txt = ["proto=http" "path=/baremetal"]
|
|
= eth1 IPv4 baremetal-introspection _openstack._tcp local
|
|
hostname = [baremetal-introspection._openstack._tcp.local]
|
|
address = [192.168.42.17]
|
|
port = [5050]
|
|
txt = ["proto=http"]
|
|
|
|
Here we do a multicast search for all services matching service type
|
|
``_openstack._tcp`` defined in `Service Type`_. We receive two results for
|
|
the expected services, each containing an IP address, a TCP port and ``proto``
|
|
and ``path`` variables as part of its ``TXT`` section.
|
|
|
|
Result:
|
|
|
|
* The baremetal endpoint is ``http://192.168.42.17/baremetal``.
|
|
* The baremetal introspection endpoint is ``http://192.168.42.17:5050``.
|
|
|
|
.. _RFC 6763: https://www.ietf.org/rfc/rfc6763.txt
|
|
.. _RFC 6762: https://www.ietf.org/rfc/rfc6762.txt
|
|
.. _Avahi: https://avahi.org/
|