subject:"Re\: \[openstack\-dev\] \[nova\] Future of the Nova API"

 So I was thinking about this and Ken'ichi has basically said pretty
 much the same thing in his reply to this thread. I don't think it
 makes client moves any easier though - this is all about lowering our
 maintenance costs. 

So, in the other fork of this thread, I think you said we can't improve
v2 because we're concerned about its incredible fragility. The above
statement seems to imply that we can totally rewrite it as decorators on
top of v3? I don't get that :)

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 We may need to differentiate between breaking the API and breaking
 corner-case behavior.

Totally agreed.

 In one case you force everyone in the ecosystem to
 adapt (the libraries, the end user code). In the other you only
 (potentially) affect those that were not following the API correctly.

The problem is that the API spec is too loose right now, which is
definitely a problem. However, I think I'd much rather tighten things
down and deal with the potential fallout of someone's client breaking
and saying oh, I thought 'red' was a valid uuid than whole rewrites.

 We could make a V3 that doesn't break the API, only breaks behavior in
 error cases due to its stronger input validation. A V3 that shouldn't
 break code that was following the API, nor require heavy library
 changes. It's still a major API bump because behavior may change and
 some end users will be screwed in the process, but damage is more
 limited, so V2 could go away after a shorter deprecation period.

What's the difference between saying /v2 will return a 404 after K and
saying If your client doesn't declare support for revision 2 of these
calls we'll return a 405, 406, 410, etc? Actually, 412 seems to be
exactly this case.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-26 Thread Joe Gordon

On Wed, Feb 26, 2014 at 6:38 AM, Dan Smith d...@danplanet.com wrote:
 We may need to differentiate between breaking the API and breaking
 corner-case behavior.

 Totally agreed.

 In one case you force everyone in the ecosystem to
 adapt (the libraries, the end user code). In the other you only
 (potentially) affect those that were not following the API correctly.

 The problem is that the API spec is too loose right now, which is
 definitely a problem. However, I think I'd much rather tighten things
 down and deal with the potential fallout of someone's client breaking
 and saying oh, I thought 'red' was a valid uuid than whole rewrites.

quietly changing things sounds like a recipe for upset users.  There
are two contracts that we produce every time we release an API:

* The specs we document
* The actual implementation and all of its bugs and quirks.

Users actually care about the latter. If the API accepts 'red' as a
valid UUID then that is part of the implicit contract.

If we do go down this route of changing the v2 API like this, it would
be nice to bump the minor version as well, so when a user has to
distinguish between the two versions they don't have to say Havana V2
vs Icehouse V2, they can just say v2.1.

So Either way we should rev some version number when making these
changes, so we don't surprise the end users.


 We could make a V3 that doesn't break the API, only breaks behavior in
 error cases due to its stronger input validation. A V3 that shouldn't
 break code that was following the API, nor require heavy library
 changes. It's still a major API bump because behavior may change and
 some end users will be screwed in the process, but damage is more
 limited, so V2 could go away after a shorter deprecation period.

 What's the difference between saying /v2 will return a 404 after K and
 saying If your client doesn't declare support for revision 2 of these
 calls we'll return a 405, 406, 410, etc? Actually, 412 seems to be
 exactly this case.

 --Dan

 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 Users actually care about the latter. If the API accepts 'red' as a
 valid UUID then that is part of the implicit contract.

Yeah, but right now, many of those things are would fail on postgres
and succeed on mysql (not uuids necessarily, but others). Since we
can't honor them in all cases, I don't see the changes (versioned, for
warning) as quite so bad as the alternative. My point was that unless we
decide to stop working on the core, we're going to have minor changes
like that regardless. If we decide to freeze v2 and move to v3, then we
have to basically emulate those bugs _and_ maintain v3. If we version v2
and move forward, we;re in better shape, IMHO.

 If we do go down this route of changing the v2 API like this, it would
 be nice to bump the minor version as well, so when a user has to
 distinguish between the two versions they don't have to say Havana V2
 vs Icehouse V2, they can just say v2.1.

Yes, I'm totally all for introducing versioning into v2. Definitely.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-26 Thread Chris Behrens


This thread is many messages deep now and I’m busy with a conference this week, 
but I wanted to carry over my opinion from the other “v3 API in Icehouse” 
thread and add a little to it.

Bumping versions is painful. v2 is going to need to live for “a long time” to 
create the least amount of pain. I would think that at least anyone running a 
decent sized Public Cloud would agree, if not anyone just running any sort of 
decent sized cloud. I don’t think there’s a compelling enough reason to 
deprecate v2 and cause havoc with what we currently have in v3. I’d like us to 
spend more time on the proposed “tasks” changes. And I think we need more time 
to figure out if we’re doing versioning in the correct way. If we’ve got it 
wrong, a v3 doesn’t fix the problem and we’ll just be causing more havoc with a 
v4.

- Chris


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Wed, 26 Feb 2014 09:28:20 -0800
Dan Smith d...@danplanet.com wrote:
 
  If we do go down this route of changing the v2 API like this, it
  would be nice to bump the minor version as well, so when a user has
  to distinguish between the two versions they don't have to say
  Havana V2 vs Icehouse V2, they can just say v2.1.
 
 Yes, I'm totally all for introducing versioning into v2. Definitely.

So if we make backwards incompatible changes we really need a major
version bump. Minor versions don't cut it, because the expectation is
you have API stability within a major version.

How much do we like it when python libraries change semantic meaning
of methods or remote methods with just a minor library version
increment?

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Wed, 26 Feb 2014 11:40:25 +0100
Thierry Carrez thie...@openstack.org wrote:
 
 We may need to differentiate between breaking the API and breaking
 corner-case behavior. In one case you force everyone in the ecosystem
 to adapt (the libraries, the end user code). In the other you only
 (potentially) affect those that were not following the API correctly.
 
 So there may be a middle ground between sticking with dirty V2
 forever and Go to V3 and accept a long V2 deprecation:
 
 We could make a V3 that doesn't break the API, only breaks behavior in
 error cases due to its stronger input validation. A V3 that shouldn't
 break code that was following the API, nor require heavy library
 changes. It's still a major API bump because behavior may change and
 some end users will be screwed in the process, but damage is more
 limited, so V2 could go away after a shorter deprecation period.

So honestly I don't think there's much value in a V3 which doesn't break
the API. We really need to fix things like incorrect success return
codes. 

And I think from a user point of view changes which people are saying
the ones we don't need such as naming consistency are the ones which
are the easiest to fix. Its in many cases a simple search and replace
(maybe even with a script). If you have library of some sort in front
of the the rest of your code then it doesn't get far into your app. And
with the really strict input validation with V3 you'll get informed
straight away if you haven't done it all correctly.

However the most valuable changes are the hardest for an app to port
to. For example now receiving a 202 instead of a 200. All of sudden you
realise the call which you thought was synchronous is in fact async.
And that you really should be considering the cases where its slow or
fails. Or the cases where data you used to send is rejected because the
call never used it. You need to think about why you were sending that
extra information, and what you thought the call was doing with it,
that its now obviously not. 

These are things which require semantic changes in your code and are a
lot more costly. But we need to fix them so future users of the
API don't fall into the same traps. So given how much work users of the
API will have to do anyway it seems to make sense to include the minor
stuff at the same time too.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 So if we make backwards incompatible changes we really need a major
 version bump. Minor versions don't cut it, because the expectation is
 you have API stability within a major version.

I disagree. If the client declares support for it, I think we can very
reasonably return new stuff.

If we take what we have today in v2 and call that 2, then we could make
novaclient send this header:

  Accept: application/json;version=2

Then, we have a common method in the api code called
get_client_version(req), which returns 2 if it's missing, otherwise it
returns the version the client declared.

When we want to return something new, we do so only if
get_client_version(req) = 3. I think that if we did that, we could
support tasks in v2, properly, today.

If we _have_ to deprecate something (with the same care, concern, and
delay as we've previously proposed deprecating v2 in general) we can
return a proper HTTP status code if the client declares a crufty version
(or no version at all). The nice thing about that, is that we don't have
to deprecate all of v2 just to deprecate something we don't feel we can
support anymore for some good technical reason.

When we come along and decide that the API should really be organized
totally differently than it is today, such that a total rewrite makes
sense, we can do that and call it v3. However, for the level of change
that we've currently done in v3, I think the above would work just fine
and avoid the churn.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Wed, 26 Feb 2014 06:29:02 -0800
Dan Smith d...@danplanet.com wrote:
  So I was thinking about this and Ken'ichi has basically said pretty
  much the same thing in his reply to this thread. I don't think it
  makes client moves any easier though - this is all about lowering
  our maintenance costs. 
 
 So, in the other fork of this thread, I think you said we can't
 improve v2 because we're concerned about its incredible fragility.
 The above statement seems to imply that we can totally rewrite it as
 decorators on top of v3? I don't get that :)

So for starters we'd only do this once the V2 API is frozen. And I do
agree its carries significant. But there are ways we can reduce the risk
compared to attempting to backport into the V2 code. By taking this
approach we don't actually have to modify/remove the existing V2 code
until we know these decorators are right. Which means that people can
test it say via an experimental /v2.1 without actually losing /v2 and
tell us if we've got the corner cases that they rely upon wrong. That
is, we hopefully avoid the situation where we don't find these
incompatiblity issues when cloud providers start getting called up by
their customers complaining that apps which used to work, now
suddenly don't (and if its something their app does rarely it could
have been quite a time since the new code was deployed).

This sort of technique also keeps the v2 and v3 code separate which
reduces the complexity.

On a related matter during some of the IRC discussions the issue of AWS
supporting every version ever released was brought up and how they
manage to do this. It was suggested that for maintenance reasons what
they most likely do is only actually implement the most recent version
and just have compatibility layers to do translation. We could do
something similarly using the above technique, or as I'd prefer a proxy
service which sits in between which does V2-V3 translation. Again
something we'd do once V2 is frozen and have a ramp time to verify that
we've got the proxy right before it actually deploys.

Incidentally the former, but the latter especially removes the
maintenance burden within Nova that you are concerned about.

Chris.

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Wed, 26 Feb 2014 16:04:38 -0600
Chris Behrens cbehr...@codestud.com wrote:
 
 This thread is many messages deep now and I’m busy with a conference
 this week, but I wanted to carry over my opinion from the other “v3
 API in Icehouse” thread and add a little to it.
 
 Bumping versions is painful. v2 is going to need to live for “a long
 time” to create the least amount of pain. I would think that at least
 anyone running a decent sized Public Cloud would agree, if not anyone
 just running any sort of decent sized cloud. I don’t think there’s a
 compelling enough reason to deprecate v2 and cause havoc with what we
 currently have in v3. I’d like us to spend more time on the proposed
 “tasks” changes. And I think we need more time to figure out if we’re
 doing versioning in the correct way. If we’ve got it wrong, a v3
 doesn’t fix the problem and we’ll just be causing more havoc with a
 v4.

So I guess I agree tasks is something we should develop further and
that makes significant non backwards compatible changes to the API -
which is the major reason why we delayed V3. And its really important
that we get those changes right so we don't need a v4.

However, keeping V3 experimental indefinitely doesn't actually remove
the dual maintenance burden. The only way to do that is eventually
remove either the V2 or V3 version or do the suggested backport. 

We've pretty well established that starting a fresh v3 API is a
multi cycle effort. If we remove the V3 api code in Juno and then
start working on a new major version bump at a later date at say L or
M it'll be another multi cycle effort which I doubt would be
feasible, especially with people knowing there is the real risk at the
end that it'll just get thrown away. 

And the alternative of not removing V3 leaves the extra maintenance
burden. So whilst I agree with making sure we get it right but I'm
wondering exactly what you mean by taking more time to figure out
what we're doing - is it removing the V3 API code and just coping
with extra maintenance burden? Or removing it and then trying to do
a big multi cycle effort again a few cycles down the track?

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-26 Thread Chris Behrens

Again, just another quick response, but if we can find a way to merge v2 into 
the current v3 code, so that we don't have dual maintenance, that would be 
really nice.

 On Feb 26, 2014, at 5:15 PM, Christopher Yeoh cbky...@gmail.com wrote:
 
 On Wed, 26 Feb 2014 16:04:38 -0600
 Chris Behrens cbehr...@codestud.com wrote:
 
 This thread is many messages deep now and I’m busy with a conference
 this week, but I wanted to carry over my opinion from the other “v3
 API in Icehouse” thread and add a little to it.
 
 Bumping versions is painful. v2 is going to need to live for “a long
 time” to create the least amount of pain. I would think that at least
 anyone running a decent sized Public Cloud would agree, if not anyone
 just running any sort of decent sized cloud. I don’t think there’s a
 compelling enough reason to deprecate v2 and cause havoc with what we
 currently have in v3. I’d like us to spend more time on the proposed
 “tasks” changes. And I think we need more time to figure out if we’re
 doing versioning in the correct way. If we’ve got it wrong, a v3
 doesn’t fix the problem and we’ll just be causing more havoc with a
 v4.
 
 So I guess I agree tasks is something we should develop further and
 that makes significant non backwards compatible changes to the API -
 which is the major reason why we delayed V3. And its really important
 that we get those changes right so we don't need a v4.
 
 However, keeping V3 experimental indefinitely doesn't actually remove
 the dual maintenance burden. The only way to do that is eventually
 remove either the V2 or V3 version or do the suggested backport. 
 
 We've pretty well established that starting a fresh v3 API is a
 multi cycle effort. If we remove the V3 api code in Juno and then
 start working on a new major version bump at a later date at say L or
 M it'll be another multi cycle effort which I doubt would be
 feasible, especially with people knowing there is the real risk at the
 end that it'll just get thrown away. 
 
 And the alternative of not removing V3 leaves the extra maintenance
 burden. So whilst I agree with making sure we get it right but I'm
 wondering exactly what you mean by taking more time to figure out
 what we're doing - is it removing the V3 API code and just coping
 with extra maintenance burden? Or removing it and then trying to do
 a big multi cycle effort again a few cycles down the track?
 
 Chris
 
 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-26 Thread Alex Xu


On 2014年02月26日 18:40, Thierry Carrez wrote:

Kenichi Oomichi wrote:

From: Christopher Yeoh [mailto:cbky...@gmail.com]
So the problem here is what we consider a bug becomes a feature from
a user of the API point of view. Eg they really shouldn't be passing
some data in a request, but its ignored and doesn't cause any issues
and the request ends up doing what they expect.

In addition, current v2 API behavior is not consistent when receiving
unexpected API parameters. Most v2 APIs ignore unexpected API parameters,
but some v2 APIs return a BadRequest response. For example, update host
API does it in this case by 
https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/contrib/hosts.py#L185

Through v3 API development, we are making all v3 APIs return a BadRequest
in this case. I think we cannot apply this kind of strict validation to
running v2 API.

We may need to differentiate between breaking the API and breaking
corner-case behavior. In one case you force everyone in the ecosystem to
adapt (the libraries, the end user code). In the other you only
(potentially) affect those that were not following the API correctly.

So there may be a middle ground between sticking with dirty V2 forever
and Go to V3 and accept a long V2 deprecation:


Let us find the middle ground, how about this:

v3: This is the total new api. it's with CamelCase fixing, stronger 
input vaildation, api policy checks, and task api.


v2.1: This is based on v3, we transform the v2 request into v3 
request(then they are share same codebase). This api is without 
CamelCase fixing. And it get new thing from v3: stronger input 
vaildation, api policy checks, task api. We are keeping this api for 
long time. V2.1 didn't break the api. This api only affect those that 
were not following v2 api correctly.


v2: just go away after a shorter deprecation period.

So v3 and v2.1 based on same code, this is reduce the cost of 
maintenance. v2 is keeping for short time, give people a chance to move 
to v2.1 or v3.

And v2.1 didn't break the api, and it's more easy for maintenance.


We could make a V3 that doesn't break the API, only breaks behavior in
error cases due to its stronger input validation. A V3 that shouldn't
break code that was following the API, nor require heavy library
changes. It's still a major API bump because behavior may change and
some end users will be screwed in the process, but damage is more
limited, so V2 could go away after a shorter deprecation period.




___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-26 Thread Kenichi Oomichi

 -Original Message-
 From: Alex Xu [mailto:x...@linux.vnet.ibm.com]
 Sent: Thursday, February 27, 2014 11:44 AM
 To: openstack-dev@lists.openstack.org
 Subject: Re: [openstack-dev] [nova] Future of the Nova API

 On 2014年02月26日 18:40, Thierry Carrez wrote:
  Kenichi Oomichi wrote:
  Through v3 API development, we are making all v3 APIs return a BadRequest
  in this case. I think we cannot apply this kind of strict validation to
  running v2 API.

  We may need to differentiate between breaking the API and breaking
  corner-case behavior. In one case you force everyone in the ecosystem to
  adapt (the libraries, the end user code). In the other you only
  (potentially) affect those that were not following the API correctly.

  So there may be a middle ground between sticking with dirty V2 forever
  and Go to V3 and accept a long V2 deprecation:

 Let us find the middle ground, how about this:

 v3: This is the total new api. it's with CamelCase fixing, stronger
 input vaildation, api policy checks, and task api.

 v2.1: This is based on v3, we transform the v2 request into v3
 request(then they are share same codebase). This api is without
 CamelCase fixing. And it get new thing from v3: stronger input
 vaildation, api policy checks, task api. We are keeping this api for
 long time. V2.1 didn't break the api. This api only affect those that
 were not following v2 api correctly.

 v2: just go away after a shorter deprecation period.

 So v3 and v2.1 based on same code, this is reduce the cost of
 maintenance. v2 is keeping for short time, give people a chance to move
 to v2.1 or v3.
 And v2.1 didn't break the api, and it's more easy for maintenance.

I also have the similar idea.

The above v2.1 idea does not break the existing API request body format, and
also we need to translate v3 to v2 for API response.
According to https://wiki.openstack.org/wiki/NovaAPIv2tov3 , we have changed
API response(response code, response body) also in v3 API. So some response
translations also seem necessary. I think the scope of the translations should
contain successful access only, and it should not contain error access because
of low maintenance cost, strong input vaildation, and errors due to client-side.

