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), 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
.)
A Note About Barbican¶
The Barbican configuration options are both supplied by and used from within
the castellan library. It may be possible to override/deprecate those options
from Nova to shoehorn them into conforming to the standard of the remainder of
this spec. However, the right way to make this happen is to have the castellan
project itself move toward common keystoneauth configuration. There will
therefore be no effort in the scope of this specification to “fix” the
[barbican]
or [key_manager]
conf sections.
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¶
History¶
Release Name |
Description |
---|---|
Pike |
Introduced (as blueprint use-service-catalog-for-endpoints) |
Queens |
Updated to reflect direction towards keystoneauth1 Adapter use |