Updates for [glance]api_servers and ksa

The design for this blueprint has been fleshed out and discussed via IRC
and ML.  This change fleshes out some details with respect to specific
conf options and the source of those conf options (keystoneauth); and
also calls out that, unlike the other existing endpoint discovery conf
options, [glance]api_servers will continue to be supported.

Change-Id: I69909359b399283666e49ff2fe2d8622397648d5
Implements: bp use-service-catalog-for-endpoints

specs/pike/approved/use-service-catalog-for-endpoints.rst

@@ -26,7 +26,7 @@ Ideally, these API endpoints should not be hardcoded. We should have a simple
 and consistent way to retrieve these endpoint URLs in Nova.
 
 This spec focuses on using the Keystone service catalog to get API endpoints
-when Nova interacts with Cinder, Glance and Neutron.
+when Nova interacts with Cinder, Glance, Neutron, and others.
 
 The service catalog is composed of a list of services which represent services
 in an OpenStack deployment. Each service has one or more endpoints associated
@@ -48,44 +48,82 @@ It is useful to efficiently find information about services such as how to
 configure communication between services.
 
 Currently, Nova uses configuration settings from ``nova.conf`` file to get
-endpoint URL. Each service has url param in ``nova.conf`` which represents
-service endpoint. For example, in ``nova.conf``, there are many endpoints
-like::
+endpoint URLs. Each service has options in ``nova.conf`` which represent
+service endpoints or (e.g. in the case of cinder) ways to discover them.
+The option names and formats are different for each group. For example,
+in ``nova.conf``, there are options like::
 
    [glance]
-   api_servers = http://127.0.0.1:9292
+   api_servers = http://127.0.0.1:9292,http://glance2:9292
    [neutron]
    url = http://127.0.0.1:9696
+   [ironic]
+   api_endpoint = http://127.0.0.1:6385
+   [cinder]
+   catalog_info = volumev3:cinderv3:publicURL
 
-Keystoneauth provides a simple and consistent way to get API endpoints from
-the Keystone service catalog instead of configuring it in a conf file.
+Keystoneauth provides a simple and consistent way to get API endpoints from the
+Keystone service catalog instead of configuring it in a conf file.
 
-For example, the ``catalog_info = volume:cinder:public`` in nova.conf
-is a configuration setting to set the info to match when looking for cinder
-in the service catalog. Format used here is::
-
-   <service_type>:<service_name>:<interface>
-
-If should be noted that ``publicURL`` is the form that has been used up until
-now, but ``public`` is the keystone v3 version of interface. The config should
-accept both, but documentation should be updated to show examples using
-``public``.
-
-To make retrieving API endpoint consistent, we can add a new method
+To make retrieving API endpoints consistent, we can add a new method
 ``get_service_url()`` in Nova. To establish communication with any other
 service, Nova will call this method to find API endpoints.
 
 The method will first look at the existing configuration options such as
-``[glance]api_servers`` and use these options if they exist in the
-configuration file. This is to ensure backwards compatibility and a smooth
-upgrade experience. If the existing configuration option is *not* found or has
-no value, then the method will look up a specified API endpoint from the
-Keystone service catalog for a particular service type using ``keystoneauth``.
+``[neutron]url`` and use these options if they exist in the configuration file.
+This is to ensure backwards compatibility and a smooth upgrade experience.
 However, the old style options will be deprecated in Pike and setting them will
 result in a warning being logged. The old deprecated endpoint options will be
 removed in the Queens release.
 
-By adding this change, we will have consistent way to connect with other
+The exception is ``[glance]api_servers``, which will continue to be supported.
+Glance needs a way to specify a *list* of service endpoints, and there is no
+such mechanism available via the service catalog.
+
+If the existing configuration option is *not* found or has no value, then the
+method will look up the API endpoint corresponding to the conf group from the
+Keystone service catalog using ``keystoneauth``.
+
+Conf groups supporting ``get_service_url()`` will include the following set of
+options, based on ``keystonauth1.adapter.Adapter``:
+
+- ``service_type``
+- ``service_name``
+- ``interface``
+- ``region_name``
+- ``endpoint_override``
+
+If ``service_type`` is not supplied, a mapping from conf group name to
+corresponding service types will be consulted, and each will be tried
+successively until a result is found. (This mapping may be hardcoded
+initially, but should ultimately move to using ``os-client-config`` or
+``service-types-authority``.)
+
+For example, a subset of the default mapping might be::
+
+  {
+      'glance': ['image'],
+      'cinder': ['block-storage', 'volumev3', 'volumev2', 'volume'],
+      'ironic': ['baremetal'],
+      'neutron': ['network'],
+  }
+
+If ``get_service_url()`` is invoked for conf group ``cinder`` and
+``[cinder]service_type`` is empty or missing from the conf, the method will
+attempt lookup with ``service_type='block-storage'``, then
+``service_type='volumev3'``, etc.
+
+If ``interface`` is not supplied, ``internal``, ``admin``, and
+``public`` will be tried successively until a result is found. (It
+should be noted that ``publicURL`` is the form that has been used up
+until now, but ``public`` is the keystone v3 version of interface. The
+config should accept both, but documentation should be updated to show
+examples using ``public``.)
+
+Conf groups must also include keystone auth and session options, or may pass
+existing auth and/or session objects to ``get_service_url()``.
+
+By adding this change, we will have a consistent way to connect with other
 services from Nova.
 
 
@@ -127,8 +165,8 @@ None
 Other deployer impact
 ---------------------
 
-The old cinder/neutron/glance endpoint configuration options will be deprecated
-in Pike and removed in Queens.
+The old endpoint configuration options, except for ``[glance]api_servers``,
+will be deprecated in Pike and removed in Queens.
 
 Developer impact
 ----------------
@@ -150,17 +188,26 @@ Other contributors:
 Work Items
 ----------
 
-* Add a utility method in Nova to get endpoint from service catalog.
+- Add methods in ``keystoneauth1.loading`` to register and list ``Adapter``
+  conf options in a manner similar to those existing for session and auth.
+- Add a utility method in Nova to get endpoint from service catalog.
+- Update conf groups to include the ``Adapter`` conf options.
+- Update conf groups (except Glance) to deprecate existing endpoint-related
+  options.
+- Update Nova code using endpoints to exploit the new utility method if the
+  legacy conf options are not specified.
+- (Queens) Remove deprecated endpoint-related conf options, and the code
+  branches that use them.
 
 Dependencies
 ============
 
-None
+* Changes need to be coordinated between ``keystoneauth`` and ``nova``.
 
 Testing
 =======
 
-* Functional tests need to be added.
+* Unit tests need to be added.
 
 Documentation Impact
 ====================