Thanks
Ken'ichi Ohmichi

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-26 Thread Chris Friesen


On 02/26/2014 04:50 PM, Dan Smith wrote:

So if we make backwards incompatible changes we really need a major
version bump. Minor versions don't cut it, because the expectation is
you have API stability within a major version.


I disagree. If the client declares support for it, I think we can very
reasonably return new stuff.

If we take what we have today in v2 and call that 2, then we could make
novaclient send this header:

   Accept: application/json;version=2

Then, we have a common method in the api code called
get_client_version(req), which returns 2 if it's missing, otherwise it
returns the version the client declared.

When we want to return something new, we do so only if
get_client_version(req) = 3. I think that if we did that, we could
support tasks in v2, properly, today.


As I see it, you're not actually disagreeing with using a major version 
bump to deal with backwards incompatible changes.


What you're really suggesting is having the client explicitly send 
version support in a header, and if they don't then we would assume 
version 2.


I don't see how this is fundamentally different than a scheme where the 
path has v3 in it instead of v2.  The two are essentially 
equivalent, either way the client indicates which version it supports.


Chris


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Thu, 27 Feb 2014 03:38:25 +
Kenichi Oomichi oomi...@mxs.nes.nec.co.jp wrote:
  
  v3: This is the total new api. it's with CamelCase fixing, stronger
  input vaildation, api policy checks, and task api.
  
  v2.1: This is based on v3, we transform the v2 request into v3
  request(then they are share same codebase). This api is without
  CamelCase fixing. And it get new thing from v3: stronger input
  vaildation, api policy checks, task api. We are keeping this api for
  long time. V2.1 didn't break the api. This api only affect those
  that were not following v2 api correctly.

So the only thing I don't think we can really do for v2.1 is tasks.
Because the API we want is inherently backwards incompatible with v2.
We want to change what quite a few methods return.

Also there would be no XML support for v2.1 but its now marked as
deprecated so that is perhaps not an issue for the timeframe we are
discussing.

  
  v2: just go away after a shorter deprecation period.
  
  So v3 and v2.1 based on same code, this is reduce the cost of
  maintenance. v2 is keeping for short time, give people a chance to
  move to v2.1 or v3.
  And v2.1 didn't break the api, and it's more easy for maintenance.
 
 I also have the similar idea.
 
 The above v2.1 idea does not break the existing API request body
 format, and also we need to translate v3 to v2 for API response.
 According to https://wiki.openstack.org/wiki/NovaAPIv2tov3 , we have
 changed API response(response code, response body) also in v3 API. So
 some response translations also seem necessary. I think the scope of
 the translations should contain successful access only, and it should
 not contain error access because of low maintenance cost, strong
 input vaildation, and errors due to client-side.
 

Yep so we would also not be fixing success codes which are incorrect.
Error codes would change, but we do that in our 'stable' api anyway.

Yes so it comes back to an earlier suggestion I made around using
decorators for the v3 API that emulate v2 which would allow us to
mangle both the input and output. But in this case we don't need to
worry about the quirks because we're saying that sort of breakage is ok
(so risk is a lot lower, and verification much easier).  

I think the critical question here is how fast can we deprecate V2
once V2.1 is released? Is that any faster than a V2 to V3 deprecation
or do we have to support for V2 anyway for say 3 years?

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-26 Thread Thomas Duesing

Howdy!  I’m a Product Manager for Cloud Servers at Rackspace, and wanted to add 
a bit to what Behrens is saying.

At Rackspace, we’ve experienced something like this (if you squint and look at 
it sideways) in the operation of our non-OpenStack cloud (“first gen Cloud 
Servers”) alongside our OpenStack cloud (“next gen Cloud Servers”).  We 
introduced first gen Cloud Servers in 2008 and next gen in August of 2012, and 
we have yet to migrate off of our first gen platform.  When all is said and 
done, first gen and next gen Cloud Servers will probably coexist for three 
years.  And really, the timeline on this migration is driven by boring 
finance-y reasons like datacenter efficiency and operational costs - if we 
didn’t have that stuff to push us along, who knows how long first gen would be 
around.

Another thing we learned from our next gen launch is that most customers won’t 
self-migrate to a new and improved platform unless they see a whole bunch of 
real value.  Migrations are hard.  That is to say, Nova’s v3 API will have to 
provide tangible benefits to our customers before we implement it, much less 
migrate away from v2.  Full transparency: in talking with our customers, we’re 
not hearing them express problems that v3 solves.  (That’s not to say I don’t 
totally see where the v3 project is coming from and appreciate all the hard 
work that’s gone into it - I really do.)

Additionally, and this is has been touched on throughout this thread, we’ve got 
a lot of touch points internally and upstream before we would consider 
deprecating the v2 API: knowledge center articles, API documentation, SDKs (we 
officially contribute to/maintain at least seven), CLI clients, two mobile 
apps, mycloud.rackspace.com, my.rackspace.com, Heat, devops tools like 
knife-rackspace and vagrant-rackspace, our entire support floor, operations 
teams, etc.

I hope that helps shed a bit of light on how we’re thinking about this in the 
public cloud at Rackspace.

-Thomas Duesing


On Feb 26, 2014, at 4:04 PM, Chris Behrens cbehr...@codestud.com wrote:


This thread is many messages deep now and I’m busy with a conference this week, 
but I wanted to carry over my opinion from the other “v3 API in Icehouse” 
thread and add a little to it.

Bumping versions is painful. v2 is going to need to live for “a long time” to 
create the least amount of pain. I would think that at least anyone running a 
decent sized Public Cloud would agree, if not anyone just running any sort of 
decent sized cloud. I don’t think there’s a compelling enough reason to 
deprecate v2 and cause havoc with what we currently have in v3. I’d like us to 
spend more time on the proposed “tasks” changes. And I think we need more time 
to figure out if we’re doing versioning in the correct way. If we’ve got it 
wrong, a v3 doesn’t fix the problem and we’ll just be causing more havoc with a 
v4.

- Chris


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



smime.p7s
Description: S/MIME cryptographic signature
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Wed, 26 Feb 2014 14:50:46 -0800
Dan Smith d...@danplanet.com wrote:
 
 I disagree. If the client declares support for it, I think we can very
 reasonably return new stuff.
 
 If we take what we have today in v2 and call that 2, then we could
 make novaclient send this header:
 
   Accept: application/json;version=2
 
 Then, we have a common method in the api code called
 get_client_version(req), which returns 2 if it's missing, otherwise it
 returns the version the client declared.
 
 When we want to return something new, we do so only if
 get_client_version(req) = 3. I think that if we did that, we could
 support tasks in v2, properly, today.

So I think once we start returning different response codes, or
completely different structures (such as the tasks change will be), it
doesn't matter if we make the change in effect by invoking /v2 prefix
or /v3 prefix or we look for a header. Its a major api revision. I
don't think we should pretend otherwise.

The fact that clients have /v2 or /v3 hard coded is pretty much a
result of a failure on our part in the first place. The nova endpoint
examples for v2 should never have included the v2 prefix. And we should
always have been using a form of version discovery instead. 

 When we come along and decide that the API should really be organized
 totally differently than it is today, such that a total rewrite makes
 sense, we can do that and call it v3. However, for the level of change
 that we've currently done in v3, I think the above would work just
 fine and avoid the churn.

So doing the proposed backport of code to v2 is a huge amount of churn
also. A lot of the cost of the v3 churn is already paid. I think in this
thread we've discussed quite a few possible alternatives, some of which
I think would significantly reduce the dual maintenance concerns on nova
internals side (eg having a common layer that both v2 and v3 call into
when doing non trivial calls into nova internals). But none of those
alternatives seem to be acceptable, only the backport.

I think the backporting approach is a substantial amount of work,
which pretty much duplicates a lot of effort which has already been
done. It comparatively has a higher level of risk involved and leaves us
in the long term with a code base we don't want (multiple versions mixed
into the same method). So just who would be willing to step up to
commit to actually doing the work on this multi cycle effort?

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 21:15:30 -0500
Russell Bryant rbry...@redhat.com wrote:

 CC'ing the openstack-operators mailing list to get a wider set of
 feedback on this question.
 
 On 02/24/2014 05:26 PM, Christopher Yeoh wrote:
  1) Continue as we have been, and plan to release v3 once we have a
  compelling enough feature set.
  
  So I think we should release in Juno even if its only with tasks and
  nova-network added. Because this allows new users to start using the
  API immediately rather than having to code against V2 (with its
  extra barriers to use) and then take the hit to upgrade later.
 
 OK, let's go a bit further with the case of marking the v3 API stable
 in Juno.  If we did that, what is a reasonable timeframe of v2 being
 deprecated before it could be removed?

So this might a lot more complicated to answer, but I'd also be
interested in how much of the v2 API people actually use in practice
(both users and deployers). I suspect there's bits that are either
never or rarely used that we could perhaps deprecate earlier which
would reduce the test/maintenance load. quota-classes is an example
which has been in since early 2012 and we only recently realised that it
doesn't actually do anything useful and so removed it.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread John Garbutt

On 24 February 2014 18:11, Matt Riedemann mrie...@linux.vnet.ibm.com wrote:


 On 2/24/2014 10:13 AM, Russell Bryant wrote:

 On 02/24/2014 01:50 AM, Christopher Yeoh wrote:

 Hi,

 There has recently been some speculation around the V3 API and whether
 we should go forward with it or instead backport many of the changes
 to the V2 API. I believe that the core of the concern is the extra
 maintenance and test burden that supporting two APIs means and the
 length of time before we are able to deprecate the V2 API and return
 to maintaining only one (well two including EC2) API again.


 Yes, this is a major concern.  It has taken an enormous amount of work
 to get to where we are, and v3 isn't done.  It's a good time to
 re-evaluate whether we are on the right path.

 The more I think about it, the more I think that our absolute top goal
 should be to maintain a stable API for as long as we can reasonably do
 so.  I believe that's what is best for our users.  I think if you gave
 people a choice, they would prefer an inconsistent API that works for
 years over dealing with non-backwards compatible jumps to get a nicer
 looking one.

 The v3 API and its unit tests are roughly 25k lines of code.  This also
 doesn't include the changes necessary in novaclient or tempest.  That's
 just *our* code.  It explodes out from there into every SDK, and then
 end user apps.  This should not be taken lightly.

 This email is rather long so here's the TL;DR version:

 - We want to make backwards incompatible changes to the API
and whether we do it in-place with V2 or by releasing V3
we'll have some form of dual API support burden.
- Not making backwards incompatible changes means:
  - retaining an inconsistent API


 I actually think this isn't so bad, as discussed above.

  - not being able to fix numerous input validation issues


 I'm not convinced, actually.  Surely we can do a lot of cleanup here.
 Perhaps you have some examples of what we couldn't do in the existing API?

 If it's a case of wanting to be more strict, some would argue that the
 current behavior isn't so bad (see robustness principle [1]):

  Be conservative in what you do, be liberal in what you accept from
  others (often reworded as Be conservative in what you send, be
  liberal in what you accept).

 There's a decent counter argument to this, too.  However, I still fall
 back on it being best to just not break existing clients above all else.

  - have to forever proxy for glance/cinder/neutron with all
the problems that entails.


 I don't think I'm as bothered by the proxying as others are.  Perhaps
 it's not architecturally pretty, but it's worth it to maintain
 compatibility for our users.


 +1 to this, I think this is also related to what Jay Pipes is saying in his
 reply:


 Whether a provider chooses to, for example,
 deploy with nova-network or Neutron, or Xen vs. KVM, or support block
 migration for that matter *should have no effect on the public API*. The
 fact that those choices currently *do* effect the public API that is
 consumed by the client is a major indication of the weakness of the API.

 As a consumer, I don't want to have to know which V2 APIs work and which
 don't depending on if I'm using nova-network or Neutron.

Agreed, I thought thats why we are doing the proxying to neutron in
v2. We can't drop that.


- Backporting V3 infrastructure changes to V2 would be a
  considerable amount of programmer/review time


 Agreed, but so is the ongoing maintenance and development of v3.


 - The V3 API as-is has:
- lower maintenance
- is easier to understand and use (consistent).
- Much better input validation which is baked-in (json-schema)
  rather than ad-hoc and incomplete.


 So here's the rub ... with the exception of the consistency bits, none
 of this is visible to users, which makes me think we should be able to
 do all of this on v2.

 - Whilst we have existing users of the API we also have a lot more
users in the future. It would be much better to allow them to use
the API we want to get to as soon as possible, rather than trying
to evolve the V2 API and forcing them along the transition that they
could otherwise avoid.


 I'm not sure I understand this.  A key point is that I think any
 evolving of the V2 API has to be backwards compatible, so there's no
 forcing them along involved.

 - We already have feature parity for the V3 API (nova-network being
the exception due to the very recent unfreezing of it), novaclient
support, and a reasonable transition path for V2 users.

 - Proposed way forward:
- Release the V3 API in Juno with nova-network and tasks support
- Feature freeze the V2 API when the V3 API is released
  - Set the timeline for deprecation of V2 so users have a lot
of warning
  - Fallback for those who really don't want to move after
deprecation is an API service which translates between

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread John Garbutt

On 25 February 2014 06:11, Christopher Yeoh cbky...@gmail.com wrote:
 On Mon, 24 Feb 2014 17:37:04 -0800
 Dan Smith d...@danplanet.com wrote:

  onSharedStorage = True
  on_shared_storage = False

 This is a good example. I'm not sure it's worth breaking users _or_
 introducing a new microversion for something like this. This is
 definitely what I would call a purity concern as opposed to
 usability.

I thought micro versioning was so we could make backwards compatible changes.
If we make breaking changes we need to support the old and the new for
a little while.
I am tempted to say the breaking changes just create a new extension,
but there are other ways...

For return values:
* get new clients to send Accepts headers, to version the response
* this amounts to the major version
* for those request the new format, they get the new format
* for those getting the old format, they get the old format

For this case, on requests:
* we can accept both formats, or maybe that also depends on the
Accepts headers (with is a bit funky, granted).
* only document the new one
* maybe in two years remove the old format? maybe never?

Same for URLs, we could have the old a new names, with the new URL
always returning the new format (think instace_actions -
server_actions).

If the code only differers in presentation, that implies much less
double testing that two full versions of the API. It seems like we
could make some of these clean ups in, and keep the old version, with
relatively few changes.

We could port the V2 classes over to the V3 code, to get the code benefits.

Return codes are a bit harder, it seems odd to change those based on
Accepts headers, but maybe I could live with that.


Maybe this is the code mess we were trying to avoid, but I feel we
should at least see how bad this kind of approach would look?


 If it was just one case it wouldn't matter but when we're inconsistent
 across the whole API it is a usability issue because it makes it so
 much harder for a user of the API to learn it. They may for example
 remember that they need to pass a server id, but they also have to
 remember for a particular call whether it should be server_id,
 instance_uuid, or id. So referring to the documentation (assuming it is
 present and correct) becomes required even after using the API for an
 extended period of time. It also makes it much more error prone -
 simple typos are much less likely to be picked up by reviewers.

 Imagine we had to use a python library where sometimes the method and
 parameter names were in snake_case, others CamelCase. Sometimes a mix
 of the two in the same call. Sometimes it would refer to a widget as
 widget and other times you had to refer to it as thingy or the call
 failed. And if you passed the wrong parameters in it would sometimes
 just quietly ignore the bad ones and proceed as if everything was ok.

 Oh and other times it returned saying it had done the work you asked it
 to, when it really it meant I'll look at it, but it might not be able
 to (more on this below). I think most developers and reviewers would be
 banging their heads on their desks after a while.

I agree its a mess.

But rather than fork the code, can we find a better way of supporting
the old an new versions on a single (ideally cleaner) code base?

So users can migrate in their own timeframe, and we don't get a
complete maintenance nightmare in the process.

 Things like the twenty different datetime formats we expose _do_ seem
 worth the change to me as it requires the client to parse a bunch of
 different formats depending on the situation. However, we could solve
 that with very little code by just exposing all the datetimes again in
 proper format:

  {
   updated_at: %(random_weirdo)s,
   updated_at_iso: %(isotime)s,
  }

 Doing the above is backwards compatible and doesn't create code
 organizations based on any sort of pasta metaphor. If we introduce a
 discoverable version tag so the client knows if they will be
 available, I think we're good.

 Except we also now need to handle the case where both are passed in and
 end up disagreeing. And what about the user confusion where they see in
 most cases updated_at means one thing so they start assuming that it
 always means that, meaning they then get it wrong in the odd case out.
 Again, harder to code against, harder to review and is the unfortunate
 side effect of being too lax in what we accept.

I think accepts headers might help.

 URL inconsistencies seem not worth the trouble and I tend to think
 that the server vs. instance distinction probably isn't either,
 but I guess I'm willing to consider it.

 So again I think it comes down consistency increases usability - eg
 knowing that if you want to operate on a foo that you always access
 it through /foo rather than most of the time except for those cases when
 someone (almost certainly accidentally) ended up writing an interface
 where you modify a foo through /bar. The latter makes it much

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread John Garbutt

On 25 February 2014 09:44, Christopher Yeoh cbky...@gmail.com wrote:
 On Mon, 24 Feb 2014 21:15:30 -0500
 Russell Bryant rbry...@redhat.com wrote:

 CC'ing the openstack-operators mailing list to get a wider set of
 feedback on this question.

 On 02/24/2014 05:26 PM, Christopher Yeoh wrote:
  1) Continue as we have been, and plan to release v3 once we have a
  compelling enough feature set.
 
  So I think we should release in Juno even if its only with tasks and
  nova-network added. Because this allows new users to start using the
  API immediately rather than having to code against V2 (with its
  extra barriers to use) and then take the hit to upgrade later.

 OK, let's go a bit further with the case of marking the v3 API stable
 in Juno.  If we did that, what is a reasonable timeframe of v2 being
 deprecated before it could be removed?

 So this might a lot more complicated to answer, but I'd also be
 interested in how much of the v2 API people actually use in practice
 (both users and deployers). I suspect there's bits that are either
 never or rarely used that we could perhaps deprecate earlier which
 would reduce the test/maintenance load. quota-classes is an example
 which has been in since early 2012 and we only recently realised that it
 doesn't actually do anything useful and so removed it.

