Use keystoneauth1 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.
This is an evolving continuation of the effort begun via blueprint use-service-catalog-for-endpoints.
Nova uses configuration parameters for API endpoints from the
file to communicate with other services within an OpenStack deployment.
This set of services includes:
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
network as a single URIOpt called
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 (
key-manager as a single StrOpt called
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.
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.
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_configsetup, register conf options for keystoneauth1
auth, Session, and Adapter objects via
- # Create an Adapter at runtime by chaining
keystoneauth1.loading.load_*_from_conf_optionsfor 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.
It is also possible to use the Adapter directly for
communication with the REST service via standard methods
post, etc.). Future efforts may be undertaken
to eliminate custom per-service clients in favor of this
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
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.
image maps to the
glance project and therefore the
[glance] conf group).
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
If not otherwise specified via the
valid_interfaces conf option,
keystoneauth1 defaults to trying, in order,
admin. The Nova implementation will override the default to trying
public. (It should be noted that
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
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
[key_manager] conf sections.
Data model impact¶
REST API impact¶
Other end user 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
will be deprecated in Queens and removed in Rocky.
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.
- Primary assignee:
Eric Fried (email@example.com)
- Other contributors:
Add utilities for consistent conf setup. This is to centralize e.g. the override for
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
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.
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.)
The sample conf file will be updated automatically by virtue of the changes to the various
The admin, user, and install guides for the affected services will be scrubbed for references to the affected configuration options.
Introduced (as blueprint use-service-catalog-for-endpoints)
Updated to reflect direction towards keystoneauth1 Adapter use