What API microversion does OpenStackClient use?

I was recently asked the following question:

What Nova API microversion does OpenStackClient use when making requests to Nova?

The answer to this question doesn’t currently seem to appear anywhere in the OpenStackClient (OSC) documentation or man pages, so I’m going to note it here for posterity. The unfortunate answer is “it depends”. More specifically, it depends on which library OSC is using internally for the specific command. Is it python-novaclient or is it openstacksdk?

  • python-novaclient doesn’t support auto-negotiation and will use 2.1 by default. The user can override this using an explicit microversion or a 2.latest “magic” value. The 2.latest unfortunately doesn’t mean auto-negotiation: latest refers to the latest microversion that novaclient knows about, not the Nova server you’re talking to. If you were to use a novaclient release from the same release series as the Nova server you’re talking to, then things things would “magically” align. However, if you use a newer version of novaclient then things are liable to crash and burn with a “microversion not supported” error message.

  • openstacksdk does support auto-negotiation, so any commands implemented using this library will attempt to use either the maximum explicit version supported by the openstacksdk API implementation (each API, represented as a Resource object, specifies its own max microversion value) or the highest version supported by the server, whichever is lower. This isn’t perfect - we don’t currently encode a corresponding “minimum microversion” so it won’t necessarily bail correctly if you’re using a server that simply doesn’t support the given API and we haven’t implemented support for all microversions - but you can always override the version using --os-compute-api-version etc. if needed.

This generally applies for other services too, so calls to the block storage service that use python-cinderclient will not auto-negotiate while calls that have been migrated to use openstacksdk will. The sole exception to this (that I’m aware of) is Placement. The Placement OSC commands are provided by the osc-placement package, which provides its own API client implementation. This supports neither auto-negotiation nor a 1.latest magic value, so you’ll always need to manually specify an API version (via the --os-placement-api-version command line flag, OS_PLACEMENT_API_VERSION environment variable or placement_api_version option in clouds.yaml) if you want to use any API microversion other than 1.0. Hopefully we’ll eventually get Placement fully integrated into openstacksdk and auto-negotiation will be a thing.

comments powered by Disqus