I think this is the big question.

I could see a chance of removing v2 after two years, maybe three
years. But two years is a long time to have the current two API code
bases, that are very similar, but a little bit different.

I think we need to find an alternative way to support the new and old
formats, like Accepts Headers, and retro-fitting a version to
extensions so we can easily advertise new attributes, to those parsers
that will break when they encounter those kinds of things.

Now I am tempted to say we morph the V3 code to also produce the V2
responses. And change the v3 API, so thats easier to do, and easier
for clients to move (like don't change URLs unless we really have to).
I know the risk for screwing that up is enormous, but maybe that makes
the most sense?

John

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread Thierry Carrez

Sean Dague wrote:
 So, that begs a new approach. Because I think at this point even if we
 did put out Nova v3, there can never be a v4. It's too much, too big,
 and doesn't fit in the incremental nature of the project. So whatever
 gets decided about v3, the thing that's important to me is a sane way to
 be able to add backwards compatible changes (which we actually don't
 have today, and I don't think any other service in OpenStack does
 either), as well a mechanism for deprecating parts of the API. With some
 future decision about whether removing them makes sense.

I agree with Sean. Whatever solution we pick, we need to make sure it's
solid enough that it can handle further evolutions of the Nova API
without repeating this dilemma tomorrow. V2 or V3, we would stick to it
for the foreseeable future.

Between the cleanup of the API, the drop of XML support, and including a
sane mechanism for supporting further changes without major bumps of the
API, we may have enough to technically justify v3 at this point. However
from a user standpoint, given the surface of the API, it can't be
deprecated fast -- so this ideal solution only works in a world with
infinite maintenance resources.

Keeping V2 forever is more like a trade-off, taking into account the
available maintenance resources and the reality of Nova's API huge
surface. It's less satisfying technically, especially if you're deeply
aware of the API incoherent bits, and the prospect of living with some
of this incoherence forever is not really appealing.

Choosing between the two is about (1) assessing if we would have the
resources to maintain V2 and V3 in parallel for some time, and (2)
evaluating how dirty the V2 API is, how much of it we could fix in a
backward-compatible manner, and if we are ready to live with the
remaining dirtiness forever.

-- 
Thierry Carrez (ttx)



signature.asc
Description: OpenPGP digital signature
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Tue, 25 Feb 2014 10:31:42 +
John Garbutt j...@johngarbutt.com wrote:

 On 25 February 2014 06:11, Christopher Yeoh cbky...@gmail.com wrote:
  On Mon, 24 Feb 2014 17:37:04 -0800
  Dan Smith d...@danplanet.com wrote:
 
   onSharedStorage = True
   on_shared_storage = False
 
  This is a good example. I'm not sure it's worth breaking users _or_
  introducing a new microversion for something like this. This is
  definitely what I would call a purity concern as opposed to
  usability.
 
 I thought micro versioning was so we could make backwards compatible
 changes. If we make breaking changes we need to support the old and
 the new for a little while.

Isn't the period that we have to support the old and the new for these
sorts of breaking the changes exactly the same period of time that we'd
have to keep V2 around if we released V3? Either way we're forcing
people off the old behaviour. 

 I am tempted to say the breaking changes just create a new extension,
 but there are other ways...

Oh, please no :-) Essentially that is no different to creating a new
extension in the v3 namespace except it makes the v2 namespace even
more confusing?

 For return values:
 * get new clients to send Accepts headers, to version the response
 * this amounts to the major version
 * for those request the new format, they get the new format
 * for those getting the old format, they get the old format
 
 For this case, on requests:
 * we can accept both formats, or maybe that also depends on the
 Accepts headers (with is a bit funky, granted).
 * only document the new one
 * maybe in two years remove the old format? maybe never?
 

So the idea of accept headers seems to me like just an alternative to
using a different namespace except a new namespace is much cleaner.

 Same for URLs, we could have the old a new names, with the new URL
 always returning the new format (think instace_actions -
 server_actions).
 
 If the code only differers in presentation, that implies much less
 double testing that two full versions of the API. It seems like we
 could make some of these clean ups in, and keep the old version, with
 relatively few changes.

As I've said before the API layer is very thin. Essentially most of it
is just about parsing the input, calling something, then formatting the
output. But we still do double testing even though the difference
between them most of the time is just presentation.  Theoretically if
the unittests were good enough in terms of checking the API we'd only
have to tempest test a single API but I think experience has shown that
we're not that good at doing exhaustive unittests. So we use the
fallback of throwing tempest at both APIs

 We could port the V2 classes over to the V3 code, to get the code
 benefits.

I'm not exactly sure what you mean here. If you mean backporting say
the V3 infrastructure so V2 can use it, I don't want people
underestimating the difficulty of that. When we developed the new
architecture we had the benefit of being able to bootstrap it without
it having to work for a while. Eg. getting core bits like servers and
images up and running without having to have the additional parts which
depend on it working with it yet. With V2 we can't do that, so
operating on a active system is going to be more difficult. The CD
people will not be happy with breakage :-)

But even then it took a considerable amount of effort - both coding and
review to get the changes merged, and that was back in Havana when it
was easier to review bandwidth. And we also discovered that especially
with that sort of infrastructure work its very difficult to get many
people working parallel - or even one person working on too many things
at one time. Because you end up in merge confict/rebase hell. I've been
there a lot in Havana and Icehouse.

 Return codes are a bit harder, it seems odd to change those based on
 Accepts headers, but maybe I could live with that.
 
 
 Maybe this is the code mess we were trying to avoid, but I feel we
 should at least see how bad this kind of approach would look?

So to me this approach really doesn't look a whole lot different to
just having a separate v2/v3 codebase in terms of maintenance. LOC
would be lower, but testing load is similar if we make the same sorts
of changes. Some things like input validation are a bit harder to
implement (because you need quite lax input validation for v2-old and
strict for v2-new).

Also how long are we going to spend on this sort of exploratory work?
The longer we take on it, the more we risk V3 slipping in Juno if we
take that route.

If we really need a super long deprecation period for V2 I'm going to
suggest again the idea of V2 proxy which translates to V3 speak and does
the necessary proxying. From a testing point of view we'd only need to
test that input and output of the proxy (ie correct V3 code requests are
emitted and correct V2 output is returned). And we already have tempest
tests for V2 which we could use for more general

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread Ken'ichi Ohmichi

2014-02-25 19:48 GMT+09:00 Thierry Carrez thie...@openstack.org:
 Sean Dague wrote:
 So, that begs a new approach. Because I think at this point even if we
 did put out Nova v3, there can never be a v4. It's too much, too big,
 and doesn't fit in the incremental nature of the project. So whatever
 gets decided about v3, the thing that's important to me is a sane way to
 be able to add backwards compatible changes (which we actually don't
 have today, and I don't think any other service in OpenStack does
 either), as well a mechanism for deprecating parts of the API. With some
 future decision about whether removing them makes sense.

 I agree with Sean. Whatever solution we pick, we need to make sure it's
 solid enough that it can handle further evolutions of the Nova API
 without repeating this dilemma tomorrow. V2 or V3, we would stick to it
 for the foreseeable future.

 Between the cleanup of the API, the drop of XML support, and including a
 sane mechanism for supporting further changes without major bumps of the
 API, we may have enough to technically justify v3 at this point. However
 from a user standpoint, given the surface of the API, it can't be
 deprecated fast -- so this ideal solution only works in a world with
 infinite maintenance resources.

 Keeping V2 forever is more like a trade-off, taking into account the
 available maintenance resources and the reality of Nova's API huge
 surface. It's less satisfying technically, especially if you're deeply
 aware of the API incoherent bits, and the prospect of living with some
 of this incoherence forever is not really appealing.

What is the maintenance cost for keeping both APIs?
I think Chris and his team have already paid most part of it, the
works for porting
the existing v2 APIs to v3 APIs is almost done.
So I'd like to clarify the maintenance cost we are discussing.

If the cost means that we should implement both API methods when creating a
new API, how about implementing internal proxy from v2 to v3 API?
When creating a new API, it is enough to implement API method for v3 API. and
when receiving a v2 request, Nova translates it to v3 API.
The request styles(url, body) of v2 and v3 are different and this idea makes new
v2 APIs v3 style. but now v2 API has already a lot of inconsistencies.
so it does not seem so big problem.


From the viewpoint of OpenStack interoperability also, I believe we
need a new API.
Many v2 API parameters are not validated. If implementing strict
validation for v2 API,
incompatibility issues happen. That is why we are implementing input
validation for
v3 API. If staying v2 API forever, we should have this kind of problem forever.
v2 API is fragile now. So the interoperability should depend on v2
API, that seems
sandbox.. (I know that it is a little overstatement, but we have found
a lot of this kind
of problem already..)


Thanks
Ken'ichi Ohmichi

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread Alex Xu


On 2014年02月25日 21:17, Ken'ichi Ohmichi wrote:

2014-02-25 19:48 GMT+09:00 Thierry Carrez thie...@openstack.org:

Sean Dague wrote:

So, that begs a new approach. Because I think at this point even if we
did put out Nova v3, there can never be a v4. It's too much, too big,
and doesn't fit in the incremental nature of the project. So whatever
gets decided about v3, the thing that's important to me is a sane way to
be able to add backwards compatible changes (which we actually don't
have today, and I don't think any other service in OpenStack does
either), as well a mechanism for deprecating parts of the API. With some
future decision about whether removing them makes sense.

I agree with Sean. Whatever solution we pick, we need to make sure it's
solid enough that it can handle further evolutions of the Nova API
without repeating this dilemma tomorrow. V2 or V3, we would stick to it
for the foreseeable future.

Between the cleanup of the API, the drop of XML support, and including a
sane mechanism for supporting further changes without major bumps of the
API, we may have enough to technically justify v3 at this point. However
from a user standpoint, given the surface of the API, it can't be
deprecated fast -- so this ideal solution only works in a world with
infinite maintenance resources.

Keeping V2 forever is more like a trade-off, taking into account the
available maintenance resources and the reality of Nova's API huge
surface. It's less satisfying technically, especially if you're deeply
aware of the API incoherent bits, and the prospect of living with some
of this incoherence forever is not really appealing.

What is the maintenance cost for keeping both APIs?
I think Chris and his team have already paid most part of it, the
works for porting
the existing v2 APIs to v3 APIs is almost done.
So I'd like to clarify the maintenance cost we are discussing.

If the cost means that we should implement both API methods when creating a
new API, how about implementing internal proxy from v2 to v3 API?
When creating a new API, it is enough to implement API method for v3 API. and
when receiving a v2 request, Nova translates it to v3 API.
The request styles(url, body) of v2 and v3 are different and this idea makes new
v2 APIs v3 style. but now v2 API has already a lot of inconsistencies.
so it does not seem so big problem.

I want to ask this question too. What is the maintenance cost?
When we release v3 api, we will freeze v2 api. So we won't add any new 
API into v2,

So is that mean the maintenance cost is much less after v2 api froze?
What I know is we should keep compute-api keep back-compatibility with 
v2 api. What

else except that?



From the viewpoint of OpenStack interoperability also, I believe we
need a new API.
Many v2 API parameters are not validated. If implementing strict
validation for v2 API,
incompatibility issues happen. That is why we are implementing input
validation for
v3 API. If staying v2 API forever, we should have this kind of problem forever.
v2 API is fragile now. So the interoperability should depend on v2
API, that seems
sandbox.. (I know that it is a little overstatement, but we have found
a lot of this kind
of problem already..)


Thanks
Ken'ichi Ohmichi

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev






___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread Sean Dague

On 02/25/2014 08:17 AM, Ken'ichi Ohmichi wrote:
2014-02-25 19:48 GMT+09:00 Thierry Carrez thie...@openstack.org:
Sean Dague wrote:
So, that begs a new approach. Because I think at this point even if we
did put out Nova v3, there can never be a v4. It's too much, too big,
and doesn't fit in the incremental nature of the project. So whatever
gets decided about v3, the thing that's important to me is a sane way to
be able to add backwards compatible changes (which we actually don't
have today, and I don't think any other service in OpenStack does
either), as well a mechanism for deprecating parts of the API. With some
future decision about whether removing them makes sense.

I agree with Sean. Whatever solution we pick, we need to make sure it's
solid enough that it can handle further evolutions of the Nova API
without repeating this dilemma tomorrow. V2 or V3, we would stick to it
for the foreseeable future.

Between the cleanup of the API, the drop of XML support, and including a
sane mechanism for supporting further changes without major bumps of the
API, we may have enough to technically justify v3 at this point. However
from a user standpoint, given the surface of the API, it can't be
deprecated fast -- so this ideal solution only works in a world with
infinite maintenance resources.

Keeping V2 forever is more like a trade-off, taking into account the
available maintenance resources and the reality of Nova's API huge
surface. It's less satisfying technically, especially if you're deeply
aware of the API incoherent bits, and the prospect of living with some
of this incoherence forever is not really appealing.

What is the maintenance cost for keeping both APIs?
I think Chris and his team have already paid most part of it, the
works for porting
the existing v2 APIs to v3 APIs is almost done.
So I'd like to clarify the maintenance cost we are discussing.

If the cost means that we should implement both API methods when creating a
new API, how about implementing internal proxy from v2 to v3 API?
When creating a new API, it is enough to implement API method for v3 API. and
when receiving a v2 request, Nova translates it to v3 API.
The request styles(url, body) of v2 and v3 are different and this idea makes
new
v2 APIs v3 style. but now v2 API has already a lot of inconsistencies.
so it does not seem so big problem.

From the viewpoint of OpenStack interoperability also, I believe we
need a new API.
Many v2 API parameters are not validated. If implementing strict
validation for v2 API,
incompatibility issues happen. That is why we are implementing input
validation for
v3 API. If staying v2 API forever, we should have this kind of problem
forever.
v2 API is fragile now. So the interoperability should depend on v2
API, that seems
sandbox.. (I know that it is a little overstatement, but we have found
a lot of this kind
of problem already..)

So I think this remains a good question about what keeping v2 forever
means. Because it does mean keeping the fact that we don't validate
input at the surface and depend on database specific errors to trickle
back up correctly. So if MySQL changes how it handles certain things,
you'll get different errors on the surface.

I'm gong to non-sequitor for a minute, because I think it's important to
step back some times.

What I want out of Nova API at the end of the day:

1. a way to discover what the API is

because this massively simplifies writing clients, SDKs, tests, and
documentation. All those pipelines are terribly manual, and have errors
in them because of it. Like has been said before you actually need to
read the Nova source code to figure out how to use parts of the API.

I think this is a great example of that -
https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api?utm_source=newsletterutm_medium=emailutm_campaign=januarynewslettermkt_tok=3RkMMJWWfF9wsRonuKzNZKXonjHpfsX57OQtX6SxlMI%2F0ER3fOvrPUfGjI4AScJrI%2BSLDwEYGJlv6SgFQrjAMapmyLgLUhE%3D

2. stop being optional

If we ever want interoperability between Nova implementations we need to
stop allowing the API to be optional. That means getting rid of
extensions. Content is either part of the Nova API, or it isn't in the
tree. Without this we'll never get an ecosystem around the API because
anything more complicated than basic server lifecycle is not guarunteed
to exist in an OpenStack implementation.

Extensions thus far have largely just been used as a cheat to get around
API compatibility changes based on the theory that users could list
extensions to figure out what the API would look like. It's a bad
theory, and not even nova command line does this. So users will get
errors on nova cli with clouds because features aren't enabled, and the
user has no idea why their commands don't work. Because it's right there
in the nova help.

3. a solid validation surface

We really need to be far more defensive on our API validation surface.
Right

Re: [openstack-dev] [nova] Future of the Nova API

 I thought micro versioning was so we could make backwards compatible changes.
 If we make breaking changes we need to support the old and the new for
 a little while.

Adding a new field alongside an old one in a structure that we return is
not a breaking change to me, IMHO. We can clean up the datestamp formats
that we return in that way: return both.

For datestamps that the client passes (are there any of these?) we don't
have to honor both and do conflict resolution if they disagree, we just
honor the new one, clearly.

 For return values:
 * get new clients to send Accepts headers, to version the response
 * this amounts to the major version
 * for those request the new format, they get the new format
 * for those getting the old format, they get the old format

Yes, I think this is quite reasonable. I honestly think that in most
cases we can avoid *ever* breaking the original return format without
the code turning into a mess, and I think that's what we should shoot for.

 We could port the V2 classes over to the V3 code, to get the code benefits.

Yes.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 I think we need to find an alternative way to support the new and old
 formats, like Accepts Headers, and retro-fitting a version to
 extensions so we can easily advertise new attributes, to those parsers
 that will break when they encounter those kinds of things.

Agreed.

 Now I am tempted to say we morph the V3 code to also produce the V2
 responses. And change the v3 API, so thats easier to do, and easier
 for clients to move (like don't change URLs unless we really have to).
 I know the risk for screwing that up is enormous, but maybe that makes
 the most sense?

It seems far easier to port the architectural awesomeness of v3 to v2 in
terms of code organization (which can be done without altering the
format), and then start extending v2 to support new formats that we
want. Trying to take a thing with a thousand small changes and add
support to optionally not send those small changes seems harder to me
than adding the important ones into v2. It will also help us revisit
what changes we want to make, and hopefully we would reconsider taking
on the versioning pain of a bunch of CamelCase changes :)

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 +1, seems would could explore for another cycle just to find out that
 backporting everything to V2 isn't going to be what we want, and now
 we've just wasted more time.

 If we say it's just deprecated and frozen against new features, then
 it's maintenance is just limited to bug fixes right?

No, any time we make a change to how the api communicates with compute,
conductor, or the scheduler, both copies of the API code have to be
changed. If we never get rid of v2 (and I don't think we have a good
reason to right now) then we're doing that *forever*. I do not want to
sign up for that.

I'm really curious what deployers like RAX, HP Cloud, etc think about
freezing V2 to features and having to deploying V3 to get them. Does RAX
expose V3 right now? Also curious if RAX/HP/etc see the V3 value
statement when compared to what it will mean for their users.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread Matt Riedemann




On Tuesday, February 25, 2014 4:02:13 PM, Dan Smith wrote:

