Open Stack

FWIW, we enumerated the use-cases and expected behavior for all
combinations of server [pre versions, older version, newer version]
and client [pre versions, older version, newer version, user-specified
version], in this "informational" spec:

http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html#proposed-change

Not all of that is implemented yet within our client, but the
auto-negotiation of version is done. While our clients probably don't
share any code, maybe something here can help:

http://git.openstack.org/cgit/openstack/python-ironicclient/tree/ironicclient/common/http.py#n72

-Deva

On Mon, Apr 27, 2015 at 2:49 AM, John Garbutt <john at johngarbutt.com> wrote:
> I see these changes as really important.
>
> We need to establish good patterns other SDKs can copy.
>
> On 24 April 2015 at 12:05, Alex Xu <soulxu at gmail.com> wrote:
>> 2015-04-24 18:15 GMT+08:00 Andrey Kurilin <akurilin at mirantis.com>:
>>> >When user execute cmd without --os-compute-version. The nova client
>>> > should discover the nova server >supported version. Then cmd choice the
>>> > latest version supported both by client and server.
>>>
>>> In that case, why X-Compute-API-Version can accept "latest" value? Also,
>>> such discovery will require extra request to API side for every client call.
>>>
>>
>> I think it is convenient for some case. like give user more easy to try nova
>> api by some code access the nova api directly. Yes, it need one more extra
>> request. But if without discover, we can't ensure the client support server.
>> Maybe client too old for server even didn't support the server's min
>> version. For better user experience, I think it worth to discover the
>> version. And we will call keystone each nova client cli call, so it is
>> acceptable.
>
> We might need to extend the API to make this easier, but I think we
> need to come up with a simple and efficient pattern here.
>
>
> Case 1:
> Existing python-novaclient calls, now going to v2.1 API
>
> We can look for the transitional entry of computev21, as mentioned
> above, but it seems fair to assume v2.1 and v2.0 are accessed from the
> same service catalog entry of "compute", by default (eventually).
>
> Lets be optimistic about what the cloud supports, and request "latest"
> version from v2.1.
>
> If its a v2.0 only API endpoint, we will not get back a version header
> with the response, we could error out if the user requested v2.x
> min_version via the CLI parameters.
>
> In most cases, we get the latest return values, and all is well.
>
>
> Case 2:
> User wants some info they know was added to the response in a specific
> microversion
>
> We can request "latest" and error out if we don't get a new enough
> version to meet the user's min requirement.
>
>
> Case 3:
> Adding support for a new request added in a microversion
>
> We could just send "latest" and assume the new functionality, then
> raise an error when you get bad request (or similar), and check the
> version header to see if that was the cause of the problem, so we can
> say why it failed.
>
> If its supported, everything just works.
>
> If the user requests a specific version before it was supported, we
> should error out as not supported, I guess?
>
> In a way it would be cleaner if we had a way for the client to say
> "latest but requires 2.3", so you get a bad version request if your
> minimum requirement is not respected, so its much clearer than
> miss-interpreting random errors that you might generate. But I guess
> its not totally required here.
>
>
> Would all that work? It should avoid an extra API call to discover the
> specific version we have available.
>
>>> >'--os-compute-version=None' can be supported, that means will return the
>>> > min version of server supported.
>>>
>>> From my point of view '--os-compute-version=None' is equal to not
>>> specified value. Maybe, it would be better to accept value "min" for
>>> os-compute-version option.
>>
>> I think '--os-compute-version=None' means not specified version request
>> header when send api request to server. The server behavior is if there
>> isn't value specified, the min version will be used.
>
> --os-compte-version=v2 means no version specified I guess?
>
> Can we go back to the use cases here please?
> What do the users need here and why?
>
>
>>> >3. if the microversion non-supported, but user call cmd with
>>> > --os-compute-version, this should return failed.
>>>
>>> Imo, it should be implemented on API side(return BadRequest when
>>> X-Compute-API-Version header is presented in V2)
>
> V2 is already deployed now, and doesn't do that.
>
> No matter what happens we need to fix that.
>>
>> Emm.... I'm not sure. Because GET '/v2/' already can be used to discover
>> microversion support or not. Sounds like add another way to support
>> discover? And v2 api didn't return fault with some extra header, that sounds
>> like behavior and back-incompatible change.
>
> -1
>
> We should not use the URL to detect the version.
> We have other ways to do that for a good reason.
>
> Thanks,
> John
>
>
>
>>> On Fri, Apr 24, 2015 at 12:42 PM, Alex Xu <soulxu at gmail.com> wrote:
>>>>
>>>>
>>>>
>>>> 2015-04-24 17:24 GMT+08:00 Andrey Kurilin <akurilin at mirantis.com>:
>>>>>
>>>>> Thank you for suggestions! I'll try modify patches as soon as possible.
>>>>
>>>>
>>>> np, it's better waiting for more comment before you begin to update the
>>>> code first. avoid you need rework again I think :)
>>>>
>>>>>
>>>>>
>>>>> On Fri, Apr 24, 2015 at 6:56 AM, Alex Xu <soulxu at gmail.com> wrote:
>>>>>>
>>>>>> Thanks Andrey for hard work on the microverison client support.
>>>>>>
>>>>>> Wrote down some my thought:
>>>>>>
>>>>>> I also agreed we will have only one endpoint 'compute'. Hope we can
>>>>>> switch v2.1 export as '/v2' in the api-paste.conf as default very soon~
>>>>>>
>>>>>> let's say what expected after we only have v2.1 in the world first:
>>>>>>
>>>>>> There are two cases for use nova client.
>>>>>> 1. user use nova client command line. I think command line should
>>>>>> support version discover. Provide most convenient way let the user try nova.
>>>>>> 2. user use nova client as library. user should call the client code to
>>>>>> discover the version and decided what version he want to use by himself.
>>>>>>
>>>>>> For the command line, the behavior can be:
>>>>>>
>>>>>> When user execute cmd without --os-compute-version. The nova client
>>>>>> should discover the nova server supported version. Then cmd choice the
>>>>>> latest version supported both by client and server. This is good for us to
>>>>>> introduce the new feature to the user.
>>>>>>
>>>>>> Also user can specified a version he want to by --os-compute-version.
>>>>>>
>>>>>> '--os-compute-version=None' can be supported, that means will return
>>>>>> the min version of server supported.
>>>>>>
>>>>>> The supported version can be discovered by version API (Thanks to
>>>>>> Ken'ichi fix this):
>>>>>> GET '/'
>>>>>>
>>>>>> https://github.com/openstack/nova/blob/master/doc/api_samples/versions/versions-get-resp.json#L25
>>>>>>
>>>>>> But reality is the v2 and v2.1 will existed at same time.
>>>>>>
>>>>>> So the v2 or v2.1 code both can run under the endpoint 'compute' with
>>>>>> url '/v2'. It depend on the admin's deployment.
>>>>>>
>>>>>> So I think the cmd also can discover whether the api supported
>>>>>> microversion under the 'compute' endpoint.
>>>>>>
>>>>>> This can be discovered by version api also.
>>>>>>
>>>>>> GET '/v2/' will return the endpoint version info. Then we can check the
>>>>>> version and min_version properties to know whether the api support
>>>>>> microversion or not.
>>>>>>
>>>>>> The behavior can be:
>>>>>> 1. If the microversion supported, the cmd behavior is same as the
>>>>>> description at the top of this mail
>>>>>> 2. If the microversion non-supported, user call cmd without
>>>>>> --os-compute-version, we use the min version.
>>>>>> 3. if the microversion non-supported, but user call cmd with
>>>>>> --os-compute-version, this should return failed.
>>>>>>
>>>>>> Hope those thoughts are helpful.
>>>>>>
>>>>>> Looks like this need some change in current patchset also :( I know
>>>>>> Andrey already pay lot of on this. But if we like this way, I also can give
>>>>>> some help on the coding :)
>>>>>>
>>>>>> Thanks
>>>>>> Alex
>>>>>>
>>>>>>
>>>>>> 2015-04-10 19:30 GMT+08:00 Andrey Kurilin <akurilin at mirantis.com>:
>>>>>>>
>>>>>>> Hi all!
>>>>>>> I working on implementation of support microversions in novaclient.
>>>>>>> Patches are ready for review, but there is one opened question: what we
>>>>>>> should do with v2.1 endpoint(computev21 service type)?
>>>>>>>
>>>>>>> "compute" is a default value of service type and keystone returns v2
>>>>>>> api endpoint for it(at least in devstack), so version header will be ignored
>>>>>>> on API side.
>>>>>>>
>>>>>>> On the one hand, each deployment can have it's own configuration of
>>>>>>> service catalog and endpoints, so default value of service type should be
>>>>>>> strict and support as much deployments as we can. On the other hand,
>>>>>>> dependency of service type for microversion feature is not good and
>>>>>>> end-users should not take care about choice of correct service type when
>>>>>>> they want to execute simple command.
>>>>>>>
>>>>>>> Possible solutions:
>>>>>>>
>>>>>>> leave everything as is: use "--service-type computev21" for each
>>>>>>> microversioned command
>>>>>>> move default value of service type to environment variables(default
>>>>>>> value is hardcoded in novaclient code now)
>>>>>>> add additional option --compute-api-type. Proposed etherpad by
>>>>>>> Christopher Yeoh
>>>>>>> https://etherpad.openstack.org/p/novaclient_microversions_design .
>>>>>>> Implementation is already finished -
>>>>>>> https://review.openstack.org/#/c/167577/ . This proposal still requires
>>>>>>> addition cli option, but compute-api-type looks more user-friendly
>>>>>>>
>>>>>>>
>>>>>>> Current implementation uses "compute" as default value for service
>>>>>>> type. Patches are pass all gates, except stable branches and ready for
>>>>>>> review:
>>>>>>>
>>>>>>> https://review.openstack.org/#/c/169378/  - deprecate v1.1 and remove
>>>>>>> references to v3 in code
>>>>>>> https://review.openstack.org/#/c/152569/  - Implements 'microversions'
>>>>>>> api type - Part 1 (usage of
>>>>>>> nova.api.openstack.api_version_request:APIVersionRequest class with
>>>>>>> https://review.openstack.org/#/c/169292/ )
>>>>>>> https://review.openstack.org/#/c/167408/  - Implements 'microversions'
>>>>>>> api type - Part 2 (adds new decorators and substitution mechanism using
>>>>>>> nova.api.openstack.versioned_method )
>>>>>>> https://review.openstack.org/#/c/136458/  - Implementation of 2.2
>>>>>>> microversion
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Best regards,
>>>>>>> Andrey Kurilin.
>>>>>>>
>>>>>>>
>>>>>>> __________________________________________________________________________
>>>>>>> OpenStack Development Mailing List (not for usage questions)
>>>>>>> Unsubscribe:
>>>>>>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>>>>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> __________________________________________________________________________
>>>>>> OpenStack Development Mailing List (not for usage questions)
>>>>>> Unsubscribe:
>>>>>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>>>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Best regards,
>>>>> Andrey Kurilin.
>>>>>
>>>>>
>>>>> __________________________________________________________________________
>>>>> OpenStack Development Mailing List (not for usage questions)
>>>>> Unsubscribe:
>>>>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>>>
>>>>
>>>>
>>>>
>>>> __________________________________________________________________________
>>>> OpenStack Development Mailing List (not for usage questions)
>>>> Unsubscribe:
>>>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>>
>>>
>>>
>>>
>>> --
>>> Best regards,
>>> Andrey Kurilin.
>>>
>>> __________________________________________________________________________
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>>
>>
>> __________________________________________________________________________
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev