Skip to content

Notes: Microversions

Jump to bottom
Carolyn Van Slyck edited this page Dec 17, 2015 · 7 revisions

Nova has switched to "microversions", instead of versioning the endpoint. Going forward the endpoint will always be /v2.1/, and if the client wants new features, they should specify the microversion in the request header, e.g. (X-OpenStack-Nova-API-Version: 2.6) to gain access to new features. Version 2.1 includes everything from 2.0, and extensions no longer exist. All 2.0 extensions are included in the official v2.1 API. Anytime someone makes a change to the API, rather than making an extension, the feature is associated with a new microversion number and is added to the official API.

Clients can then specify if they want to communicate using the old API (specifying nothing will get you 2.1) or using a more recent microversion.

The API docs are not yet in sync with the microversions and you can't tell from the API doc if a feature has been added/changed/removed in a microversion. Use the version history from the repository (second link below) as a guide for now.

The SDK needs to support a few scenarios:

  1. Single cloud user, has no idea what a microversion is and just wants to get the job done.
  2. Multi-cloud user, found a microversion that has what they want on multiple providers and they are sticking to it.
  3. Multi-cloud developer. Needs to know what is supported and easily fallback to other workarounds.

We want to make life easiest for 1 and 2, while not making 3's job impossible.

  • Each microversion is a different namespace, with all classes included, e.g. request/response objects, ComputeService, ComputeApiBuilder, etc.
  • Microversions are cumulative. 2.10 will include everything from 2.1-2.9 excluding deprecated items.
  • Classes in each microversion use inheritance (as things are cumulative). Most verisons will have nothing different except a method or property, everything else comes through via inheritance. For anything that has been removed, override, mark with Obsolete and EditorBrowsable(EditorBrowsableState.Never) so a user won't see them. Implement it by throwing a NotSupportedException with the microversion # referenced so that if it is invoked via sneaky means (e.g. reflection, crazy casting etc) that they understand why it failed.
  • User picks a namespace and they can use whatever they see in intellisense as long as they are connected to an OpenStack instance that supports the selected microversion. They don't see deprecated members and features from newer microversions are not visible to them.
  • #1 won't specify a microversion and will have access to everything in 2.1, but not in the microversions. At the moment, this gives them 99% of the Nova functionality.
  • #2 picks a microversion by specifying it once in a using directive and is done.
  • #3 will need to query the OpenStack instance for the range of supported microversions and react accordingly.

Examples

User #1 is using vanilla 2.1 without microversions:

using OpenStack.Compute.v2_1;

var computeService = new ComputeService(...);
var result = computeService.GetVncConsole("<serverId>", "novnc");

User #2 is using their preferred microversion, 2.6:

using OpenStack.Compute.v2_6;

var computeService = new ComputeService(...);
// user cannot use and does not see GetVncConsole as it has been deprecated.
// Instead they now see a new function that replaces it, GetRemoteConsole
var result = computeService.GetRemoteConsole("<serverId>", "vnc", "novnc");

User #3 needs to handle running their application against any microversion. This relies on redoing identity which is scheduled for 1.5.2.

using OpenStack.Identity;

var credentials = new Credentials("username", "project", "password");
var identity = new IdentityService(credentials);
var serviceCatalog = identity.GetServiceCatalog();
if(serviceCatalog.HasCompute(2.12) == true)
{
  var compute = serviceCatalog.BuildComputeService(2.12);
  compute.DoFancyStuff();
}
Clone this wiki locally