+1, seems would could explore for another cycle just to find out that
backporting everything to V2 isn't going to be what we want, and now
we've just wasted more time.



If we say it's just deprecated and frozen against new features, then
it's maintenance is just limited to bug fixes right?


No, any time we make a change to how the api communicates with compute,
conductor, or the scheduler, both copies of the API code have to be
changed. If we never get rid of v2 (and I don't think we have a good
reason to right now) then we're doing that *forever*. I do not want to
sign up for that.


Yeah, so objects is the big one here.  And it doesn't sound like we're 
talking about getting rid of V2 *right now*, we're talking about 
deprecating it after V3 is released (plan would be Juno for 
nova-network and tasks) and then maintaining it for some amount of time 
before it could be removed, and it doesn't sound like we know what that 
number is until we get some input from deployers/operators.




I'm really curious what deployers like RAX, HP Cloud, etc think about
freezing V2 to features and having to deploying V3 to get them. Does RAX
expose V3 right now? Also curious if RAX/HP/etc see the V3 value
statement when compared to what it will mean for their users.


I'd also be interested to see what happens with the Keystone V2 API 
because as I understand it, it's deprecated already and there is no V3 
support in python-keystoneclient, that's all moved to 
python-openstackclient, which I don't think even Tempest is using yet, 
at least not for API tests.


So what kind of reaction are the Keystone people getting to that?  Do 
they plan on removing their V2 API at some point?  Or just maintain it 
with bug fixes forever?




--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



--

Thanks,

Matt Riedemann


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 Yeah, so objects is the big one here.

Objects, and everything else. With no-db-compute we did it for a couple
cycles, then objects, next it will be retooling flows to conductor, then
dealing with tasks, talking to gantt, etc. It's not going to end any
time soon.

 So what kind of reaction are the Keystone people getting to that?  Do
 they plan on removing their V2 API at some point?  Or just maintain it
 with bug fixes forever?

Yep, that would be good data. We also need to factor in the relative
deployment scale of nova installations vs. keystone installations in the
world (AFAIK, RAX doesn't use keystone for example).

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread Jay Pipes

On Tue, 2014-02-25 at 09:26 -0500, Sean Dague wrote:
 What I want out of Nova API at the end of the day:
 
 1. a way to discover what the API is
 
 because this massively simplifies writing clients, SDKs, tests, and
 documentation. All those pipelines are terribly manual, and have errors
 in them because of it. Like has been said before you actually need to
 read the Nova source code to figure out how to use parts of the API.

++

The key here, IMO, is to have JSON-Schema documents returned in the same
manner as Glance's v2 API and Heroku's API does, with separate schema
documents returned for each resource exposed in the API.

 2. stop being optional
 
 If we ever want interoperability between Nova implementations we need to
 stop allowing the API to be optional. That means getting rid of
 extensions. Content is either part of the Nova API, or it isn't in the
 tree. Without this we'll never get an ecosystem around the API because
 anything more complicated than basic server lifecycle is not guarunteed
 to exist in an OpenStack implementation.
 
 Extensions thus far have largely just been used as a cheat to get around
 API compatibility changes based on the theory that users could list
 extensions to figure out what the API would look like. It's a bad
 theory, and not even nova command line does this. So users will get
 errors on nova cli with clouds because features aren't enabled, and the
 user has no idea why their commands don't work. Because it's right there
 in the nova help.

No surprise... 100% agreement from me on this.

 3. a solid validation surface
 
 We really need to be far more defensive on our API validation surface.
 Right now bad data makes it far too far down the code stack. That's just
 a recipe for security issues.

++. WSME makes this kind of thing much more solid. What is/was the
status of WSME/Pecan integration in Nova?

Best,
-jay


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Tue, 25 Feb 2014 09:26:09 -0500
Sean Dague s...@dague.net wrote:

On 02/25/2014 08:17 AM, Ken'ichi Ohmichi wrote:
2014-02-25 19:48 GMT+09:00 Thierry Carrez thie...@openstack.org:
Sean Dague wrote:
So, that begs a new approach. Because I think at this point even
if we did put out Nova v3, there can never be a v4. It's too
much, too big, and doesn't fit in the incremental nature of the
project. So whatever gets decided about v3, the thing that's
important to me is a sane way to be able to add backwards
compatible changes (which we actually don't have today, and I
don't think any other service in OpenStack does either), as well
a mechanism for deprecating parts of the API. With some future
decision about whether removing them makes sense.

I agree with Sean. Whatever solution we pick, we need to make sure
it's solid enough that it can handle further evolutions of the
Nova API without repeating this dilemma tomorrow. V2 or V3, we
would stick to it for the foreseeable future.

Between the cleanup of the API, the drop of XML support, and
including a sane mechanism for supporting further changes without
major bumps of the API, we may have enough to technically justify
v3 at this point. However from a user standpoint, given the
surface of the API, it can't be deprecated fast -- so this ideal
solution only works in a world with infinite maintenance resources.

Keeping V2 forever is more like a trade-off, taking into account
the available maintenance resources and the reality of Nova's API
huge surface. It's less satisfying technically, especially if
you're deeply aware of the API incoherent bits, and the prospect
of living with some of this incoherence forever is not really
appealing.

If the cost means that we should implement both API methods when
creating a new API, how about implementing internal proxy from v2
to v3 API? When creating a new API, it is enough to implement API
method for v3 API. and when receiving a v2 request, Nova translates
it to v3 API. The request styles(url, body) of v2 and v3 are
different and this idea makes new v2 APIs v3 style. but now v2 API
has already a lot of inconsistencies. so it does not seem so big
problem.

From the viewpoint of OpenStack interoperability also, I believe we
need a new API.
Many v2 API parameters are not validated. If implementing strict
validation for v2 API,
incompatibility issues happen. That is why we are implementing input
validation for
v3 API. If staying v2 API forever, we should have this kind of
problem forever. v2 API is fragile now. So the interoperability
should depend on v2 API, that seems
sandbox.. (I know that it is a little overstatement, but we have
found a lot of this kind
of problem already..)

I'm gong to non-sequitor for a minute, because I think it's important
to step back some times.

What I want out of Nova API at the end of the day:

1. a way to discover what the API is

because this massively simplifies writing clients, SDKs, tests, and
documentation. All those pipelines are terribly manual, and have
errors in them because of it. Like has been said before you actually
need to read the Nova source code to figure out how to use parts of
the API.

So from what I understand I think the jsonschema work that Ken'ichi has
been working on for V3 goes a fair way in being able to support this
sort of thing. The jsonschema we'd be able to provide for V2 however is
a bit trickier as we'd have to leave the input validation pretty loose
(and probably in rather wierdly inconsistent ways because that's how
its implemented) in most cases.

Extensions thus far have largely just been used as a cheat to get
around API compatibility changes based on the theory that users could
list extensions to figure out what the API would look like. It's a bad
theory, and not even nova command line does this. So users will get
errors on nova cli with clouds because features aren't enabled, and
the user has no idea why their commands don't work. Because it's
right there

Re: [openstack-dev] [nova] Future of the Nova API

On Tue, 25 Feb 2014 14:47:16 -0800
Dan Smith d...@danplanet.com wrote:
  Yeah, so objects is the big one here.
 
 Objects, and everything else. With no-db-compute we did it for a
 couple cycles, then objects, next it will be retooling flows to
 conductor, then dealing with tasks, talking to gantt, etc. It's not
 going to end any time soon.

So I think there's some areas where I think the burden of making
changes to two APIs is very low. Take for example adding object support
for unrescue:

diff 
ec78b42d7b7e9da99ba0638a4f6d0aa7c8e5^..ec78b42d7b7e9da99ba0638a4f6d0aa7c8e5
 | diffstat
 api/openstack/compute/contrib/rescue.py|2 +-
 api/openstack/compute/plugins/v3/rescue.py |3 ++-
 compute/manager.py |   14 +++---
 compute/rpcapi.py  |   12 
 tests/compute/test_compute.py  |8 +---
 tests/compute/test_rpcapi.py   |2 +-
 6 files changed, 24 insertions(+), 17 deletions(-)

And the delta for the v2/v3 parts is:

diff --git a/nova/api/openstack/compute/contrib/rescue.py 
b/nova/api/openstack/compute/con
index fe31f2c..0233be2 100644
--- a/nova/api/openstack/compute/contrib/rescue.py
+++ b/nova/api/openstack/compute/contrib/rescue.py
@@ -75,7 +75,7 @@ class RescueController(wsgi.Controller):
 Unrescue an instance.
 context = req.environ[nova.context]
 authorize(context)
-instance = self._get_instance(context, id)
+instance = self._get_instance(context, id, want_objects=True)
 try:
 self.compute_api.unrescue(context, instance)
 except exception.InstanceInvalidState as state_error:
diff --git a/nova/api/openstack/compute/plugins/v3/rescue.py 
b/nova/api/openstack/compute/
index 5ae876b..66b4c17 100644
--- a/nova/api/openstack/compute/plugins/v3/rescue.py
+++ b/nova/api/openstack/compute/plugins/v3/rescue.py
@@ -77,7 +77,8 @@ class RescueController(wsgi.Controller):
 Unrescue an instance.
 context = req.environ[nova.context]
 authorize(context)
-instance = common.get_instance(self.compute_api, context, id)
+instance = common.get_instance(self.compute_api, context, id,
+   want_objects=True)
 try:
 self.compute_api.unrescue(context, instance)
 except exception.InstanceInvalidState as state_error:

eg a one line trivial change in a patch with
 6 files changed, 24 insertions(+), 17 deletions(-)

So in those specific cases I think the v2/v3 dual maintenance burden is very 
low.

But there are also other cases (such as some of the flavors apis) where
the extension basically does:

1. parse incoming data
2. call some flavor code
3. get what is returned and mangle it into a temporary data structure
4. format data for returning to the user

Now 1 and 4 are very v2 and v3 API specific. But 2 and 3 tend to be more
generic (this is not always the case with error paths etc) and do need to be
changed with object transition (and perhaps some of the other changes you are
talking about). eg foo['aaa'] - foo.aaa. Or adding want_objects=True to 
a method.

Now I still maintain that trying to squeeze both v2 and v3 parsing/formatting
into the same file/method is the wrong thing to do. But we could possibly
expand on nova/api/openstack/common.py and push cases where we can cases of
2 and 3 into it as common methods which the v2/v3 apis call down into.

This would reduce the amount of duplication which is required (I doubt
we could remove all duplication though) and whether its worth it for say
the rescue example is debatable. But for those cases you'd only need to make
the modification in one file.

However we would still have unittest and and tempest burden (I don't see
how we avoid that if we are ever going to fix the v2 API).

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Tue, 25 Feb 2014 10:37:14 +
John Garbutt j...@johngarbutt.com wrote:
 
 Now I am tempted to say we morph the V3 code to also produce the V2
 responses. And change the v3 API, so thats easier to do, and easier
 for clients to move (like don't change URLs unless we really have to).
 I know the risk for screwing that up is enormous, but maybe that makes
 the most sense?

So I was thinking about this and Ken'ichi has basically said pretty
much the same thing in his reply to this thread. I don't think it
makes client moves any easier though - this is all about lowering our
maintenance costs. 

So for the V3 API where the json/schema input validation patches have
merged, for static input validation (ie not things like does this
server exist) its all done in the decorator now, outside of actual
method. This makes the v3 API code much cleaner.

So I was pondering if its possible to write a decorator for v3 (not
json schema because we have to do some crazy stuff) that does the
equivalent of V2 input validation. Getting it right for perfectly good
input would not be that hard. But getting all the quirks of V2 just
right would be very tricky and error prone, with no tests.

Mind you, that's not a lot different from porting v3 back to v2 either.
There's also significant risk of accidentally changing the v2 API in a
way we don't intend.

But regardless I think its only something that would be feasible to
attempt once V2 is frozen. And only worth considering if the the
deprecation period for V2 is very long 2 years.

I think we do really need to get a better quantitative grip on what this
dual maintenance burden actually is. I don't think its too hard 
to measure the gate/check impact (more VMs please!) but in terms of
developer and review time overhead what do we think it will be and what
is acceptable and what isn't?

Because that needs to be somehow balanced against how long (hand wave)
that we'll have to keep dual support for and the developer cost and
review time to do any backport work. Plus throw in what sort of code
base we end up with in the end.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 This would reduce the amount of duplication which is required (I doubt
 we could remove all duplication though) and whether its worth it for say
 the rescue example is debatable. But for those cases you'd only need to make
 the modification in one file.

Don't forget the cases where the call chain changes -- where we end up
calling into conductor instead of compute, or changing how we fetch
complicated information (like BDMs) that we end up needing to send to
something complicated like the run_instance call. As we try to evolve
compute/api.py to do different things, the changes we have to drive into
the api/openstack/ code will continue.

However, remember I've maintained that I think we can unify a lot of the
work to make using almost the same code work for multiple ways of
accessing the API. I think it's much better to structure it as multiple
views into the same data. My concern with the v2 - v3 approach, is that
I think instead of explicitly duplicating 100% of everything and then
looking for ways to squash the two pieces back together, we should be
making calculated changes and supporting just the delta. I think that if
we did that, we'd avoid making simple naming and CamelCase changes as
I'm sure we'll try to avoid starting from v3. Why not start with v2?

We've already established that we can get a version from the client on
an incoming request, so why wouldn't we start with v2 and evolve the
important pieces instead of explicitly making the decision to break
everyone by moving to v3 and *then* start with that practice?

--Dan


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-25 Thread Kenichi Oomichi

-Original Message-
From: Christopher Yeoh [mailto:cbky...@gmail.com]
Sent: Wednesday, February 26, 2014 11:33 AM
To: openstack-dev@lists.openstack.org
Subject: Re: [openstack-dev] [nova] Future of the Nova API

On Tue, 25 Feb 2014 09:26:09 -0500
Sean Dague s...@dague.net wrote:

What I want out of Nova API at the end of the day:

1. a way to discover what the API is

because this massively simplifies writing clients, SDKs, tests, and
documentation. All those pipelines are terribly manual, and have
errors in them because of it. Like has been said before you actually
need to read the Nova source code to figure out how to use parts of
the API.

I think this is a great example of that -

https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api?utm_source=newsletterutm_medium=email
utm_campaign=januarynewslettermkt_tok=3RkMMJWWfF9wsRonuKzNZKXonjHpfsX57OQtX6SxlMI%2F0ER3fOvrPUfGjI4AScJrI%2BSLDwEY
GJlv6SgFQrjAMapmyLgLUhE%3D

So from what I understand I think the jsonschema work that Ken'ichi has
been working on for V3 goes a fair way in being able to support this
sort of thing.

Yes, right.
On the sample Sean pointed, the API reference documentation is being
maintained with using jsonschema. That is the best situation I hope for
Nova API documentation. We will be able to generate/get complete API
documentation with synchronizing the API implementation in this situation.

As the first step, I've proposed the API sample generator[1] which auto-
generates API sample files from API schema. I created a prototype[2], and
I've confirmed it is not so difficult to implement it.

The jsonschema we'd be able to provide for V2 however is a bit trickier
as we'd have to leave the input validation pretty loose (and probably in
rather wierdly inconsistent ways because that's how its implemented) in
most cases.

Right. If applying strict jsonschema validation to v2 API, the backward
incompatibility issues would happen. so we have to apply loose validation
to v2 API if we need it, but I am not sure that such v2 API validation is
worth.

= Current tensions =

Cloud providers want v2 for a long time (which, honestly, was news).
I'm not sure I completely know what that means. Are we talking about
the bug for bug surface that is today? Are we talking about not
wanting to change endpoints?

So the problem here is what we consider a bug becomes a feature from
a user of the API point of view. Eg they really shouldn't be passing
some data in a request, but its ignored and doesn't cause any issues
and the request ends up doing what they expect.

In addition, current v2 API behavior is not consistent when receiving
unexpected API parameters. Most v2 APIs ignore unexpected API parameters,
but some v2 APIs return a BadRequest response. For example, update host
API does it in this case by
https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/contrib/hosts.py#L185

Through v3 API development, we are making all v3 APIs return a BadRequest
in this case. I think we cannot apply this kind of strict validation to
running v2 API.

Thanks
ken'ichi Ohmichi

---
[1]:
http://lists.openstack.org/pipermail/openstack-dev/2014-February/026537.html
[2]: https://review.openstack.org/#/c/71465/

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Tue, 25 Feb 2014 20:52:14 -0800
Dan Smith d...@danplanet.com wrote:

  This would reduce the amount of duplication which is required (I
  doubt we could remove all duplication though) and whether its worth
  it for say the rescue example is debatable. But for those cases
  you'd only need to make the modification in one file.
 
 Don't forget the cases where the call chain changes -- where we end up
 calling into conductor instead of compute, or changing how we fetch
 complicated information (like BDMs) that we end up needing to send to
 something complicated like the run_instance call. As we try to evolve
 compute/api.py to do different things, the changes we have to drive
 into the api/openstack/ code will continue.

Sure, but won't most of those continue to be abstracted away by this
new common layer? Its not like the rework will expect any new data in
the request, or ultimately any new data returned in the request
(because these would all involve API changes).

 We've already established that we can get a version from the client on
 an incoming request, so why wouldn't we start with v2 and evolve the
 important pieces instead of explicitly making the decision to break
 everyone by moving to v3 and *then* start with that practice?

Because the V2 API code is really fragile which we want to keep stable.
And the cost of breaking it is high as we probably won't catch many
cases in the gate or review and we'll end up breaking clients when
providers deploy it. And so doing a backport is a huge amount of work
with a large amount of risk attached and compared to starting afresh
with the V3 work we'd be making infrastructure changes to a live, moving
target.

It's the same sorts of reasons that library developers on occasion
decide to release a new major version which knowingly are not backwards
compatible. Even if it means some sort of dual support for a period.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 02:06:50 -0500
Jay Pipes jaypi...@gmail.com wrote:

 On Mon, 2014-02-24 at 17:20 +1030, Christopher Yeoh wrote:
  - Proposed way forward:
- Release the V3 API in Juno with nova-network and tasks support
- Feature freeze the V2 API when the V3 API is released
  - Set the timeline for deprecation of V2 so users have a lot
of warning
  - Fallback for those who really don't want to move after
deprecation is an API service which translates between V2 and V3
requests, but removes the dual API support burden from Nova.
 
 And when do you think we can begin the process of deprecating the V3
 API and removing API extensions and XML translation support?

So did you mean V2 API here? I don't understand why you think the V3
API would need deprecating any time soon.

XML support has already been removed from the V3 API and I think the
patch to mark XML as deprecated for the V2 API and eventual removal in
Juno has already landed. So at least for part of the V2 API a one cycle
deprecation period has been seen as reasonable.

When it comes to API extensions I think that is actually more a
question of policy than anything else. The actual implementation behind
the scenes of a plugin architecture makes a lot of sense whether we
have extensions or not. It forces a good level of isolation between API
features and clarity of interaction where its needed - all of which
much is better from a maintenance point of view.

Now whether we have parts of the API which are optional or not is
really a policy decision as to whether we will force deployers to use
all of the plugins or a subset (eg currently the core). There is
the technical support for doing so in the V3 API (essentially what is
used to enforce the core of the API). And a major API version bump is
not required to change this. Perhaps this part falls in to the
DefCore discussions :-)

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 - We want to make backwards incompatible changes to the API
   and whether we do it in-place with V2 or by releasing V3
   we'll have some form of dual API support burden.

IMHO, the cost of maintaining both APIs (which are largely duplicated)
for almost any amount of time outweighs the cost of localized changes.

   - Not making backwards incompatible changes means:
 - retaining an inconsistent API
 - not being able to fix numerous input validation issues
 - have to forever proxy for glance/cinder/neutron with all
   the problems that entails.

The neutron stickiness aside, I don't see a problem leaving the proxying
in place for the foreseeable future. I think that it's reasonable to
mark them as deprecated, encourage people not to use them, and maybe
even (with a core api version to mark the change) say that they're not
supported anymore.

I also think that breaking our users because we decided to split A into
B and C on the backend kind of sucks. I imagine that continuing to do
that at the API layer (when we're clearly going to keep doing it on the
backend) is going to earn us a bit of a reputation.

   - Backporting V3 infrastructure changes to V2 would be a
 considerable amount of programmer/review time

While acknowledging that you (and others) have done that for v3 already,
I have to think that such an effort is much less costly than maintaining
two complete overlapping pieces of API code.

 - The V3 API as-is has:
   - lower maintenance
   - is easier to understand and use (consistent).
   - Much better input validation which is baked-in (json-schema)
 rather than ad-hoc and incomplete.

In case it's not clear, there is no question that the implementation of
v3 is technically superior in my mind. So, thanks for that :)

IMHO, it is also:

- twice the code
- different enough to be annoying to convert existing clients to use
- not currently different enough to justify the pain

 - Proposed way forward:
   - Release the V3 API in Juno with nova-network and tasks support
   - Feature freeze the V2 API when the V3 API is released
 - Set the timeline for deprecation of V2 so users have a lot
   of warning

This feels a lot like holding our users hostage in order to get them to
move. We're basically saying We tweaked a few things, fixed some
spelling errors, and changed some date stamp formats. You will have to
port your client, or no new features for you! That's obviously a little
hyperbolic, but I think that deployers of APIv2 would probably feel like
that's the story they have to give to their users.

 Firstly I'd like to step back a bit and ask the question whether we
 ever want to fix up the various problems with the V2 API that involve
 backwards incompatible changes. These range from inconsistent naming
 through the urls and data expected and returned, to poor and
 inconsistent input validation and removal of all the proxying Nova
 does to cinder, glance and neutron. I believe the answer to this is
 yes - inconsistencies in the API make it harder to use (eg do I have a
 instance or a server, and a project or a tenant just to name a
 couple) and more error prone and proxying has caused several painful to
 fix issues for us.

I naively think that we could figure out a way to move things forward
without having to completely break older clients. It's clear that other
services (with much larger and more widely-used APIs) are able to do it.

That said, I think the corollary to the above question is: do we ever
want to knowingly break an existing client for either of:

1. arbitrary user-invisible backend changes in implementation or
   service organization
2. purely cosmetic aspects like spelling, naming, etc

IMHO, we should do whatever we can to avoid breaking them except for the
most extreme cases.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 2014-02-24 at 20:22 +1030, Christopher Yeoh wrote:
 On Mon, 24 Feb 2014 02:06:50 -0500
 Jay Pipes jaypi...@gmail.com wrote:
 
  On Mon, 2014-02-24 at 17:20 +1030, Christopher Yeoh wrote:
   - Proposed way forward:
 - Release the V3 API in Juno with nova-network and tasks support
 - Feature freeze the V2 API when the V3 API is released
   - Set the timeline for deprecation of V2 so users have a lot
 of warning
   - Fallback for those who really don't want to move after
 deprecation is an API service which translates between V2 and V3
 requests, but removes the dual API support burden from Nova.
  
  And when do you think we can begin the process of deprecating the V3
  API and removing API extensions and XML translation support?
 
 So did you mean V2 API here? I don't understand why you think the V3
 API would need deprecating any time soon.

No, I meant v3.

 XML support has already been removed from the V3 API and I think the
 patch to mark XML as deprecated for the V2 API and eventual removal in
 Juno has already landed. So at least for part of the V2 API a one cycle
 deprecation period has been seen as reasonable.

OK, very sorry, I must have missed that announcement. I did not realize
that XML support had already been removed from v3.

 When it comes to API extensions I think that is actually more a
 question of policy than anything else. The actual implementation behind
 the scenes of a plugin architecture makes a lot of sense whether we
 have extensions or not. 

An API extension is not a plugin. And I'm not arguing against a plugin
architecture -- the difference is that a driver/plugin architecture
enables a single public API to have difference backend implementations.

Please see my diatribe on that here:

https://www.mail-archive.com/openstack-dev@lists.openstack.org/msg13660.html

 It forces a good level of isolation between API
 features and clarity of interaction where its needed - all of which
 much is better from a maintenance point of view.

Sorry, I have to violently disagree with you on that one. The API
extensions (in Nova, Neutron, Keystone, et al) have muddied the code
immeasurably and bled implementation into the public API -- something
that is antithetical to good public API design.

Drivers and plugins belong in the implementation layer. Not in the
public API layer.

 Now whether we have parts of the API which are optional or not is
 really a policy decision as to whether we will force deployers to use
 all of the plugins or a subset (eg currently the core). 

It's not about forcing providers to support all of the public API.
It's about providing a single, well-documented, consistent HTTP REST API
for *consumers* of that API. Whether a provider chooses to, for example,
deploy with nova-network or Neutron, or Xen vs. KVM, or support block
migration for that matter *should have no effect on the public API*. The
fact that those choices currently *do* effect the public API that is
consumed by the client is a major indication of the weakness of the API.

 There is
 the technical support for doing so in the V3 API (essentially what is
 used to enforce the core of the API). And a major API version bump is
 not required to change this. Perhaps this part falls in to the
 DefCore discussions :-)

