Spec: Use keystoneauth1 Adapter for endpoints
Specification for blueprint use-ksa-adapter-for-endpoints. This spec follows on from blueprint use-service-catalog-for-endpoints (pike), which fell off waiting for dependencies to be ready. Change-Id: I504723a0c86a0bbdbda6252f72c8fbfde3b6b43a Implements: bp use-ksa-adapter-for-endpoints Previously-approved: Pike
This commit is contained in:
Eric Fried
287
specs/queens/approved/use-ksa-adapter-for-endpoints.rst
Normal file
287
specs/queens/approved/use-ksa-adapter-for-endpoints.rst
Normal file
@@ -0,0 +1,287 @@
|
||||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=======================================
|
||||
Use keystoneauth1 Adapter for endpoints
|
||||
=======================================
|
||||
|
||||
`<https://blueprints.launchpad.net/nova/+spec/use-ksa-adapter-for-endpoints>`_
|
||||
|
||||
Endpoint and version discovery via keystoneauth1.Adapter have come
|
||||
together in baked and usable form as of keystoneauth1 release 3.x.x, and
|
||||
there is a drive to use these mechanisms consistently any time endpoint
|
||||
discovery is needed. This effort aims to take advantage of Adapters to
|
||||
make endpoint discovery consistent across Nova for the various services
|
||||
it uses: identity (keystone), image (glance), block-storage (cinder),
|
||||
network (neutron), baremetal (ironic), key-manager (barbican), and
|
||||
placement.
|
||||
|
||||
.. note:: This is an evolving continuation of the effort begun via
|
||||
`blueprint use-service-catalog-for-endpoints`_.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
Nova uses configuration parameters for API endpoints from the ``nova.conf``
|
||||
file to communicate with other services within an OpenStack deployment.
|
||||
This set of services includes:
|
||||
|
||||
* identity (keystone)
|
||||
* image (glance)
|
||||
* block-storage (cinder)
|
||||
* network (neutron)
|
||||
* baremetal (ironic)
|
||||
* key-manager (barbican)
|
||||
* placement
|
||||
|
||||
Today, there are a number of disparate ways in which service endpoints
|
||||
are discovered and configured. For example, different services use
|
||||
different configuration keys for the same endpoint characteristic; e.g.
|
||||
the endpoint URL can be specified to:
|
||||
|
||||
* baremetal as a single URIOpt called ``[ironic]api_endpoint``
|
||||
* network as a single URIOpt called ``[neutron]url``
|
||||
* image as a ListOpt of URL strings called ``[glance]api_servers``
|
||||
(which is in fact the *only* way the image service endpoint can be
|
||||
set)
|
||||
* block-storage by a StrOpt template interpolated with values from the
|
||||
context object (``[cinder]endpoint_template``)
|
||||
* key-manager as a single StrOpt called ``[barbican]barbican_endpoint``
|
||||
* placement and identity not at all (no endpoint override is allowed)
|
||||
|
||||
The purpose of this effort is to expose within Nova a clean, consistent
|
||||
mechanism for endpoint discovery; and to use that mechanism for all of
|
||||
the services with which Nova communicates.
|
||||
|
||||
Use Cases
|
||||
---------
|
||||
|
||||
As an Operator, I want a consistent way to configure endpoint discovery
|
||||
for my services.
|
||||
|
||||
As a Developer maintaining code, I only want to learn one paradigm for
|
||||
service endpoint setup and configuration.
|
||||
|
||||
As a Developer creating code that communicates with a new service, I
|
||||
want to be able to employ the same paradigm as is used for other
|
||||
services.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
The keystoneauth1 library provides a simple and consistent way to
|
||||
configure endpoint discovery for a service. A consumer of keystoneauth1
|
||||
takes the following steps:
|
||||
|
||||
# In ``oslo_config`` setup, register conf options for keystoneauth1
|
||||
auth, Session, and Adapter objects via
|
||||
``keystoneauth1.loading.register_*_conf_options``.
|
||||
# Create an Adapter at runtime by chaining
|
||||
``keystoneauth1.loading.load_*_from_conf_options`` for auth, Session,
|
||||
and Adapter, supplying those methods with the registered conf group.
|
||||
(Alternatively, an existing auth and/or Session may be supplied to the
|
||||
Adapter loader.)
|
||||
# Use the resulting Adapter's discovery methods, such as
|
||||
``get_endpoint``, as needed.
|
||||
|
||||
.. note:: It is also possible to use the Adapter directly for
|
||||
communication with the REST service via standard methods
|
||||
(``get``, ``post``, etc.). Future efforts may be undertaken
|
||||
to eliminate custom per-service clients in favor of this
|
||||
mechanism.
|
||||
|
||||
From the Operator's perspective, this exposes a consistent way to
|
||||
configure service endpoints. For each service type, the configuration
|
||||
options have the same names and semantics. (For some service types, it
|
||||
may be possible to obtain auth from context, thereby eliminating the
|
||||
need for auth configuration.)
|
||||
|
||||
To make the Developer experience consistent, we propose to add a new
|
||||
method ``get_ksa_adapter()`` in Nova. To establish communication with
|
||||
any other service, Nova will call this method and use the resulting
|
||||
Adapter to discover endpoint data. This method will use the
|
||||
`service-types-authority`_ via `os-service-types`_ to map service type
|
||||
names to their respective conf groups based on project name (e.g.
|
||||
service type ``image`` maps to the ``glance`` project and therefore the
|
||||
``[glance]`` conf group).
|
||||
|
||||
.. note:: At some point in the future, there should be an effort to
|
||||
rename conf groups from project names to their respective
|
||||
service type names. That is outside the scope of this
|
||||
blueprint.
|
||||
|
||||
In the Queens cycle, the existing configuration options and discovery
|
||||
mechanisms will continue to be supported. If the legacy configuration
|
||||
option is specified, it will take precedence; otherwise, the new
|
||||
mechanism will be used. This is to ensure backwards compatibility and a
|
||||
smooth upgrade experience. However, the old style options will be
|
||||
deprecated in Queens and setting them will result in a warning being
|
||||
logged. The deprecated legacy endpoint options will be removed in the
|
||||
Rocky release.
|
||||
|
||||
The exception is ``[glance]api_servers``, which will continue to be
|
||||
supported. Operators need a way to specify a *list* of image service
|
||||
endpoints, and there is no such mechanism available via keystoneauth1
|
||||
Adapter.
|
||||
|
||||
If not otherwise specified via the ``valid_interfaces`` conf option,
|
||||
keystoneauth1 defaults to trying, in order, ``public``, ``internal``,
|
||||
``admin``. The Nova implementation will override the default to trying
|
||||
``internal``, then ``public``. (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
|
||||
the documentation attached to the conf options as exposed by
|
||||
keystoneauth1 shows examples using ``public``.)
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
None
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
|
||||
None
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
None
|
||||
|
||||
Notifications impact
|
||||
--------------------
|
||||
|
||||
None
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
None
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
With some configurations (e.g. if ``endpoint_override`` is not
|
||||
specified), endpoint discovery may entail additional API calls. Every
|
||||
effort will be made to limit these calls by caching the byproducts of
|
||||
the discovery (the Adapter objects, the resulting clients, etc.) such
|
||||
that, in the worst case, the impact will be felt once per service type
|
||||
per endpoint version.
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
The old endpoint configuration options, except for ``[glance]api_servers``,
|
||||
will be deprecated in Queens and removed in Rocky.
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
None
|
||||
|
||||
Upgrade impact
|
||||
--------------
|
||||
|
||||
A deployer upgrading to Queens is encouraged to transition her
|
||||
configurations to use the new endpoint discovery mechanisms described in
|
||||
this spec. However, not doing so should result in no immediate
|
||||
functional impacts. Any existing endpoint-related conf options will
|
||||
continue to work, but will begin to log deprecation warnings.
|
||||
Configuration sections with no endpoint related conf options should
|
||||
begin to use the new mechanisms seamlessly.
|
||||
|
||||
A deployer upgrading to Rocky will be *required* to transition to the
|
||||
new conf mechanisms. That impact will be further described in the Rocky
|
||||
follow-on to this effort.
|
||||
|
||||
There is no upgrade impact on any database or REST API. There are no
|
||||
externally-visible behavior changes.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
Eric Fried (efried@us.ibm.com)
|
||||
|
||||
Other contributors:
|
||||
None
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
- Add utilities for consistent conf setup. This is to centralize e.g.
|
||||
the override for ``valid_interfaces``.
|
||||
- Modify the conf setup files for the existing services to
|
||||
|
||||
- use these utilities and keystoneauth1.loading methods to register
|
||||
and list conf options for keystoneauth1 auth, Session, and Adapter
|
||||
objects.
|
||||
- deprecate the legacy options related to endpoint discovery (except
|
||||
for ``[glance]api_servers``).
|
||||
|
||||
- Add a utility method in Nova to create a keystoneauth1 Adapter from
|
||||
the conf.
|
||||
- Update Nova code using endpoints to exploit the new utility method if the
|
||||
legacy conf options are not specified.
|
||||
- (Rocky) Remove deprecated endpoint-related conf options, and the code
|
||||
branches that use them.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
* keystoneauth1 3.2.0 or later
|
||||
* os-service-types_ 1.1.0 or later
|
||||
* service-types-authority_ (This is the language-agnostic data
|
||||
repository backing os-service-types. It is not a pypi package, and
|
||||
has no place in the requirements project or Nova's
|
||||
``requirements.txt``.)
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
* Unit tests need to be added.
|
||||
* Patches will be proposed in devstack and the devstack setup of other
|
||||
projects which remove the legacy endpoint-related conf options and/or
|
||||
specify the new ones. These patches passing the various devstack
|
||||
gates will stand as proof that the new mechanisms work. (Some of
|
||||
these patches may eventually be merged, though that is not a
|
||||
requirement in the scope of this spec.)
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
* The sample conf file will be updated automatically by virtue of the
|
||||
changes to the various ``oslo_config`` setup modules.
|
||||
* The admin, user, and install guides for the affected services will be
|
||||
scrubbed for references to the affected configuration options.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
.. _service-types-authority: https://service-types.openstack.org/
|
||||
.. _os-service-types: https://github.com/openstack/os-service-types/blob/master/README.rst
|
||||
.. _`blueprint use-service-catalog-for-endpoints`: https://blueprints.launchpad.net/nova/+spec/use-service-catalog-for-endpoints
|
||||
|
||||
History
|
||||
=======
|
||||
|
||||
.. list-table:: Revisions
|
||||
:header-rows: 1
|
||||
|
||||
* - Release Name
|
||||
- Description
|
||||
* - Pike
|
||||
- Introduced (as `blueprint use-service-catalog-for-endpoints`_)
|
||||
* - Queens
|
||||
- Updated to reflect direction towards keystoneauth1 Adapter use
|
||||
Reference in New Issue
Block a user