Cinder Client Automatic Microversion Selection

Registered by Justin A Wilson on 2016-11-18

==============================================
Cinder Client Automatic Microversion Selection
==============================================

============
Introduction
============

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
API.

========
Solution
========

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
microversion.

                        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.

==========
Conclusion
==========

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.

==========
References
==========

REST API Version History
http://docs.openstack.org/developer/cinder/devref/api_microversion_history.html

API Microversions for Operators- What? Why? and How?
https://www.youtube.com/watch?feature=player_embedded&v=7KdNiuf2f9s

API Microversions
http://docs.openstack.org/developer/cinder/devref/api_microversion_dev.html

Nova’s Kilo spec for microversions
http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/kilo/implemented/api-microversions.rst

Advanced Microversion Support - Client : Blueprints : python-manilaclient
https://blueprints.launchpad.net/python-manilaclient/+spec/manila-client-advanced-microversion-support

Various Discussions via IRC

Blueprint information

Status:
Not started
Approver:
Sean McGinnis
Priority:
Undefined
Drafter:
Justin A Wilson
Direction:
Needs approval
Assignee:
Justin A Wilson
Definition:
Pending Approval
Series goal:
None
Implementation:
Unknown
Milestone target:
None

Related branches

Sprints

Whiteboard

Gerrit topic: https://review.openstack.org/#q,topic:bp/cinder-client-automatic-microversion-selection,n,z

Addressed by: https://review.openstack.org/417169
    Cinder Client Automatic Microversion Negotiation

Gerrit topic: https://review.openstack.org/#q,topic:bug/1632872,n,z

Addressed by: https://review.openstack.org/385629
    Fix discover_version

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.