I don't see how this discussion falls into the DefCore discussion.

Best,
-jay


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On 02/24/2014 01:50 AM, Christopher Yeoh wrote:
 Hi,
 
 There has recently been some speculation around the V3 API and whether
 we should go forward with it or instead backport many of the changes
 to the V2 API. I believe that the core of the concern is the extra
 maintenance and test burden that supporting two APIs means and the
 length of time before we are able to deprecate the V2 API and return
 to maintaining only one (well two including EC2) API again.

Yes, this is a major concern.  It has taken an enormous amount of work
to get to where we are, and v3 isn't done.  It's a good time to
re-evaluate whether we are on the right path.

The more I think about it, the more I think that our absolute top goal
should be to maintain a stable API for as long as we can reasonably do
so.  I believe that's what is best for our users.  I think if you gave
people a choice, they would prefer an inconsistent API that works for
years over dealing with non-backwards compatible jumps to get a nicer
looking one.

The v3 API and its unit tests are roughly 25k lines of code.  This also
doesn't include the changes necessary in novaclient or tempest.  That's
just *our* code.  It explodes out from there into every SDK, and then
end user apps.  This should not be taken lightly.

 This email is rather long so here's the TL;DR version:
 
 - We want to make backwards incompatible changes to the API
   and whether we do it in-place with V2 or by releasing V3
   we'll have some form of dual API support burden.
   - Not making backwards incompatible changes means:
 - retaining an inconsistent API

I actually think this isn't so bad, as discussed above.

 - not being able to fix numerous input validation issues

I'm not convinced, actually.  Surely we can do a lot of cleanup here.
Perhaps you have some examples of what we couldn't do in the existing API?

If it's a case of wanting to be more strict, some would argue that the
current behavior isn't so bad (see robustness principle [1]):

Be conservative in what you do, be liberal in what you accept from
others (often reworded as Be conservative in what you send, be
liberal in what you accept).

There's a decent counter argument to this, too.  However, I still fall
back on it being best to just not break existing clients above all else.

 - have to forever proxy for glance/cinder/neutron with all
   the problems that entails.

I don't think I'm as bothered by the proxying as others are.  Perhaps
it's not architecturally pretty, but it's worth it to maintain
compatibility for our users.

   - Backporting V3 infrastructure changes to V2 would be a
 considerable amount of programmer/review time

Agreed, but so is the ongoing maintenance and development of v3.

 
 - The V3 API as-is has:
   - lower maintenance
   - is easier to understand and use (consistent).
   - Much better input validation which is baked-in (json-schema)
 rather than ad-hoc and incomplete.

So here's the rub ... with the exception of the consistency bits, none
of this is visible to users, which makes me think we should be able to
do all of this on v2.

 - Whilst we have existing users of the API we also have a lot more
   users in the future. It would be much better to allow them to use
   the API we want to get to as soon as possible, rather than trying
   to evolve the V2 API and forcing them along the transition that they
   could otherwise avoid.

I'm not sure I understand this.  A key point is that I think any
evolving of the V2 API has to be backwards compatible, so there's no
forcing them along involved.

 - We already have feature parity for the V3 API (nova-network being
   the exception due to the very recent unfreezing of it), novaclient
   support, and a reasonable transition path for V2 users.
 
 - Proposed way forward:
   - Release the V3 API in Juno with nova-network and tasks support
   - Feature freeze the V2 API when the V3 API is released
 - Set the timeline for deprecation of V2 so users have a lot
   of warning
 - Fallback for those who really don't want to move after
   deprecation is an API service which translates between V2 and V3
   requests, but removes the dual API support burden from Nova.

One of my biggest principles with a new API is that we should not have
to force a migration with a strict timeline like this.  If we haven't
built something compelling enough to get people to *want* to migrate as
soon as they are able, then we haven't done our job.  Deprecation of the
old thing should only be done when we feel it's no longer wanted or used
by the vast majority.  I just don't see that happening any time soon.

We have a couple of ways forward right now.

1) Continue as we have been, and plan to release v3 once we have a
compelling enough feature set.

2) Take what we have learned from v3 and apply it to v2.  For example:

 - The plugin infrastructure is an internal implementation detail that
   can be done with the existing API.

 -

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Matt Riedemann




On 2/24/2014 10:13 AM, Russell Bryant wrote:

On 02/24/2014 01:50 AM, Christopher Yeoh wrote:

Hi,

There has recently been some speculation around the V3 API and whether
we should go forward with it or instead backport many of the changes
to the V2 API. I believe that the core of the concern is the extra
maintenance and test burden that supporting two APIs means and the
length of time before we are able to deprecate the V2 API and return
to maintaining only one (well two including EC2) API again.


Yes, this is a major concern.  It has taken an enormous amount of work
to get to where we are, and v3 isn't done.  It's a good time to
re-evaluate whether we are on the right path.

The more I think about it, the more I think that our absolute top goal
should be to maintain a stable API for as long as we can reasonably do
so.  I believe that's what is best for our users.  I think if you gave
people a choice, they would prefer an inconsistent API that works for
years over dealing with non-backwards compatible jumps to get a nicer
looking one.

The v3 API and its unit tests are roughly 25k lines of code.  This also
doesn't include the changes necessary in novaclient or tempest.  That's
just *our* code.  It explodes out from there into every SDK, and then
end user apps.  This should not be taken lightly.


This email is rather long so here's the TL;DR version:

- We want to make backwards incompatible changes to the API
   and whether we do it in-place with V2 or by releasing V3
   we'll have some form of dual API support burden.
   - Not making backwards incompatible changes means:
 - retaining an inconsistent API


I actually think this isn't so bad, as discussed above.


 - not being able to fix numerous input validation issues


I'm not convinced, actually.  Surely we can do a lot of cleanup here.
Perhaps you have some examples of what we couldn't do in the existing API?

If it's a case of wanting to be more strict, some would argue that the
current behavior isn't so bad (see robustness principle [1]):

 Be conservative in what you do, be liberal in what you accept from
 others (often reworded as Be conservative in what you send, be
 liberal in what you accept).

There's a decent counter argument to this, too.  However, I still fall
back on it being best to just not break existing clients above all else.


 - have to forever proxy for glance/cinder/neutron with all
   the problems that entails.


I don't think I'm as bothered by the proxying as others are.  Perhaps
it's not architecturally pretty, but it's worth it to maintain
compatibility for our users.


+1 to this, I think this is also related to what Jay Pipes is saying in 
his reply:


Whether a provider chooses to, for example,
deploy with nova-network or Neutron, or Xen vs. KVM, or support block
migration for that matter *should have no effect on the public API*. The
fact that those choices currently *do* effect the public API that is
consumed by the client is a major indication of the weakness of the API.

As a consumer, I don't want to have to know which V2 APIs work and which 
don't depending on if I'm using nova-network or Neutron.





   - Backporting V3 infrastructure changes to V2 would be a
 considerable amount of programmer/review time


Agreed, but so is the ongoing maintenance and development of v3.



- The V3 API as-is has:
   - lower maintenance
   - is easier to understand and use (consistent).
   - Much better input validation which is baked-in (json-schema)
 rather than ad-hoc and incomplete.


So here's the rub ... with the exception of the consistency bits, none
of this is visible to users, which makes me think we should be able to
do all of this on v2.


- Whilst we have existing users of the API we also have a lot more
   users in the future. It would be much better to allow them to use
   the API we want to get to as soon as possible, rather than trying
   to evolve the V2 API and forcing them along the transition that they
   could otherwise avoid.


I'm not sure I understand this.  A key point is that I think any
evolving of the V2 API has to be backwards compatible, so there's no
forcing them along involved.


- We already have feature parity for the V3 API (nova-network being
   the exception due to the very recent unfreezing of it), novaclient
   support, and a reasonable transition path for V2 users.

- Proposed way forward:
   - Release the V3 API in Juno with nova-network and tasks support
   - Feature freeze the V2 API when the V3 API is released
 - Set the timeline for deprecation of V2 so users have a lot
   of warning
 - Fallback for those who really don't want to move after
   deprecation is an API service which translates between V2 and V3
   requests, but removes the dual API support burden from Nova.


One of my biggest principles with a new API is that we should not have
to force a migration with a strict timeline like this.  If we haven't
built something

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 07:56:19 -0800
Dan Smith d...@danplanet.com wrote:

  - We want to make backwards incompatible changes to the API
and whether we do it in-place with V2 or by releasing V3
we'll have some form of dual API support burden.
 
 IMHO, the cost of maintaining both APIs (which are largely duplicated)
 for almost any amount of time outweighs the cost of localized changes.

The API layer is a actually quite a very thin layer on top of the rest
of Nova. Most of the logic in the API code is really just checking
incoming data, calling the underlying nova logic and then massaging
what is returned in the correct format. So as soon as you change the
format the cost of localised changes is pretty much the same as
duplicating the APIs. In fact I'd argue in many cases its more because
in terms of code readability its a lot worse and techniques like using
decorators for jsonschema for input validation are a lot harder to
implement. And unit and tempest tests still need to be duplicated.

 
 The neutron stickiness aside, I don't see a problem leaving the
 proxying in place for the foreseeable future. I think that it's
 reasonable to mark them as deprecated, encourage people not to use
 them, and maybe even (with a core api version to mark the change) say
 that they're not supported anymore.
 

I don't understand why this is also not seen as forcing people off V2
to V3 which is being given as a reason for not being able to set a
reasonable deprecation time for V2. This will require major changes for
people using the V2 API to change how they use it. 


 I also think that breaking our users because we decided to split A
 into B and C on the backend kind of sucks. I imagine that continuing
 to do that at the API layer (when we're clearly going to keep doing
 it on the backend) is going to earn us a bit of a reputation.

In all the discussions we've (as in the Nova group) had over the API
there has been a pretty clear consensus that proxying is quite
suboptimal (there are caching issues etc) and the long term goal is to
remove it from Nova. Why the change now? 

 
- Backporting V3 infrastructure changes to V2 would be a
  considerable amount of programmer/review time
 
 While acknowledging that you (and others) have done that for v3
 already, I have to think that such an effort is much less costly than
 maintaining two complete overlapping pieces of API code.

I strongly disagree here. I think you're overestimating the
amount of maintenance effort this involves and significantly
underestimating how much effort and review time a backport is going to
take.

 - twice the code
 - different enough to be annoying to convert existing clients to use
 - not currently different enough to justify the pain

For starters, It's not twice the code because we don't do things like
proxying and because we are able to logically separate out input
validation jsonschema. 

v2 API: ~14600 LOC
v3 API: ~7300 LOC (~8600 LOC if nova-network as-is added back in,
though the actually increase would almost certainly be a lot smaller)

And that's with a lot of the jsonschema patches not landed. So its
actually getting *smaller*. Long term which looks the better from a
maintenance point of view 

And I think you're continuing to look at it solely from the point of
view of pain for existing users of the API and not considering the pain
for new users who have to work out how to use the API. Eg just one
simple example, but how many people new to the API get confused about
what they are meant to send when it asks for instance_uuid when
they've never received one - is at server uuid - and if so what's the
difference? Do I have to do some sort of conversion? Similar issues
around project and tenant. And when writing code they have to remember
for this part of the API they pass it as server_uuid, in another
instance_uuid, or maybe its just id? All of these looked at
individually may look like small costs or barriers to using the API but
they all add up and they end up being imposed over a lot of people.

 This feels a lot like holding our users hostage in order to get them
 to move. We're basically saying We tweaked a few things, fixed some
 spelling errors, and changed some date stamp formats. You will have to
 port your client, or no new features for you! That's obviously a
 little hyperbolic, but I think that deployers of APIv2 would probably
 feel like that's the story they have to give to their users.

