Cinder Client Automatic Microversion Selection

Registered by Justin A Wilson

Cinder Client Automatic Microversion Selection


With the Nova, Manilla and Cinder projects implementing support for
microversions, the Openstack Client itself is not microversion aware and
present a "ease of use" issue when trying to use a feature that may or
may not be present in the currently running version of the cinder
service. Currently, this is not a issue for the Manilla project, because
its developers have implemented a auto-negotiation feature to
automatically call the highest api version of the service if available.
This is not the case for the Cinder client. In order for one
to make an api call to the Cinder service, at least the minimum
microversion at which the api call was implemented has be known at the
time of the api call. As of Cinder v3, the microversion must be provided
in the HTTP request header, otherwise it falls back to v3.0 which is
identical to v2.

The Problem

Currently, the caller of any API calls to the Cinder v3 API must know
the specific version of the API that they want to use. By default,
Cinder assumes that you meant to use 3.0 if no version is specified.
This behavior is likely to maintain backwards compatibility with the v2


The solution to this problem would be to query the version api, which is
present at each endpoint, for the current version of Cinder v3 API.
Then the version that is returned can be passed to the Cinder client if
it is compatible. This way the most currently available version of the
Cinder v3 API is always used.

Needed Changes

The current behavior is to fallback to v3.0 if no version is specifed.
This behavior will need to be changed to attempt to choose the highest
compatible version. If no version is compatiable, then fallback to
v3.0. A variable (MIN_SUPPORTED_VERSION ???) must be added to indicate
the minimum version that the current (MAX_VERSION) version of the client
can interact with. This minimum version variable must be elevated when a
backwards compatibility breaking change is introduced at a new

                        PCC = Python Cinder Client
Scenario A

API Versions |3.0 --- 3.1|
PCC Versions |3.0 -------- 3.2|

The client will use v3.1, but some API calls will not be available
(should 404). This case should really not be allowed, but is possible.

Scenario B

API Versions |3.3 --- 3.5|
PCC Versions |3.1 -------- 3.4|

The client will use v3.4 and all of the commands that were present a the
time of v3.4 will be available.

Scenario C

API Versions |3.6 --- 3.8|
PCC Versions |3.1 --- 3.3|

The client is not compatible, but the client will fallback to v3.0 to
maintain minimal functionality.


The solution detailed above will greatly simplify the use of the Cinder
python client with the v3 API by allowing not specifying a specific API
version and making use of the latest compatible version of the v3 api.
This will also allow the OpenStack client to make use of new features
of the Cinder API more easily as they become available in the future
if the user is running the latest version of the Cinder service.


REST API Version History

API Microversions for Operators- What? Why? and How?

API Microversions

Nova’s Kilo spec for microversions

Advanced Microversion Support - Client : Blueprints : python-manilaclient

Various Discussions via IRC

Blueprint information

Not started
Sean McGinnis
Justin A Wilson
Needs approval
Justin A Wilson
Pending Approval
Series goal:
Milestone target:

Related branches



Gerrit topic:,topic:bp/cinder-client-automatic-microversion-selection,n,z

Addressed by:
    Cinder Client Automatic Microversion Negotiation

Gerrit topic:,topic:bug/1632872,n,z

Addressed by:
    Fix discover_version


Work Items

This blueprint contains Public information 
Everyone can see this information.


No subscribers.