api-sig/guidelines/dns-sd.rst

DNS-based Service Discovery

The normal way to discover OpenStack services is via the service catalog <consuming-catalog>. However, in some edge cases it may be convenient to use DNS-based discovery, for example:

1. Initial discovery of the Identity service endpoint via DNS.
2. 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.