And how is say removing proxying or making *any* backwards incompatible
change any different? And this sort of situation is very common with
major library version upgrades. If you want new features you have to
port to the library version which requires changes to your app (that's
why its a major library version not a minor one).

 I naively think that we could figure out a way to move things forward
 without having to completely break older clients. It's clear that
 other services (with much larger and more widely-used APIs) are

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Morgan Fainberg

On the topic of backwards incompatible changes:

I strongly believe that breaking current clients that use the APIs directly is 
the worst option possible. All the arguments about needing to know which APIs 
work based upon which backend drivers are used are all valid, but making an API 
incompatible change when we’ve made the contract that the current API will be 
stable is a very bad approach. Breaking current clients isn’t just breaking 
“novaclient, it would also break any customers that are developing directly 
against the API. In the case of cloud deployments with real-world production 
loads on them (and custom development around the APIs) upgrading between major 
versions is already difficult to orchestrate (timing, approvals, etc), if we 
add in the need to re-work large swaths of code due to API changes, it will 
become even more onerous and perhaps drive deployers to forego the upgrades in 
lieu of stability.

If the perception is that we don’t have stable APIs (especially when we are 
ostensibly versioning them), driving adoption of OpenStack becomes 
significantly more difficult. Difficulty in driving further adoption would be a 
big negative to both the project and the community.

TL;DR, “don’t break the contract”. If we are seriously making incompatible 
changes (and we will be regardless of the direction) the only reasonable option 
is a new major version.
—
Morgan Fainberg
Principal Software Engineer
Core Developer, Keystone
m...@metacloud.com


On February 24, 2014 at 10:16:31, Matt Riedemann (mrie...@linux.vnet.ibm.com) 
wrote:



On 2/24/2014 10:13 AM, Russell Bryant wrote:  
 On 02/24/2014 01:50 AM, Christopher Yeoh wrote:  
 Hi,  
  
 There has recently been some speculation around the V3 API and whether  
 we should go forward with it or instead backport many of the changes  
 to the V2 API. I believe that the core of the concern is the extra  
 maintenance and test burden that supporting two APIs means and the  
 length of time before we are able to deprecate the V2 API and return  
 to maintaining only one (well two including EC2) API again.  
  
 Yes, this is a major concern. It has taken an enormous amount of work  
 to get to where we are, and v3 isn't done. It's a good time to  
 re-evaluate whether we are on the right path.  
  
 The more I think about it, the more I think that our absolute top goal  
 should be to maintain a stable API for as long as we can reasonably do  
 so. I believe that's what is best for our users. I think if you gave  
 people a choice, they would prefer an inconsistent API that works for  
 years over dealing with non-backwards compatible jumps to get a nicer  
 looking one.  
  
 The v3 API and its unit tests are roughly 25k lines of code. This also  
 doesn't include the changes necessary in novaclient or tempest. That's  
 just *our* code. It explodes out from there into every SDK, and then  
 end user apps. This should not be taken lightly.  
  
 This email is rather long so here's the TL;DR version:  
  
 - We want to make backwards incompatible changes to the API  
 and whether we do it in-place with V2 or by releasing V3  
 we'll have some form of dual API support burden.  
 - Not making backwards incompatible changes means:  
 - retaining an inconsistent API  
  
 I actually think this isn't so bad, as discussed above.  
  
 - not being able to fix numerous input validation issues  
  
 I'm not convinced, actually. Surely we can do a lot of cleanup here.  
 Perhaps you have some examples of what we couldn't do in the existing API?  
  
 If it's a case of wanting to be more strict, some would argue that the  
 current behavior isn't so bad (see robustness principle [1]):  
  
 Be conservative in what you do, be liberal in what you accept from  
 others (often reworded as Be conservative in what you send, be  
 liberal in what you accept).  
  
 There's a decent counter argument to this, too. However, I still fall  
 back on it being best to just not break existing clients above all else.  
  
 - have to forever proxy for glance/cinder/neutron with all  
 the problems that entails.  
  
 I don't think I'm as bothered by the proxying as others are. Perhaps  
 it's not architecturally pretty, but it's worth it to maintain  
 compatibility for our users.  

+1 to this, I think this is also related to what Jay Pipes is saying in  
his reply:  

Whether a provider chooses to, for example,  
deploy with nova-network or Neutron, or Xen vs. KVM, or support block  
migration for that matter *should have no effect on the public API*. The  
fact that those choices currently *do* effect the public API that is  
consumed by the client is a major indication of the weakness of the API.  

As a consumer, I don't want to have to know which V2 APIs work and which  
don't depending on if I'm using nova-network or Neutron.  

  
 - Backporting V3 infrastructure changes to V2 would be a  
 considerable amount of programmer/review time  
  
 Agreed, but so is the

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 11:13:11 -0500
Russell Bryant rbry...@redhat.com wrote:
 
 Yes, this is a major concern.  It has taken an enormous amount of work
 to get to where we are, and v3 isn't done.  It's a good time to
 re-evaluate whether we are on the right path.

So I think its important to point out that we pretty much were done
before the last minute nova-network unfreezing which became a new
requirement for V3 in I-3. And the unfortunate unexpected delay in the
tasks API work. If either of those hadn't occurred we could have made
up the difference in I-3 - and even then we *could* have made it
but for I think reasonable risk purposes in trying to merge a lot of
code at the last minute decided to delay.

 The more I think about it, the more I think that our absolute top goal
 should be to maintain a stable API for as long as we can reasonably do
 so.  I believe that's what is best for our users.  I think if you gave
 people a choice, they would prefer an inconsistent API that works for
 years over dealing with non-backwards compatible jumps to get a nicer
 looking one.
 
 The v3 API and its unit tests are roughly 25k lines of code.  This
 also doesn't include the changes necessary in novaclient or tempest.
 That's just *our* code.  It explodes out from there into every SDK,
 and then end user apps.  This should not be taken lightly.

So the v2 API and its unit tests are around 43k LOC. And this is even
with the v3 API having more tests for the better input validation we do.

Just taking this down to burden in terms of LOC (and this may be one
of the worst metrics ever). If we proceeded with the v3 API and
maintained the V2 API for say 4 cycles, thats and extra burden of 100k
LOC compared to just doing the v2 API. But we'd pay that off in just 2
and a bit cycles once the the v2 API is removed because we'd now be
maintaining around 25k LOC instead of 43k LOC.

 
 If it's a case of wanting to be more strict, some would argue that the
 current behavior isn't so bad (see robustness principle [1]):
 
 Be conservative in what you do, be liberal in what you accept
 from others (often reworded as Be conservative in what you send, be
 liberal in what you accept).

Sometimes the problem is that people send extraneous data and they're
never told that what they're doing is wrong. But really no harm
caused, everything still works. I'm sure there are plenty of examples
of this happening. 

But the bigger issue around input validation being too lax is
that people send optional parameters (perhaps with a typo, or perhaps
simply in the wrong place) and the API layer quietly ignores them. The
users think they've requested some behaviour, the API says yep,
sure!, but it doesn't actually do what they want. We've even seen
this sort of thing in our api samples which automatically flows through
to our documentation!

 There's a decent counter argument to this, too.  However, I still fall
 back on it being best to just not break existing clients above all
 else.

I agree, we shouldn't break existing clients - within a major version.
That's why we need to make API rev.

  - The V3 API as-is has:
- lower maintenance
- is easier to understand and use (consistent).
- Much better input validation which is baked-in (json-schema)
  rather than ad-hoc and incomplete.
 
 So here's the rub ... with the exception of the consistency bits, none
 of this is visible to users, which makes me think we should be able to
 do all of this on v2.

As discussed above we can't really do a lot on input validation
either. And I think the pain of doing the backport is being greatly
underestimated. In doing the v3 port we arranged the patches so much of
it in terms of review was similar to doing patches to V2 rather than
starting from new code. And I know how hard that was to get it all in
during a period when it was easier to review bandwidth.

 
  - Whilst we have existing users of the API we also have a lot more
users in the future. It would be much better to allow them to use
the API we want to get to as soon as possible, rather than trying
to evolve the V2 API and forcing them along the transition that
  they could otherwise avoid.
 
 I'm not sure I understand this.  A key point is that I think any
 evolving of the V2 API has to be backwards compatible, so there's no
 forcing them along involved.

Well other people have been suggesting we can just deprecate parts (be
it proxying or other bits we really don't like) and then make the
backwards incompatible change. I think we've already said we'll do it
for XML for the V2 API and force them off to JSON.

  - Proposed way forward:
- Release the V3 API in Juno with nova-network and tasks support
- Feature freeze the V2 API when the V3 API is released
  - Set the timeline for deprecation of V2 so users have a lot
of warning
  - Fallback for those who really don't want to move after
deprecation is an API service which translates between V2 and

Re: [openstack-dev] [nova] Future of the Nova API

On 02/24/2014 05:01 PM, Morgan Fainberg wrote:
 On the topic of backwards incompatible changes:
 
 I strongly believe that breaking current clients that use the APIs
 directly is the worst option possible. All the arguments about needing
 to know which APIs work based upon which backend drivers are used are
 all valid, but making an API incompatible change when we’ve made the
 contract that the current API will be stable is a very bad approach.
 Breaking current clients isn’t just breaking “novaclient, it would also
 break any customers that are developing directly against the API. In the
 case of cloud deployments with real-world production loads on them (and
 custom development around the APIs) upgrading between major versions is
 already difficult to orchestrate (timing, approvals, etc), if we add in
 the need to re-work large swaths of code due to API changes, it will
 become even more onerous and perhaps drive deployers to forego the
 upgrades in lieu of stability.
 
 If the perception is that we don’t have stable APIs (especially when we
 are ostensibly versioning them), driving adoption of OpenStack becomes
 significantly more difficult. Difficulty in driving further adoption
 would be a big negative to both the project and the community.
 
 TL;DR, “don’t break the contract”. If we are seriously making
 incompatible changes (and we will be regardless of the direction) the
 only reasonable option is a new major version.

FWIW, I do *not* consider non backwards compatible changes to be on the
table for the existing API.  Evolving it would have to be done in a
backwards compatible way.  I'm completely in agreement with that.

-- 
Russell Bryant

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 The API layer is a actually quite a very thin layer on top of the
 rest of Nova. Most of the logic in the API code is really just
 checking incoming data, calling the underlying nova logic and then
 massaging what is returned in the correct format. So as soon as you
 change the format the cost of localised changes is pretty much the
 same as duplicating the APIs. In fact I'd argue in many cases its
 more because in terms of code readability its a lot worse and
 techniques like using decorators for jsonschema for input validation
 are a lot harder to implement. And unit and tempest tests still need
 to be duplicated.

Making any change to the backend is double the effort with the two trees
as it would be with one API. I agree that changing/augmenting the format
of a call means some localized if this then that code, but that's
minor compared to what it takes to do things on the backend, IMHO.

 I don't understand why this is also not seen as forcing people off
 V2 to V3 which is being given as a reason for not being able to set
 a reasonable deprecation time for V2. This will require major changes
 for people using the V2 API to change how they use it.

Well, deprecating them doesn't require the change. Removing them does. I
think we can probably keep the proxying in a deprecated form for a very
long time, hopefully encouraging new users to do it right without
breaking existing users who don't care. Hopefully losing out on the
functionality they miss by not talking directly to Neutron (for example)
will be a good carrot to avoid using the proxy APIs.

 In all the discussions we've (as in the Nova group) had over the API 
 there has been a pretty clear consensus that proxying is quite 
 suboptimal (there are caching issues etc) and the long term goal is
 to remove it from Nova. Why the change now?

This is just MHO, of course. I don't think I've been party to those
conversations. I understand why the proxying is bad, but that's a
different issue from whether we drop it and break our users.

 I strongly disagree here. I think you're overestimating the amount of
 maintenance effort this involves and significantly underestimating
 how much effort and review time a backport is going to take.

Fair enough. I'm going from my experience over the last few cycles of
changing how the API communicates with the backend. This is something
we'll have to continue to evolve over time, and right now it
Sucks Big Time(tm) :)

 - twice the code
 For starters, It's not twice the code because we don't do things
 like proxying and because we are able to logically separate out
 input validation jsonschema.

You're right, I should have said twice the code for changes between the
API and the backend.

 Eg just one simple example, but how many people new to the API get
 confused about what they are meant to send when it asks for
 instance_uuid when they've never received one - is at server uuid -
 and if so what's the difference? Do I have to do some sort of
 conversion? Similar issues around project and tenant. And when
 writing code they have to remember for this part of the API they pass
 it as server_uuid, in another instance_uuid, or maybe its just id?
 All of these looked at individually may look like small costs or
 barriers to using the API but they all add up and they end up being
 imposed over a lot of people.

Yup, it's ugly, no doubt. I think that particular situation is probably
(hopefully?) covered up by the various client libraries (and/or docs)
that we have. If not, I think it's probably something we can improve
from an experience perspective on that end. But yeah, I know the public
API docs would still have that ambiguity.

 And how is say removing proxying or making *any* backwards
 incompatible change any different?

It's not. That's why I said maybe remove it some day :)

 Well if you never deprecate the only way to do it is to maintain the 
 old API forever (including test). And just take the hit on all that 
 involves.

Sure. Hopefully people that actually deploy and support our API will
chime in here about whether they think that effort is worth not telling
their users to totally rewrite their clients.

If we keep v2 and v3, I think we start in icehouse with a very large
surface, which will increase over time. If we don't, then we start with
v2 and end up with only the delta over time.

 What about the tasks API? We that discussed at the mid cycle summit
 and decided that the alternative backwards compatible way of doing it
 was too ugly and we didn't want to do that. But that's exactly what
 we'd be doing if we implemented them in the v2 API and it would be a 
 feature which ends up looking bolted because of the otherwise 
 significant non backwards compatible API changes we can't do.

If we version the core API and let the client declare the version it
speaks in a header, we could iterate on that interface right? If they're
version X, return the server object and a task header, if =X return
the task. We

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Chris Friesen


On 02/24/2014 04:01 PM, Morgan Fainberg wrote:


TL;DR, “don’t break the contract”. If we are seriously making
incompatible changes (and we will be regardless of the direction) the
only reasonable option is a new major version.


Agreed.  I don't think we can possibly consider making 
backwards-incompatible changes without changing the version number.


We could stay with V2 and make as many backwards-compatible changes as 
possible using a minor version. This could include things like adding 
support for unified terminology as long as we *also* continue to support 
the old terminology.  The downside of this is that the code gets messy.


On the other hand, if we need to make backwards incompatible changes 
then we need to bump the version number.


Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 11:48:41 -0500
Jay Pipes jaypi...@gmail.com wrote:
 It's not about forcing providers to support all of the public API.
 It's about providing a single, well-documented, consistent HTTP REST
 API for *consumers* of that API. Whether a provider chooses to, for
 example, deploy with nova-network or Neutron, or Xen vs. KVM, or
 support block migration for that matter *should have no effect on the
 public API*. The fact that those choices currently *do* effect the
 public API that is consumed by the client is a major indication of
 the weakness of the API.

So for the nova-network/neutron issue its more a result of either
support for neutron was never implemented or new nova-network features
were added without corresponding neutron support. I agree its not a
good place to be in, but isn't really relevant to whether we have
extensions or not.

Similarly with a Xen vs KVM situation I don't think its an extension
related issue. In V2 we have features in *core* which are only supported
by some virt backends. It perhaps comes down to not being willing to
say either that we will force all virt backends to support all features
in the API or they don't get in the tree. Or alternatively be willing
to say no to any feature in the API which can not be currently
implemented in all virt backends. The former greatly increases the
barrier to getting a hypervisor included, the latter restricts Nova
development to the speed of the slowest developing and least
mature hypervisor supported.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On 02/24/2014 05:26 PM, Christopher Yeoh wrote:
 - Whilst we have existing users of the API we also have a lot more
   users in the future. It would be much better to allow them to use
   the API we want to get to as soon as possible, rather than trying
   to evolve the V2 API and forcing them along the transition that
 they could otherwise avoid.

 I'm not sure I understand this.  A key point is that I think any
 evolving of the V2 API has to be backwards compatible, so there's no
 forcing them along involved.
 
 Well other people have been suggesting we can just deprecate parts (be
 it proxying or other bits we really don't like) and then make the
 backwards incompatible change. I think we've already said we'll do it
 for XML for the V2 API and force them off to JSON.

Well, marking deprecated is different than removing it.  We have to get
good data that shows that it's not actually being used before can
actually remove it.  Marking it deprecated at least signals that we
don't consider it actively maintained and that it may go away in the future.

I also consider the XML situation a bit different than changing
specifics of a given API extension, for example.  We're talking about
potentially removing an entire API vs changing an API while it's in use.

 2) Take what we have learned from v3 and apply it to v2.  For example:

 snip
  - revisit a new major API when we get to the point of wanting to
effectively do a re-write, where we are majorly re-thinking the
way our API is designed (from an external perspective, not internal
implementation).
 
 Ultimately I think what this would means is punting any significant API
 improvements several years down the track and effectively throwing away
 a lot of the worked we've done in the last year on the API

One of the important questions is how much improvement can we make to v2
without breaking backwards compatibility?

What can we *not* do in a backwards compatible manner?  How much does it
hurt to give those things up?  How does that compare to the cost of dual
maintenance?

-- 
Russell Bryant

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Michael Davies

On Tue, Feb 25, 2014 at 8:31 AM, Morgan Fainberg m...@metacloud.com wrote:

 On the topic of backwards incompatible changes:

 I strongly believe that breaking current clients that use the APIs
 directly is the worst option possible. All the arguments about needing to
 know which APIs work based upon which backend drivers are used are all
 valid, but making an API incompatible change when we've made the contract
 that the current API will be stable is a very bad approach. Breaking
 current clients isn't just breaking novaclient, it would also break any
 customers that are developing directly against the API. In the case of
 cloud deployments with real-world production loads on them (and custom
 development around the APIs) upgrading between major versions is already
 difficult to orchestrate (timing, approvals, etc), if we add in the need to
 re-work large swaths of code due to API changes, it will become even more
 onerous and perhaps drive deployers to forego the upgrades in lieu of
 stability.

 If the perception is that we don't have stable APIs (especially when we
 are ostensibly versioning them), driving adoption of OpenStack becomes
 significantly more difficult. Difficulty in driving further adoption would
 be a big negative to both the project and the community.

 TL;DR, don't break the contract. If we are seriously making incompatible
 changes (and we will be regardless of the direction) the only reasonable
 option is a new major version


I'm absolutely in agreement here - thanks Morgan for raising this.

Changing the API on consumers means forcing them to re-evaluate their
options: Should I fix my usage of the API, or is it time to try another
solution?  The implementation cost is mostly the same.  We can't assume
that API breakages won't lead to customers leaving.  It's worth noting that
competing cloud APIs are inconsistent, and frankly awful.  But they don't
change because it's all about the commercial interest of retaining
customers and supporting a cornucopia of SDKs.

Any changes to a versioned API need to be completely backwards compatible,
and we shouldn't assume changes aren't going to break things - we should
test the crap out of them so as to ensure this is the case. Or put another
way, any time we touch a stable API, we need to be extremely careful.

If we want new features, if we want to clean up existing interfaces, it's
far better to move to a new API version (even with the maintenance burden
of supporting another API) than try and bolt something on the side.  This
includes improving input validation, because we should not be changing the
functionality presented to end-users on a stable API, even if it's for
their own good.  What it comes down to is strongly supporting the consumers
of our software.  We need to make things easy for those who support and
develop against the APIs.

Hope this helps,

Michael...
-- 
Michael Davies   mich...@the-davies.net
Rackspace Australia
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Sean Dague

It's really easy to just say don't break the contract. Until we got
the level of testing that we currently have in Tempest, the contract was
broken pretty regularly. I'm sure there are still breaks in it around
the edges where we aren't clamping down on people today.

So the history of v2 is far from being a stable API in the traditional
sense.

Which isn't to say we're trying to go and make the whole thing fluid.
However there has to be a path forward for incremental improvement,
because there are massive short comings in the existing API.

While a big bang approach might work for smaller interfaces, the Nova
API surface is huge. So huge, it's not even fully documented. Which
means we're at a state where you aren't implementing to an API, you are
implementing to an implementation. And if you look at HP and RAX you'll
find enough differences to make you scratch your head a bunch. And
that's only 2 data points. I'm sure the private cloud products have all
kinds of funkiness in them.

So we do really need to be pragmatic here as well. Because our
experience with v3 so far has been doing a major version bump on Nova is
a minimum of 2 years, and that doesn't reach a completion point that
anyone's happy with to switch over.

So, that begs a new approach. Because I think at this point even if we
did put out Nova v3, there can never be a v4. It's too much, too big,
and doesn't fit in the incremental nature of the project. So whatever
gets decided about v3, the thing that's important to me is a sane way to
be able to add backwards compatible changes (which we actually don't
have today, and I don't think any other service in OpenStack does
either), as well a mechanism for deprecating parts of the API. With some
future decision about whether removing them makes sense.

-Sean

On 02/24/2014 05:01 PM, Morgan Fainberg wrote:
 On the topic of backwards incompatible changes:
 
 I strongly believe that breaking current clients that use the APIs
 directly is the worst option possible. All the arguments about needing
 to know which APIs work based upon which backend drivers are used are
 all valid, but making an API incompatible change when we’ve made the
 contract that the current API will be stable is a very bad approach.
 Breaking current clients isn’t just breaking “novaclient, it would also
 break any customers that are developing directly against the API. In the
 case of cloud deployments with real-world production loads on them (and
 custom development around the APIs) upgrading between major versions is
 already difficult to orchestrate (timing, approvals, etc), if we add in
 the need to re-work large swaths of code due to API changes, it will
 become even more onerous and perhaps drive deployers to forego the
 upgrades in lieu of stability.
 
 If the perception is that we don’t have stable APIs (especially when we
 are ostensibly versioning them), driving adoption of OpenStack becomes
 significantly more difficult. Difficulty in driving further adoption
 would be a big negative to both the project and the community.
 
 TL;DR, “don’t break the contract”. If we are seriously making
 incompatible changes (and we will be regardless of the direction) the
 only reasonable option is a new major version.
 
 *—*
 *Morgan Fainberg*
 Principal Software Engineer
 Core Developer, Keystone
 m...@metacloud.com mailto:m...@metacloud.com
 
 
 On February 24, 2014 at 10:16:31, Matt Riedemann
 (mrie...@linux.vnet.ibm.com mailto://mrie...@linux.vnet.ibm.com) wrote:
 


 On 2/24/2014 10:13 AM, Russell Bryant wrote:
  On 02/24/2014 01:50 AM, Christopher Yeoh wrote:
  Hi,
 
  There has recently been some speculation around the V3 API and whether
  we should go forward with it or instead backport many of the changes
  to the V2 API. I believe that the core of the concern is the extra
  maintenance and test burden that supporting two APIs means and the
  length of time before we are able to deprecate the V2 API and return
  to maintaining only one (well two including EC2) API again.
 
  Yes, this is a major concern.  It has taken an enormous amount of work
  to get to where we are, and v3 isn't done.  It's a good time to
  re-evaluate whether we are on the right path.
 
  The more I think about it, the more I think that our absolute top goal
  should be to maintain a stable API for as long as we can reasonably do
  so.  I believe that's what is best for our users.  I think if you gave
  people a choice, they would prefer an inconsistent API that works for
  years over dealing with non-backwards compatible jumps to get a nicer
  looking one.
 
  The v3 API and its unit tests are roughly 25k lines of code.  This also
  doesn't include the changes necessary in novaclient or tempest.  That's
  just *our* code.  It explodes out from there into every SDK, and then
  end user apps.  This should not be taken lightly.
 
  This email is rather long so here's the TL;DR version:
 
  - We want to make backwards incompatible changes to the API

Re: [openstack-dev] [nova] Future of the Nova API

On 02/24/2014 05:49 PM, Michael Davies wrote:
 On Tue, Feb 25, 2014 at 8:31 AM, Morgan Fainberg m...@metacloud.com
 mailto:m...@metacloud.com wrote:
 
 On the topic of backwards incompatible changes:
 
 I strongly believe that breaking current clients that use the APIs
 directly is the worst option possible. All the arguments about
 needing to know which APIs work based upon which backend drivers are
 used are all valid, but making an API incompatible change when we’ve
 made the contract that the current API will be stable is a very bad
 approach. Breaking current clients isn’t just breaking “novaclient,
 it would also break any customers that are developing directly
 against the API. In the case of cloud deployments with real-world
 production loads on them (and custom development around the APIs)
 upgrading between major versions is already difficult to orchestrate
 (timing, approvals, etc), if we add in the need to re-work large
 swaths of code due to API changes, it will become even more onerous
 and perhaps drive deployers to forego the upgrades in lieu of stability.
 
 If the perception is that we don’t have stable APIs (especially when
 we are ostensibly versioning them), driving adoption of OpenStack
 becomes significantly more difficult. Difficulty in driving further
 adoption would be a big negative to both the project and the community.
 
 TL;DR, “don’t break the contract”. If we are seriously making
 incompatible changes (and we will be regardless of the direction)
 the only reasonable option is a new major version
 
 
 I'm absolutely in agreement here - thanks Morgan for raising this.
 
 Changing the API on consumers means forcing them to re-evaluate their
 options: Should I fix my usage of the API, or is it time to try another
 solution?  The implementation cost is mostly the same.  We can't assume
 that API breakages won't lead to customers leaving.  It's worth noting
 that competing cloud APIs are inconsistent, and frankly awful.  But they
 don't change because it's all about the commercial interest of retaining
 customers and supporting a cornucopia of SDKs.
 
 Any changes to a versioned API need to be completely backwards
 compatible, and we shouldn't assume changes aren't going to break things
 - we should test the crap out of them so as to ensure this is the case.
 Or put another way, any time we touch a stable API, we need to be
 extremely careful.
 
 If we want new features, if we want to clean up existing interfaces,
 it's far better to move to a new API version (even with the maintenance
 burden of supporting another API) than try and bolt something on the
 side.  This includes improving input validation, because we should not
 be changing the functionality presented to end-users on a stable API,
 even if it's for their own good.  What it comes down to is strongly
 supporting the consumers of our software.  We need to make things easy
 for those who support and develop against the APIs.

Let's please avoid too much violent agreement on this.  There seems to
have been some confusion spurred by Morgan's post.

I don't think *anybody* is in favor of non backwards compatible changes
to an existing API.  The short version of choices discussed in this thread:

1) Continue developing v3 (non backwards compat changes until we call it
stable).  Maintain v2 and v3 until we reach a point that we can drop v2
(there is debate about when that could be)

2) Focus on v2 only, and figure out ways to add features and evolve it
**but only in backwards compatible ways**

3) Some other possible view of a way forward that hasn't been brought up
yet, but I'm totally open to ideas

-- 
Russell Bryant

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Chris Friesen


On 02/24/2014 04:59 PM, Sean Dague wrote:


So, that begs a new approach. Because I think at this point even if we
did put out Nova v3, there can never be a v4. It's too much, too big,
and doesn't fit in the incremental nature of the project.


Does it necessarily need to be that way though?  Maybe we bump the 
version number every time we make a non-backwards-compatible change, 
even if it's just removing an API call that has been deprecated for a while.


Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Sean Dague

On 02/24/2014 06:13 PM, Chris Friesen wrote:
 On 02/24/2014 04:59 PM, Sean Dague wrote:
 
 So, that begs a new approach. Because I think at this point even if we
 did put out Nova v3, there can never be a v4. It's too much, too big,
 and doesn't fit in the incremental nature of the project.
 
 Does it necessarily need to be that way though?  Maybe we bump the
 version number every time we make a non-backwards-compatible change,
 even if it's just removing an API call that has been deprecated for a
 while.

So I'm not sure how this is different than the keep v2 and use
microversioning suggestion that is already in this thread.

-Sean

-- 
Sean Dague
Samsung Research America
s...@dague.net / sean.da...@samsung.com
http://dague.net



signature.asc
Description: OpenPGP digital signature
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 2014-02-24 at 14:01 -0800, Morgan Fainberg wrote:
 TL;DR, “don’t break the contract”. If we are seriously making
 incompatible changes (and we will be regardless of the direction) the
 only reasonable option is a new major version.

100% agreement.

Note that when I asked Chris when we would tackle the issue of
extensions, I was definitely looking at the next major version of the
Compute API, not v3 or v2. Sorry if I muddied the conversation in that
regard.

Best,
-jay



___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 2014-02-24 at 17:59 -0500, Sean Dague wrote:
 So we do really need to be pragmatic here as well. Because our
 experience with v3 so far has been doing a major version bump on Nova is
 a minimum of 2 years, and that doesn't reach a completion point that
 anyone's happy with to switch over.

I don't see why version 4 need repeat the timeline of v3 development.
I'm not saying it isn't possible, just that one doesn't necessarily lead
to the other.

Best,
-jay


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Tue, 2014-02-25 at 09:11 +1030, Christopher Yeoh wrote:
 On Mon, 24 Feb 2014 11:48:41 -0500
 Jay Pipes jaypi...@gmail.com wrote:
  It's not about forcing providers to support all of the public API.
  It's about providing a single, well-documented, consistent HTTP REST
  API for *consumers* of that API. Whether a provider chooses to, for
  example, deploy with nova-network or Neutron, or Xen vs. KVM, or
  support block migration for that matter *should have no effect on the
  public API*. The fact that those choices currently *do* effect the
  public API that is consumed by the client is a major indication of
  the weakness of the API.
 
 So for the nova-network/neutron issue its more a result of either
 support for neutron was never implemented or new nova-network features
 were added without corresponding neutron support. I agree its not a
 good place to be in, but isn't really relevant to whether we have
 extensions or not.

OK, fair enough.

 Similarly with a Xen vs KVM situation I don't think its an extension
 related issue. In V2 we have features in *core* which are only supported
 by some virt backends. It perhaps comes down to not being willing to
 say either that we will force all virt backends to support all features
 in the API or they don't get in the tree. Or alternatively be willing
 to say no to any feature in the API which can not be currently
 implemented in all virt backends. The former greatly increases the
 barrier to getting a hypervisor included, the latter restricts Nova
 development to the speed of the slowest developing and least
 mature hypervisor supported.

Actually, the problem is not feature parity. The problem lies where two
drivers implement the same or similar functionality, but the public API
for a user to call the functionality is slightly different depending on
which driver is used by the deployer.

There's nothing wrong at all (IMO) in having feature disparity amongst
drivers. However, problems arise when the public API does any of the
following:

 * exposes two ways of doing the same thing, depending on underlying
driver
 * exposes things in a way that is specific to one particular
vendor/driver to the exclusion of others
 * exposes things that should not be exposed to the end-user or tenant,
but that belong in the realm of the deployer

See my original response on the ML about that for examples of all of the
above from the current Nova API(s).

Best,
-jay


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Sean Dague

On 02/24/2014 06:31 PM, Jay Pipes wrote:
 On Mon, 2014-02-24 at 17:59 -0500, Sean Dague wrote:
 So we do really need to be pragmatic here as well. Because our
 experience with v3 so far has been doing a major version bump on Nova is
 a minimum of 2 years, and that doesn't reach a completion point that
 anyone's happy with to switch over.
 
 I don't see why version 4 need repeat the timeline of v3 development.
 I'm not saying it isn't possible, just that one doesn't necessarily lead
 to the other.
 
 Best,
 -jay

I guess having watched this evolve, it's not clear to me how to do it in
a shorter time frame. Maybe we just made tons of mistakes in the
process, but it seems like anything large like this is really 3 - 4
cycles. That was the cells timeline, that's been the baremetal story
timeline. Even the scheduler forklift, that everyone thought could
happen in a single cycle, is probably going to be 3 cycles start to finish.

Ways in which we could do this quicker would be appreciated. Though I do
like getting a few hours of sleep a night.

-Sean

-- 
Sean Dague
Samsung Research America
s...@dague.net / sean.da...@samsung.com
http://dague.net



signature.asc
Description: OpenPGP digital signature
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Chris Friesen


On 02/24/2014 05:17 PM, Sean Dague wrote:

On 02/24/2014 06:13 PM, Chris Friesen wrote:

On 02/24/2014 04:59 PM, Sean Dague wrote:


So, that begs a new approach. Because I think at this point even if we
did put out Nova v3, there can never be a v4. It's too much, too big,
and doesn't fit in the incremental nature of the project.


Does it necessarily need to be that way though?  Maybe we bump the
version number every time we make a non-backwards-compatible change,
even if it's just removing an API call that has been deprecated for a
while.


So I'm not sure how this is different than the keep v2 and use
microversioning suggestion that is already in this thread.


It differs in that it allows the user to determine whether the changes 
are forwards or backwards compatible.  For instance, you might use an 
API version that looks like {major}.{minor}.{bugfix} with the following 
rules:


A new bugfix release is both forwards and backwards compatible.

A new minor release is backwards compatible. So code written against 
version x.y will work with version x.y+n.  New minor releases would 
generally add functionality.


A new major release is not necessarily backwards compatible.  Code 
written against version x may not work with version x+1.  New major 
releases remove or change functionality.


Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Morgan Fainberg

Yes, micro-versioning is most likely a better approach, and I’m a fan of using 
that to gain the benefits of V3 without changing for the sake of change. 
Ideally in a versioned API we should be versioning a smaller surface area than 
“THE WHOLE API” if at all possible. If we kept the old “version” around and 
deprecated it (keep it for 2 cycles, when it goes away the non-versioned call 
says “sorry, version unsupported”?, and it can continue to be versioned as 
needed) and continue to increment the versions as appropriate with changes, we 
will be holding true to our contract. The benefits of V3 can still be reaped, 
knowing where the API should move towards.

Don’t try and take on a giant task to make a “new API version” at once. 

We can maintain the contract and still progress the APIs forward. And to Sean’s 
comment that the V2 API hasn’t been as “stable in the traditional sense” in the 
past, I think we can forgive past issues since we now have the framework to 
show us when/if things end up being incompatible (and I agree with the fact 
that big-bang changes don’t work for large surface area projects). I still 
stand by my statement that we can’t (shouldn’t knowingly) break the contract, 
we also can’t assume people will move to V3 (if we launch it) in a reasonable 
timeframe if the new API doesn’t really justify a massive re-write. Maintaining 
2, nearly identical, APIs is going to be problematic for both the developers 
and deployers. In my view (as a deployer, consumer, and developer) this means 
we should keep V2, and work on benefiting from the lessons learned in 
developing V3 while moving to correct the issues we have in a maintainable / 
friendly way (to developers, deployers, and consumers).
—
Morgan Fainberg
Principal Software Engineer
Core Developer, Keystone
m...@metacloud.com


On February 24, 2014 at 15:22:01, Sean Dague (s...@dague.net) wrote:

On 02/24/2014 06:13 PM, Chris Friesen wrote:  
 On 02/24/2014 04:59 PM, Sean Dague wrote:  
  
 So, that begs a new approach. Because I think at this point even if we  
 did put out Nova v3, there can never be a v4. It's too much, too big,  
 and doesn't fit in the incremental nature of the project.  
  
 Does it necessarily need to be that way though? Maybe we bump the  
 version number every time we make a non-backwards-compatible change,  
 even if it's just removing an API call that has been deprecated for a  
 while.  

So I'm not sure how this is different than the keep v2 and use  
microversioning suggestion that is already in this thread.  

-Sean  

--  
Sean Dague  
Samsung Research America  
s...@dague.net / sean.da...@samsung.com  
http://dague.net  

- signature.asc, 493 bytes
___  
OpenStack-dev mailing list  
OpenStack-dev@lists.openstack.org  
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev  
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 17:47:51 -0500
Russell Bryant rbry...@redhat.com wrote:
 On 02/24/2014 05:26 PM, Christopher Yeoh wrote:
  - Whilst we have existing users of the API we also have a lot more
users in the future. It would be much better to allow them to
  use the API we want to get to as soon as possible, rather than
  trying to evolve the V2 API and forcing them along the transition
  that they could otherwise avoid.
 
  I'm not sure I understand this.  A key point is that I think any
  evolving of the V2 API has to be backwards compatible, so there's
  no forcing them along involved.
  
  Well other people have been suggesting we can just deprecate parts
  (be it proxying or other bits we really don't like) and then make
  the backwards incompatible change. I think we've already said we'll
  do it for XML for the V2 API and force them off to JSON.
 
 Well, marking deprecated is different than removing it.  We have to
 get good data that shows that it's not actually being used before can
 actually remove it.  Marking it deprecated at least signals that we
 don't consider it actively maintained and that it may go away in the
 future.

So the deprecation message in the patch says:

   LOG.warning(_('XML support has been deprecated and will be
 removed in the Juno release.'))

perhaps that should be changed :-)

 I also consider the XML situation a bit different than changing
 specifics of a given API extension, for example.  We're talking about
 potentially removing an entire API vs changing an API while it's in
 use.

That's sort of true, but existing users will have to move to JSON.
Which I think would be a lot more work compared to making someone move
from V2 to V3.

  Ultimately I think what this would means is punting any significant
  API improvements several years down the track and effectively
  throwing away a lot of the worked we've done in the last year on
  the API
 
 One of the important questions is how much improvement can we make to
 v2 without breaking backwards compatibility?
 
 What can we *not* do in a backwards compatible manner?  How much does
 it hurt to give those things up?  How does that compare to the cost
 of dual maintenance?

In terms of user facing changes we can't do a whole lot - because they
are inherently changes in how users communicate with API. And not just
in terms of parameter names, but where and how they access the
functionality (eg url paths change). In the past we've made
mistakes as to where or how functionality should appear, leading to
weird inconsistencies.

So either we can't fix them or in cases where we preserve backwards
compatibility we end up with dual maintenance cost (our test load
still doubles), but often having to be implemented in a way which costs
us more in terms of readability because the code becomes spaghetti.

If it was just a handful changes then I'd agree a major version bump is
not necessary - and we wouldn't have started going down this path over
a year ago. But the user facing improvements are pretty much pervasive
through the API (with the exception of the more recent extensions where
we've got better at enforcing a consistent and sane API style).

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 15:54:42 -0800
Morgan Fainberg m...@metacloud.com wrote:

 Yes, micro-versioning is most likely a better approach, and I’m a fan
 of using that to gain the benefits of V3 without changing for the
 sake of change. Ideally in a versioned API we should be versioning a
 smaller surface area than “THE WHOLE API” if at all possible. If we
 kept the old “version” around and deprecated it (keep it for 2
 cycles, when it goes away the non-versioned call says “sorry, version
 unsupported”?, and it can continue to be versioned as needed) and
 continue to increment the versions as appropriate with changes, we
 will be holding true to our contract. The benefits of V3 can still be
 reaped, knowing where the API should move towards.

So we have a very large number of changes we want to make to the V2
API, and we've already done the work (including adding versioning to
make backwards compatible changes easier in the future) in the V3 API.

How is backporting all those changes to V2, marking the old behaviour as
deprecated and the removing them in 2 cycles (forcing them off the
old behaviour) any different from releasing the V3 API, marking the V2
as deprecated and removing it in the same timeframe? Except that the
former involves a lot more work?

Where there is compatibility between the V2 and V3 API the only change
which is required is the accessing it via /v3 instead of /v2/tenant_id

 don’t work for large surface area projects). I still stand by my
 statement that we can’t (shouldn’t knowingly) break the contract, we
 also can’t assume people will move to V3 (if we launch it) in a
 reasonable timeframe if the new API doesn’t really justify a massive
 re-write. 

If we can't assume people will make the changes to move to V3, then how
we can we assume they'll make the necessary changes with the
deprecation-in-place model when the amount of change required is
basically the same if we want to make the same improvements? 

Also in terms of consistency of the API we don't actually reap most of
the advantage until all of the changes have been made. Because until
that point we are still look like inconsistent API to users.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 So the deprecation message in the patch says:
 
LOG.warning(_('XML support has been deprecated and will be
  removed in the Juno release.'))
 
 perhaps that should be changed :-)

Maybe, but I think we can continue with the plan to rip it out in Juno.
In the past when we've asked, there has been an overwhelming amount of
meh regarding removing it. We've considered it several times, and
we've now drawn a line in the sand. Personally, I'm fine with doing
this, and I think the support from the core team that +A'd the heck out
of it probably means that there is wide support for it.

 In terms of user facing changes we can't do a whole lot - because they
 are inherently changes in how users communicate with API. And not just
 in terms of parameter names, but where and how they access the
 functionality (eg url paths change). In the past we've made
 mistakes as to where or how functionality should appear, leading to
 weird inconsistencies.
 
 So either we can't fix them or in cases where we preserve backwards
 compatibility we end up with dual maintenance cost (our test load
 still doubles), but often having to be implemented in a way which costs
 us more in terms of readability because the code becomes spaghetti.

I think it can be done without it turning into a mess. Non-trivial for
sure, but not impossible. And if not, I still expect most users would
prefer stability over purity.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 16:20:12 -0800
Dan Smith d...@danplanet.com wrote:
  So the deprecation message in the patch says:
  
 LOG.warning(_('XML support has been deprecated and will be
   removed in the Juno release.'))
  
  perhaps that should be changed :-)
 
 Maybe, but I think we can continue with the plan to rip it out in
 Juno. In the past when we've asked, there has been an overwhelming
 amount of meh regarding removing it. We've considered it several
 times, and we've now drawn a line in the sand. Personally, I'm fine
 with doing this, and I think the support from the core team that +A'd
 the heck out of it probably means that there is wide support for it.

Sure, I was using it as an example of where we have been willing to use
a fixed deprecation schedule for the API. If we look at the Havana
user survey I think the results say:

http://www.slideshare.net/openstack/havana-survey-resultsfinal-19312081

JSON: 150
XML: 62
Both: 33

So thats around 40% of those surveyed who would be affected. 
So if we can draw a line in the sand based on those sorts of numbers,
why is it impossible to do it for the V2 API as a whole? Albeit I
think more than one cycle would be needed.

  So either we can't fix them or in cases where we preserve backwards
  compatibility we end up with dual maintenance cost (our test load
  still doubles), but often having to be implemented in a way which
  costs us more in terms of readability because the code becomes
  spaghetti.
 
 I think it can be done without it turning into a mess. Non-trivial for
 sure, but not impossible. And if not, I still expect most users would
 prefer stability over purity.

We're not choosing between stability of purity though. As I've argued
elsewhere its not about 'purity', its about usability. And say we do
manage to do it without it turning into complete mess, we still have
the dual maintenance cost which seems to be the primary concern about
having both the V2 and V3 API released.

By supporting backwards incompatible changes inside the V2 API we're
just hiding the fact that we in fact have two different APIs. We're not
actually reducing the maintenance cost and it comes at increased user
confusion, not less. In some areas of testing we'll be increasing
the work needed to be done. Eg we need to make sure we're doing
something sane when someone passes say:

onSharedStorage = True
on_shared_storage = False

should the old or new behaviour get priority? Or should we instead
return a 400? We don't need to have that logic (or testing) when we
cleanly separate the new API from the old one. Similar issues when
passing a mixture of old and new formats. Should that be valid? If not
we need to explicitly check and reject.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On Mon, 24 Feb 2014 18:17:34 -0500
Sean Dague s...@dague.net wrote:

 On 02/24/2014 06:13 PM, Chris Friesen wrote:
  On 02/24/2014 04:59 PM, Sean Dague wrote:
  
  So, that begs a new approach. Because I think at this point even
  if we did put out Nova v3, there can never be a v4. It's too much,
  too big, and doesn't fit in the incremental nature of the project.
  
  Does it necessarily need to be that way though?  Maybe we bump the
  version number every time we make a non-backwards-compatible change,
  even if it's just removing an API call that has been deprecated for
  a while.
 
 So I'm not sure how this is different than the keep v2 and use
 microversioning suggestion that is already in this thread.

For non backwards compatible changes I think the difference is in how
the user accesses the API. When only make major changes when bumping
the major version then they know for sure that if they access

/v3/foo

then they're app will work. If /v3 doesn't exist then they know it's
not supported.

Whereas if we make backwards incompatible changes within a major
version then they have to start checking the microversion first. And
if experience is anything to go with we end up with user code that gets
overly conservative about checking versions (eg checking against exact
versions or not working with later versions), just in case.

Note that bumping the major version in the future does not
necessarily mean a rework of the magnitude that we have had for V3. The
V2-V3 transition is different because we want to change a *lot* of the
API.

We now have an architecture in the V3 API which is quite a bit more
flexible. So say a theoretical example of where we wanted to change the
data return from shelve in a backwards incompatible way (in practice
I don't think we'd bump a major version just for one change). We could
present a /v4 interface that was exactly the same as /v3 except for
what shelve provides and the only code duplication would be that
required for the new shelve functionality. All the v3 plugins would
load into the /v4 namespace. (It's most likely not worth doing this for
the v2/v3 transition because so much has changed and we cant retrofit
better input validation).

So those who want the deprecated behaviour continue to access
everything via /v3, those who want the new behaviour access it via /v4.
Its a clean delineation for users and they never accidentally get new
backwards incompatible behaviour through the old resource path. Either
its there (and supported) or /v3 doesn't exist and they need to update
their app which if they don't use the shelve functionality is trivial
(just point at /v4 instead of /v3) which is really just the equivalent
of linking your program against libfoo.2.so instead of libfoo.1.so. And
we don't have extra test load except for the shelve delta because the
code is all exactly the same.

For backwards compatible changes, microversions are certainly useful
though.

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

 onSharedStorage = True
 on_shared_storage = False

This is a good example. I'm not sure it's worth breaking users _or_
introducing a new microversion for something like this. This is
definitely what I would call a purity concern as opposed to usability.

Things like the twenty different datetime formats we expose _do_ seem
worth the change to me as it requires the client to parse a bunch of
different formats depending on the situation. However, we could solve
that with very little code by just exposing all the datetimes again in
proper format:

 {
  updated_at: %(random_weirdo)s,
  updated_at_iso: %(isotime)s,
 }

Doing the above is backwards compatible and doesn't create code
organizations based on any sort of pasta metaphor. If we introduce a
discoverable version tag so the client knows if they will be available,
I think we're good.

URL inconsistencies seem not worth the trouble and I tend to think
that the server vs. instance distinction probably isn't either, but
I guess I'm willing to consider it.

Personally, I would rather do what we can/need in order to provide
features in a compatible way, fix real functional issues (like the
datetimes), and not ask users to port to a new API to clear up a bunch
of CamelCase inconsistencies. Just MHO.

--Dan

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On 02/24/2014 08:16 PM, Christopher Yeoh wrote:
 On Mon, 24 Feb 2014 16:20:12 -0800
 Dan Smith d...@danplanet.com wrote:
 So the deprecation message in the patch says:

LOG.warning(_('XML support has been deprecated and will be
  removed in the Juno release.'))

 perhaps that should be changed :-)

 Maybe, but I think we can continue with the plan to rip it out in
 Juno. In the past when we've asked, there has been an overwhelming
 amount of meh regarding removing it. We've considered it several
 times, and we've now drawn a line in the sand. Personally, I'm fine
 with doing this, and I think the support from the core team that +A'd
 the heck out of it probably means that there is wide support for it.
 
 Sure, I was using it as an example of where we have been willing to use
 a fixed deprecation schedule for the API. 

Well, I got a little carried away when I wrote that message.  I think we
should change it.  I don't think it's a responsible thing to do to
remove it unless we do another good round of assessing what the impact
would be and then only removing it when the impact is very minimal.

I'd really like some help from the public cloud providers to get some
insight into the percentage of their users that use XML.  We likely have
some work to do in Nova to make it easier to collect this data.

 If we look at the Havana
 user survey I think the results say:
 
 http://www.slideshare.net/openstack/havana-survey-resultsfinal-19312081
 
 JSON: 150
 XML: 62
 Both: 33
 
 So thats around 40% of those surveyed who would be affected. 
 So if we can draw a line in the sand based on those sorts of numbers,
 why is it impossible to do it for the V2 API as a whole? Albeit I
 think more than one cycle would be needed.
 

Sadly, I think those results are near useless.  For example:

 - it doesn't differentiate based on the type of responder.  Is it
   deployers saying they deploy the XML API (they don't have a choice).
   There is no way to know about cloud usage here.

 - is there possible confusion with EC2?  (EC2 is XML)

However, getting good data here *is* important.

Also note that none of the major SDKs use XML.  In addition to our own
client libraries, the following only use JSON:

Apache jclouds (Java)
openstack.net (C#)
pkgcloud (node.js)
php-opencloud (PHP)
Fog (Ruby)

 So either we can't fix them or in cases where we preserve backwards
 compatibility we end up with dual maintenance cost (our test load
 still doubles), but often having to be implemented in a way which
 costs us more in terms of readability because the code becomes
 spaghetti.

 I think it can be done without it turning into a mess. Non-trivial for
 sure, but not impossible. And if not, I still expect most users would
 prefer stability over purity.
 
 We're not choosing between stability of purity though. As I've argued
 elsewhere its not about 'purity', its about usability. And say we do
 manage to do it without it turning into complete mess, we still have
 the dual maintenance cost which seems to be the primary concern about
 having both the V2 and V3 API released.
 
 By supporting backwards incompatible changes inside the V2 API we're
 just hiding the fact that we in fact have two different APIs. We're not
 actually reducing the maintenance cost and it comes at increased user
 confusion, not less. In some areas of testing we'll be increasing
 the work needed to be done. Eg we need to make sure we're doing
 something sane when someone passes say:
 
 onSharedStorage = True
 on_shared_storage = False
 
 should the old or new behaviour get priority? Or should we instead
 return a 400? We don't need to have that logic (or testing) when we
 cleanly separate the new API from the old one. Similar issues when
 passing a mixture of old and new formats. Should that be valid? If not
 we need to explicitly check and reject.

I think in cases like this, we should only have the old behavior.  I'm
not sure I see much value in making these changes in v2 at all.

-- 
Russell Bryant

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

On 02/24/2014 08:31 PM, Christopher Yeoh wrote:
 On Mon, 24 Feb 2014 18:17:34 -0500
 Sean Dague s...@dague.net wrote:
 
 On 02/24/2014 06:13 PM, Chris Friesen wrote:
 On 02/24/2014 04:59 PM, Sean Dague wrote:

 So, that begs a new approach. Because I think at this point even
 if we did put out Nova v3, there can never be a v4. It's too much,
 too big, and doesn't fit in the incremental nature of the project.

 Does it necessarily need to be that way though?  Maybe we bump the
 version number every time we make a non-backwards-compatible change,
 even if it's just removing an API call that has been deprecated for
 a while.

 So I'm not sure how this is different than the keep v2 and use
 microversioning suggestion that is already in this thread.
 
 For non backwards compatible changes I think the difference is in how
 the user accesses the API. When only make major changes when bumping
 the major version then they know for sure that if they access
 
 /v3/foo
 
 then they're app will work. If /v3 doesn't exist then they know it's
 not supported.
 
 Whereas if we make backwards incompatible changes within a major
 version then they have to start checking the microversion first.

snip

A point of clarification on the micro-version idea.  IMO, the only
changes acceptable under such a scheme are backwards compatible ones.

-- 
Russell Bryant

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

CC'ing the openstack-operators mailing list to get a wider set of
feedback on this question.

On 02/24/2014 05:26 PM, Christopher Yeoh wrote:
 1) Continue as we have been, and plan to release v3 once we have a
 compelling enough feature set.
 
 So I think we should release in Juno even if its only with tasks and
 nova-network added. Because this allows new users to start using the
 API immediately rather than having to code against V2 (with its extra
 barriers to use) and then take the hit to upgrade later.

OK, let's go a bit further with the case of marking the v3 API stable in
Juno.  If we did that, what is a reasonable timeframe of v2 being
deprecated before it could be removed?

From a selfish developer perspective, the answer is remove v2
immediately.  From a selfish user perspective, the answer is never
remove it.  Where is the reasonable middle ground?  How long would it
take to have enough clients migrated that we could remove the old API?

I'm interested in answers from pretty much everyone on this, including
deployers, as well as users of our APIs.  I'm also especially interested
in an opinion from large public clouds based on OpenStack.

-- 
Russell Bryant

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API

2014-02-24 Thread Kenichi Oomichi

-Original Message-
From: Christopher Yeoh [mailto:cbky...@gmail.com]
Sent: Tuesday, February 25, 2014 6:35 AM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [nova] Future of the Nova API

- twice the code
- different enough to be annoying to convert existing clients to use
- not currently different enough to justify the pain

For starters, It's not twice the code because we don't do things like
proxying and because we are able to logically separate out input
validation jsonschema.

v2 API: ~14600 LOC
v3 API: ~7300 LOC (~8600 LOC if nova-network as-is added back in,
though the actually increase would almost certainly be a lot smaller)

And that's with a lot of the jsonschema patches not landed. So its
actually getting *smaller*. Long term which looks the better from a
maintenance point of view

The merits of jsonschema validation are not only less-code but also
clarifying API attributes Nova has.
Throght jsonschema validation development, we needed to clarify all API
attributes of each API and write all of them to API schema defined with
jsonschema. For example,
https://review.openstack.org/#/c/68560/6/nova/api/openstack/compute/schemas/v3/scheduler_hints.py
clarifies that API extension scheduler_hints of create a server API
contains 7 API attributes and these data types. I think we don't have
enough API document which shows all API attributes.

So now I have a question what should deployers answer a question if
their users ask
What API attributes can we specify to your OpenStack API?
to the deployers. Should we/deployers dig all v2 API code for all
API attributes? I think many people on this ML have this kind of
experience.
If all jsonschema patches are landed, we can show all API attributes
for deployers/users by just specifying API schema directory.

Thanks
Ken'ichi Ohmichi

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Future of the Nova API