Re: [openstack-dev] [Ironic] Let's talk about API versions
On 20 August 2015 at 23:19, Ruby Loo rlooya...@gmail.com wrote: On 18 August 2015 at 17:13, Ruby Loo rlooya...@gmail.com wrote: On 18 August 2015 at 13:08, Lucas Alvares Gomes lucasago...@gmail.com wrote: HI Hi, I'd like to make sure I understand. Is it the case that ideally, if we could go back in time, we'd like to change the client so it defaults to 1.1? AFAIUI, yes But since we can't, the next client that we ship/release will have the most reasonable oldest version? If so, then since the most recent client shipped is at 1.6, then I think we should put it back to 1.6 even though it is 1.9 on master. Regardless of whether there are no backwards incompatible changes between 1.6 1.9 -- because we need to stick to some way-of-doing-things, and if we use 1.9, I suspect it will be confusing. At least 1.6 was what we had at the end of kilo. The reason why I think we should release with 1.9 is because: 1) It's already on master and people may be using it already 2) It's compatible with the previous version that has been released already (1.6). So it won't break neither users that just get it from pip nor users that clone the git repository. The order of my preference is 1.1 (which is unrealistic as I mention below), 1.6 (because that's what the client had in kilo release and is the 'closest' version to the server's 1.1), then 1.9 for the reasons you mentioned above, then 1.10 just cuz it is the last version that is backwards compatible :-) Devananda has a patch[0] that changes the client to 1.6, but the reviewers' comments there point to the mailing list (here) wrt deciding what it should be so what do other folks think? In case we don't resolve this via email, I added this topic (which default version should the client use) to our next meeting's agenda. cheers, --ruby In today's ironic meeting[0], we voted to set the default version to 1.9, in the client. --ruby [0] http://eavesdrop.openstack.org/meetings/ironic/2015/ironic.2015-08-24-17.00.html __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 18 August 2015 at 17:13, Ruby Loo rlooya...@gmail.com wrote: On 18 August 2015 at 13:08, Lucas Alvares Gomes lucasago...@gmail.com wrote: HI Hi, I'd like to make sure I understand. Is it the case that ideally, if we could go back in time, we'd like to change the client so it defaults to 1.1? AFAIUI, yes But since we can't, the next client that we ship/release will have the most reasonable oldest version? If so, then since the most recent client shipped is at 1.6, then I think we should put it back to 1.6 even though it is 1.9 on master. Regardless of whether there are no backwards incompatible changes between 1.6 1.9 -- because we need to stick to some way-of-doing-things, and if we use 1.9, I suspect it will be confusing. At least 1.6 was what we had at the end of kilo. The reason why I think we should release with 1.9 is because: 1) It's already on master and people may be using it already 2) It's compatible with the previous version that has been released already (1.6). So it won't break neither users that just get it from pip nor users that clone the git repository. The order of my preference is 1.1 (which is unrealistic as I mention below), 1.6 (because that's what the client had in kilo release and is the 'closest' version to the server's 1.1), then 1.9 for the reasons you mentioned above, then 1.10 just cuz it is the last version that is backwards compatible :-) Devananda has a patch[0] that changes the client to 1.6, but the reviewers' comments there point to the mailing list (here) wrt deciding what it should be so what do other folks think? In case we don't resolve this via email, I added this topic (which default version should the client use) to our next meeting's agenda. cheers, --ruby __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
HI Hi, I'd like to make sure I understand. Is it the case that ideally, if we could go back in time, we'd like to change the client so it defaults to 1.1? AFAIUI, yes But since we can't, the next client that we ship/release will have the most reasonable oldest version? If so, then since the most recent client shipped is at 1.6, then I think we should put it back to 1.6 even though it is 1.9 on master. Regardless of whether there are no backwards incompatible changes between 1.6 1.9 -- because we need to stick to some way-of-doing-things, and if we use 1.9, I suspect it will be confusing. At least 1.6 was what we had at the end of kilo. The reason why I think we should release with 1.9 is because: 1) It's already on master and people may be using it already 2) It's compatible with the previous version that has been released already (1.6). So it won't break neither users that just get it from pip nor users that clone the git repository. What we're saying is that for M*, N*, O*, ..., the version used in the client will be the higher of server's MIN_VER_STR or 1.6, right? It's a suggestion, if we all agree that the minimal version (1.1) is the ideal version to the client to be pinned with when no other version is specified, how can we best warn the users that we are going to pin to this version for the future releases ? Maybe we don't need to do that, but would be good to discuss and have a consensus about it. Hey Lucas, Maybe I missed something about the client. If no version is specified to the (next-released) client, won't it use 1.6? How are we going to move it back to 1.1? Yeah *right now* with the last released version if you don't specify a version it will use 1.6. With the current code in the git repository the version will used will be 1.9 if no other is specified. About how we are going to move it back was my question as well. If we all agree in moving it to 1.1 when no version is specified how we can best warn the users that we are going to do that? Since it might break their workflow. Maybe we shouldn't move it back, but let's keep the conversation going so we can solve this. Cheers, Lucas __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 18 August 2015 at 13:08, Lucas Alvares Gomes lucasago...@gmail.com wrote: HI Hi, I'd like to make sure I understand. Is it the case that ideally, if we could go back in time, we'd like to change the client so it defaults to 1.1? AFAIUI, yes But since we can't, the next client that we ship/release will have the most reasonable oldest version? If so, then since the most recent client shipped is at 1.6, then I think we should put it back to 1.6 even though it is 1.9 on master. Regardless of whether there are no backwards incompatible changes between 1.6 1.9 -- because we need to stick to some way-of-doing-things, and if we use 1.9, I suspect it will be confusing. At least 1.6 was what we had at the end of kilo. The reason why I think we should release with 1.9 is because: 1) It's already on master and people may be using it already 2) It's compatible with the previous version that has been released already (1.6). So it won't break neither users that just get it from pip nor users that clone the git repository. The order of my preference is 1.1 (which is unrealistic as I mention below), 1.6 (because that's what the client had in kilo release and is the 'closest' version to the server's 1.1), then 1.9 for the reasons you mentioned above, then 1.10 just cuz it is the last version that is backwards compatible :-) Devananda has a patch[0] that changes the client to 1.6, but the reviewers' comments there point to the mailing list (here) wrt deciding what it should be so what do other folks think? What we're saying is that for M*, N*, O*, ..., the version used in the client will be the higher of server's MIN_VER_STR or 1.6, right? It's a suggestion, if we all agree that the minimal version (1.1) is the ideal version to the client to be pinned with when no other version is specified, how can we best warn the users that we are going to pin to this version for the future releases ? Maybe we don't need to do that, but would be good to discuss and have a consensus about it. I think 1.1 (the server's MIN_VER_STR) is the ideal version for the client, but I think we missed the boat on that. I don't think it makes much sense to change things so that the client uses that version in some future release. The reason being is that kilo was released with the client defaulting to 1.6. For everyone in cloudland not explicitly specifying a version, they are using 1.6. And what is different in 1.6 than 1.1 -- we renamed NOSTATE to AVAILABLE state. I don't think it is worth breaking existing applications to deprecate/go back to 1.1. (A separate discussion I'd like to have, is when do we want to change the server's MIN_VER_STR from 1.1 to eg 1.6 or even gasp, 1.11 when ENROLL made its appearance). --ruby [0] https://review.openstack.org/#/c/208102/ __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 1 August 2015 at 05:16, Lucas Alvares Gomes lucasago...@gmail.com wrote: Hi, It sounds like we all agree -- the client we ship should default to a fixed, older version. Anyone who wants newer functionality can pass a newer version to their client. Here's the current state of things: server: - stable/kilo: 1.6 - current: 1.11 client: - stable/kilo: 1.6 - latest release (0.7.0): 1.6 - current: 1.9 So -- since we haven't released a client that sends a header 1.6, I propose that we set the client back to sending the 1.6 header right away. While having the client default to 1.1 would be ideal, this should still keep the Jackson the Absent of the world as happy as reasonably possible moving forward without breaking anyone that is packaging Kilo already. (yes, this may affect Olivia the Contributor, but that's OK because Olivia will have read this email :) ) There are no backwards incompatible changes from 1.6 to 1.9, so I suggest we just leave it at 1.9 and don't break Jackson nor Olivia (and have no assumptions about who will read this or not). Hi, I'd like to make sure I understand. Is it the case that ideally, if we could go back in time, we'd like to change the client so it defaults to 1.1? But since we can't, the next client that we ship/release will have the most reasonable oldest version? If so, then since the most recent client shipped is at 1.6, then I think we should put it back to 1.6 even though it is 1.9 on master. Regardless of whether there are no backwards incompatible changes between 1.6 1.9 -- because we need to stick to some way-of-doing-things, and if we use 1.9, I suspect it will be confusing. At least 1.6 was what we had at the end of kilo. What we're saying is that for M*, N*, O*, ..., the version used in the client will be the higher of server's MIN_VER_STR or 1.6, right? ... Apart from that I think most of the people agreed on the client defaulting to the minimal version (which I'm assuming means 1.1). So what people think? Should we add some warning messages when the version is not specified in the CLI saying we are moving it back to 1.1 on the next releases? And then default it to 1.1 later? Cheers, Lucas Hey Lucas, Maybe I missed something about the client. If no version is specified to the (next-released) client, won't it use 1.6? How are we going to move it back to 1.1? --ruby __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 11 August 2015 at 06:13, Ruby Loo rlooya...@gmail.com wrote:
Hi, sorry for the delay. I vote no. I understand the rationale of trying to
do things so that we don't break our users but that's what the versioning is
meant for and more importantly -- I think adding the ENROLL state is fairly
important wrt the lifecycle of a node. I don't particularly want to hide
that and/or let folks opt out of it in the long term.
From a reviewer point-of-view, my concern is me trying to remember all the
possible permutations/states etc that are possible to make sure that new
code doesn't break existing behavior. I haven't thought out whether adding
this new API would make that worse or not, but then, I don't really want to
have to think about it. So KISS as much as we can! :)
I'm a little surprised by this, to be honest.
Here's why: allowing the initial state to be chosen from
ENROLL/AVAILABLE from the latest version of the API is precisely as
complex as allowing two versions of the API {old, new} where old
creates nodes in AVAILABLE and new creates nodes in ENROLL. The only
difference I can see is that eventually someday if {old} stops being
supported, then and only then we can go through the code and clean
things up.
It seems to me that the costs to us of supporting graceful transitions
for users here are:
1) A new version NEWVER of the API that supports node state being one
of {not supplied, AVAILABLE, ENROLL}, on creation, defaulting to
AVAILABLE when not supplied.
2) Supporting the initial state of AVAILABLE indefinitely rather than
just until we *delete* version 1.10.
3) CD deployments that had rolled forward to 1.11 will need to add the
state parameter to their scripts to move forward to NEWVER.
4) Don't default the client to the veresions between 1.10 and NEWVER
versions at any point.
That seems like a very small price to pay on our side, and the
benefits for users are that they can opt into the new functionality
when they are ready.
-Rob
--
Robert Collins rbtcoll...@hp.com
Distinguished Technologist
HP Converged Cloud
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 4 August 2015 at 12:20, Jim Rollenhagen j...@jimrollenhagen.com wrote: On Mon, Jul 27, 2015 at 01:35:25PM -0700, Jim Rollenhagen wrote: Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. So after much deliberation, we took an informal vote in IRC this morning between 5 out of our 9 cores. The question was: should we do a 1.12 api version that allows the user to pick begining provision state in (AVAILABLE, ENROLL), defaulting to AVAILABLE? The results were 3 for no, 2 for yes. So that's the plan. Other Ironic cores (Haomeng, Yuriy, Ramesh, Ruby): please chime in if you have opinions on this. :) Otherwise we'll be getting to work on releasing a server as-is in the next few days. // jim Hi, sorry for the delay. I vote no. I understand the rationale of trying to do things so that we don't break our users but that's what the versioning is meant for and more importantly -- I think adding the ENROLL state is fairly important wrt the lifecycle of a node. I don't particularly want to hide that and/or let folks opt out of it in the long term. From a reviewer point-of-view, my concern is me trying to remember all the possible permutations/states etc that are possible to make sure that new code doesn't break existing behavior. I haven't thought out whether adding this new API would make that worse or not, but then, I don't really want to have to think about it. So KISS as much as we can! :) --ruby __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
Thanks for giving me a chance to vote. I don't have any experience talking to production/live Ironic using a client and only talk to my own devstack. Personally I vote for a *no* (for such a 1.12) the reasons that have been cited in the previous threads that 1) we need users to be aware of API versions (so I also would want them to pin it if they wanted a stable one, so don't default in their automation and keep testing and updating to the newer api versions) 2) it's already released, and i also tend to consider anything released could already being used right now On Tue, Aug 4, 2015 at 9:50 PM, Jim Rollenhagen j...@jimrollenhagen.com wrote: On Mon, Jul 27, 2015 at 01:35:25PM -0700, Jim Rollenhagen wrote: Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. So after much deliberation, we took an informal vote in IRC this morning between 5 out of our 9 cores. The question was: should we do a 1.12 api version that allows the user to pick begining provision state in (AVAILABLE, ENROLL), defaulting to AVAILABLE? The results were 3 for no, 2 for yes. So that's the plan. Other Ironic cores (Haomeng, Yuriy, Ramesh, Ruby): please chime in if you have opinions on this. :) Otherwise we'll be getting to work on releasing a server as-is in the next few days. // jim __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Mon, Jul 27, 2015 at 01:35:25PM -0700, Jim Rollenhagen wrote: Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. So after much deliberation, we took an informal vote in IRC this morning between 5 out of our 9 cores. The question was: should we do a 1.12 api version that allows the user to pick begining provision state in (AVAILABLE, ENROLL), defaulting to AVAILABLE? The results were 3 for no, 2 for yes. So that's the plan. Other Ironic cores (Haomeng, Yuriy, Ramesh, Ruby): please chime in if you have opinions on this. :) Otherwise we'll be getting to work on releasing a server as-is in the next few days. // jim __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
Hi, It sounds like we all agree -- the client we ship should default to a fixed, older version. Anyone who wants newer functionality can pass a newer version to their client. Here's the current state of things: server: - stable/kilo: 1.6 - current: 1.11 client: - stable/kilo: 1.6 - latest release (0.7.0): 1.6 - current: 1.9 So -- since we haven't released a client that sends a header 1.6, I propose that we set the client back to sending the 1.6 header right away. While having the client default to 1.1 would be ideal, this should still keep the Jackson the Absent of the world as happy as reasonably possible moving forward without breaking anyone that is packaging Kilo already. (yes, this may affect Olivia the Contributor, but that's OK because Olivia will have read this email :) ) There are no backwards incompatible changes from 1.6 to 1.9, so I suggest we just leave it at 1.9 and don't break Jackson nor Olivia (and have no assumptions about who will read this or not). ... Apart from that I think most of the people agreed on the client defaulting to the minimal version (which I'm assuming means 1.1). So what people think? Should we add some warning messages when the version is not specified in the CLI saying we are moving it back to 1.1 on the next releases? And then default it to 1.1 later? Cheers, Lucas __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
It sounds like we all agree -- the client we ship should default to a fixed, older version. Anyone who wants newer functionality can pass a newer version to their client. Here's the current state of things: server: - stable/kilo: 1.6 - current: 1.11 client: - stable/kilo: 1.6 - latest release (0.7.0): 1.6 - current: 1.9 So -- since we haven't released a client that sends a header 1.6, I propose that we set the client back to sending the 1.6 header right away. While having the client default to 1.1 would be ideal, this should still keep the Jackson the Absent of the world as happy as reasonably possible moving forward without breaking anyone that is packaging Kilo already. (yes, this may affect Olivia the Contributor, but that's OK because Olivia will have read this email :) ) -Deva On Fri, Jul 31, 2015 at 2:50 PM Jim Rollenhagen j...@jimrollenhagen.com wrote: On Fri, Jul 31, 2015 at 02:37:52PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-31 04:14:54 -0700: On 07/30/2015 04:58 PM, Devananda van der Veen wrote: snip Thoughts? * I'm assuming it is possible to make micro version changes to the 1.x API as 1.10.1, 1.10.2,etc Despite most folks calling this microversions, I have been trying to simply call this API version negotiation. To your question, no -- the implementations by Nova and Ironic, and the proposal that the API-WG has drafted [1], do not actually support MAJOR.MINOR.PATCH semantics. It has been implemented as a combination of an HTTP request to http(s)://server URL/major/resource URI plus a header X-OpenStack-service-API-Version: major.minor. The major version number is duplicated in both the URI and the header, though Ironic will error if they do not match. Also, there is no patch or micro version. So, were we to change the major version in the header, I would expect that we also change it in the URL, which means registering a new endpoint with Keystone, and, well, all of that. Right, it's important to realize that the microversion mechanism is not semver, intentionally. It's inspired by HTTP content negotiation, as Deva said. I wrote up a lot of the rational for the model in Nova here, which the Ironic model is based off of - https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/ Thanks Sean, this post was exactly what I needed to understand the inspiration behind the current situation. Ironic is a little different. It's entirely an admin API. And most users are going to only talk to an Ironic that they own the deployment schedule on. So the multi cloud that you don't own concern might not be there. But, it would also be confusing to all users if Ironic goes down a different path with microversions, and still calls it the same thing. I think being single-tenant makes the impact of changes different, however the solution can be the same. While tools that use Ironic may not be out in the wild as much from an operator perspective, there will be plenty of tools built to the Ironic API that will want to be distributed to users of various versions of Ironic. It sounds to me like for Ironic, the same assumption should be made as in the outlined Jackson the Absent solution. Assume no version is old version, and require specifying the new version to get any new behavior. What is preventing Ironic from embracing that? So, this is actually how the Ironic API behaves. However, it was at some point decided that the client should have a more recent default version (which is the main topic for this thread). I agree with you; I think this is the best route. // jim __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
2015-07-30 22:58 GMT+02:00 Devananda van der Veen devananda@gmail.com: On Thu, Jul 30, 2015 at 10:21 AM Clint Byrum cl...@fewbar.com wrote: Excerpts from Jim Rollenhagen's message of 2015-07-27 13:35:25 -0700: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Great discussion. I think through this thread I've gained some insight into what is going on, and I think the problem is that minor version bumps are not for backward incompatible changes. As a user, I want to pin everything and move the pins after I've tested and adapted with new versions of things. However, I also don't want to have to micro manage this process while I move forward on different schedules with my REST clients and the Ironic service. So, to be clear, I may have missed what you're trying to do with micro versions. In my world, a 1.10 - 1.11 would be for adding new methods, new arguments, or deprecating (but not removing) an existing piece of the API. But changing the semantics of an existing thing is a major version bump. So I wonder if the right thing to do is to bump to 2.0, make the default in the client 1.10* for now, with deprecation warnings that the major version will not be assumed for future client libraries, and move on with the understanding that micro versions aren't supposed to break users of a particular major version. Thoughts? * I'm assuming it is possible to make micro version changes to the 1.x API as 1.10.1, 1.10.2,etc Despite most folks calling this microversions, I have been trying to simply call this API version negotiation. To your question, no -- the implementations by Nova and Ironic, and the proposal that the API-WG has drafted [1], do not actually support MAJOR.MINOR.PATCH semantics. It has been implemented as a combination of an HTTP request to http(s)://server URL/major/resource URI plus a header X-OpenStack-service-API-Version: major.minor. What if we break this assumption? I.e. we call version in URL a family version (or epoch, using more common terminology)? Then we can have API versioning completely independent, bump major when needed etc. Nothing can be done in ENROLL case IMO, but in the future we would make such change a 3.0 version, and could backport changes to 2.X branch for some (hopefully short) time. I'm also really fond of idea of allowing people to request 1.latest, 2.latest, etc in this case, where 2.latest would mean gimme all features which I can receive without breaking, provided that I'm compatible with 2.x branch. The major version number is duplicated in both the URI and the header, though Ironic will error if they do not match. Also, there is no patch or micro version. So, were we to change the major version in the header, I would expect that we also change it in the URL, which means registering a new endpoint with Keystone, and, well, all of that. -D [1] https://review.openstack.org/#/c/187112/ __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- -- -- Dmitry Tantsur -- __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Fri, Jul 31, 2015 at 02:37:52PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-31 04:14:54 -0700: On 07/30/2015 04:58 PM, Devananda van der Veen wrote: snip Thoughts? * I'm assuming it is possible to make micro version changes to the 1.x API as 1.10.1, 1.10.2,etc Despite most folks calling this microversions, I have been trying to simply call this API version negotiation. To your question, no -- the implementations by Nova and Ironic, and the proposal that the API-WG has drafted [1], do not actually support MAJOR.MINOR.PATCH semantics. It has been implemented as a combination of an HTTP request to http(s)://server URL/major/resource URI plus a header X-OpenStack-service-API-Version: major.minor. The major version number is duplicated in both the URI and the header, though Ironic will error if they do not match. Also, there is no patch or micro version. So, were we to change the major version in the header, I would expect that we also change it in the URL, which means registering a new endpoint with Keystone, and, well, all of that. Right, it's important to realize that the microversion mechanism is not semver, intentionally. It's inspired by HTTP content negotiation, as Deva said. I wrote up a lot of the rational for the model in Nova here, which the Ironic model is based off of - https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/ Thanks Sean, this post was exactly what I needed to understand the inspiration behind the current situation. Ironic is a little different. It's entirely an admin API. And most users are going to only talk to an Ironic that they own the deployment schedule on. So the multi cloud that you don't own concern might not be there. But, it would also be confusing to all users if Ironic goes down a different path with microversions, and still calls it the same thing. I think being single-tenant makes the impact of changes different, however the solution can be the same. While tools that use Ironic may not be out in the wild as much from an operator perspective, there will be plenty of tools built to the Ironic API that will want to be distributed to users of various versions of Ironic. It sounds to me like for Ironic, the same assumption should be made as in the outlined Jackson the Absent solution. Assume no version is old version, and require specifying the new version to get any new behavior. What is preventing Ironic from embracing that? So, this is actually how the Ironic API behaves. However, it was at some point decided that the client should have a more recent default version (which is the main topic for this thread). I agree with you; I think this is the best route. // jim __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
Excerpts from Sean Dague's message of 2015-07-31 04:14:54 -0700: On 07/30/2015 04:58 PM, Devananda van der Veen wrote: snip Thoughts? * I'm assuming it is possible to make micro version changes to the 1.x API as 1.10.1, 1.10.2,etc Despite most folks calling this microversions, I have been trying to simply call this API version negotiation. To your question, no -- the implementations by Nova and Ironic, and the proposal that the API-WG has drafted [1], do not actually support MAJOR.MINOR.PATCH semantics. It has been implemented as a combination of an HTTP request to http(s)://server URL/major/resource URI plus a header X-OpenStack-service-API-Version: major.minor. The major version number is duplicated in both the URI and the header, though Ironic will error if they do not match. Also, there is no patch or micro version. So, were we to change the major version in the header, I would expect that we also change it in the URL, which means registering a new endpoint with Keystone, and, well, all of that. Right, it's important to realize that the microversion mechanism is not semver, intentionally. It's inspired by HTTP content negotiation, as Deva said. I wrote up a lot of the rational for the model in Nova here, which the Ironic model is based off of - https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/ Thanks Sean, this post was exactly what I needed to understand the inspiration behind the current situation. Ironic is a little different. It's entirely an admin API. And most users are going to only talk to an Ironic that they own the deployment schedule on. So the multi cloud that you don't own concern might not be there. But, it would also be confusing to all users if Ironic goes down a different path with microversions, and still calls it the same thing. I think being single-tenant makes the impact of changes different, however the solution can be the same. While tools that use Ironic may not be out in the wild as much from an operator perspective, there will be plenty of tools built to the Ironic API that will want to be distributed to users of various versions of Ironic. It sounds to me like for Ironic, the same assumption should be made as in the outlined Jackson the Absent solution. Assume no version is old version, and require specifying the new version to get any new behavior. What is preventing Ironic from embracing that? __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 07/30/2015 04:58 PM, Devananda van der Veen wrote: snip Thoughts? * I'm assuming it is possible to make micro version changes to the 1.x API as 1.10.1, 1.10.2,etc Despite most folks calling this microversions, I have been trying to simply call this API version negotiation. To your question, no -- the implementations by Nova and Ironic, and the proposal that the API-WG has drafted [1], do not actually support MAJOR.MINOR.PATCH semantics. It has been implemented as a combination of an HTTP request to http(s)://server URL/major/resource URI plus a header X-OpenStack-service-API-Version: major.minor. The major version number is duplicated in both the URI and the header, though Ironic will error if they do not match. Also, there is no patch or micro version. So, were we to change the major version in the header, I would expect that we also change it in the URL, which means registering a new endpoint with Keystone, and, well, all of that. Right, it's important to realize that the microversion mechanism is not semver, intentionally. It's inspired by HTTP content negotiation, as Deva said. I wrote up a lot of the rational for the model in Nova here, which the Ironic model is based off of - https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/ Ironic is a little different. It's entirely an admin API. And most users are going to only talk to an Ironic that they own the deployment schedule on. So the multi cloud that you don't own concern might not be there. But, it would also be confusing to all users if Ironic goes down a different path with microversions, and still calls it the same thing. Fwiw, we just landed our when do you need a microversion document which might also ad context here - http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion -Sean -- Sean Dague http://dague.net __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Thu, Jul 30, 2015 at 10:21 AM Clint Byrum cl...@fewbar.com wrote: Excerpts from Jim Rollenhagen's message of 2015-07-27 13:35:25 -0700: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Great discussion. I think through this thread I've gained some insight into what is going on, and I think the problem is that minor version bumps are not for backward incompatible changes. As a user, I want to pin everything and move the pins after I've tested and adapted with new versions of things. However, I also don't want to have to micro manage this process while I move forward on different schedules with my REST clients and the Ironic service. So, to be clear, I may have missed what you're trying to do with micro versions. In my world, a 1.10 - 1.11 would be for adding new methods, new arguments, or deprecating (but not removing) an existing piece of the API. But changing the semantics of an existing thing is a major version bump. So I wonder if the right thing to do is to bump to 2.0, make the default in the client 1.10* for now, with deprecation warnings that the major version will not be assumed for future client libraries, and move on with the understanding that micro versions aren't supposed to break users of a particular major version. Thoughts? * I'm assuming it is possible to make micro version changes to the 1.x API as 1.10.1, 1.10.2,etc Despite most folks calling this microversions, I have been trying to simply call this API version negotiation. To your question, no -- the implementations by Nova and Ironic, and the proposal that the API-WG has drafted [1], do not actually support MAJOR.MINOR.PATCH semantics. It has been implemented as a combination of an HTTP request to http(s)://server URL/major/resource URI plus a header X-OpenStack-service-API-Version: major.minor. The major version number is duplicated in both the URI and the header, though Ironic will error if they do not match. Also, there is no patch or micro version. So, were we to change the major version in the header, I would expect that we also change it in the URL, which means registering a new endpoint with Keystone, and, well, all of that. -D [1] https://review.openstack.org/#/c/187112/ __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
Excerpts from Jim Rollenhagen's message of 2015-07-27 13:35:25 -0700: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Great discussion. I think through this thread I've gained some insight into what is going on, and I think the problem is that minor version bumps are not for backward incompatible changes. As a user, I want to pin everything and move the pins after I've tested and adapted with new versions of things. However, I also don't want to have to micro manage this process while I move forward on different schedules with my REST clients and the Ironic service. So, to be clear, I may have missed what you're trying to do with micro versions. In my world, a 1.10 - 1.11 would be for adding new methods, new arguments, or deprecating (but not removing) an existing piece of the API. But changing the semantics of an existing thing is a major version bump. So I wonder if the right thing to do is to bump to 2.0, make the default in the client 1.10* for now, with deprecation warnings that the major version will not be assumed for future client libraries, and move on with the understanding that micro versions aren't supposed to break users of a particular major version. Thoughts? * I'm assuming it is possible to make micro version changes to the 1.x API as 1.10.1, 1.10.2,etc __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 6:05 AM, Jim Rollenhagen j...@jimrollenhagen.com wrote: [snip] It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. 4) Require a version to use the client at all. This would be a one-time break with how applications initialize the client (perhaps we could fall back to the earliest version or something for a deprecation period). This isn't a great user experience, however, it's the best way to get users to think about versioning. And no, this requires typing another argument every time! is not a valid argument against this; we already require a number of arguments, anyone sane doesn't type --ironic-api-url or --os-username every time they use the client. 5) Do what we're doing now. Bump the client's default version with every release. This mostly hides these versions from end users, and in general those users probably won't know they exist. And then we run into arguments every time we want to make a breaking change to the API. :) I think I like option 1 or 3 the best. I certainly don't like option 5 because we're going to break users every time we release a new client. What do other folks think we should do? Thanks jroll for bringing this up! Isn't the problem here that we're treating breaking and non-breaking changes similarly? Didn't we previously say that major backward incompatible changes should require a major version bump? What if we adopted a semver or similar scheme for API versioning? What if we required 'Major' (in Major.Minor.Patch) to increment for a backwards incompatible change? In our current tooling this would be hard, but is it what we should be doing? Is this the root of the problem? I think we want the latest version of the API, used by the client and server, that is backwards compatible i.e. min(latest client version, latest server version). As developers we want the latest version of our code out there. As operators and users we want the latest (backward compatible) features and the bug fixes, but we don't want to rewrite how we interface to the software. But if a version is explicitly specified, that should be used instead i.e. we should support version pining so that operators can gracefully upgrade when it's right for them (assuming the server still supports that version) But the question remains, What version of the API do we want to ship when we ship a major Ironic release? (whenever that is now[1] :-P ) Or phrased differently, How do we advance versions from release to release?. I think the answer to this is that we default to the latest stable major API version at the point of release. That should be the default for client and server, and shouldn't discount anyone from using older clients with newer servers and vice versa due to the presence of version negotiation. Hope this helps, Michael... [1] https://github.com/openstack/ironic-specs/blob/master/specs/liberty/feature-based-releases.rst -- Michael Davies mich...@the-davies.net Rackspace Cloud Builders Australia __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 07/30/2015 12:55 AM, Michael Davies wrote: On Tue, Jul 28, 2015 at 6:05 AM, Jim Rollenhagen j...@jimrollenhagen.com mailto:j...@jimrollenhagen.com wrote: [snip] It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. 4) Require a version to use the client at all. This would be a one-time break with how applications initialize the client (perhaps we could fall back to the earliest version or something for a deprecation period). This isn't a great user experience, however, it's the best way to get users to think about versioning. And no, this requires typing another argument every time! is not a valid argument against this; we already require a number of arguments, anyone sane doesn't type --ironic-api-url or --os-username every time they use the client. 5) Do what we're doing now. Bump the client's default version with every release. This mostly hides these versions from end users, and in general those users probably won't know they exist. And then we run into arguments every time we want to make a breaking change to the API. :) I think I like option 1 or 3 the best. I certainly don't like option 5 because we're going to break users every time we release a new client. What do other folks think we should do? Thanks jroll for bringing this up! Isn't the problem here that we're treating breaking and non-breaking changes similarly? Didn't we previously say that major backward incompatible changes should require a major version bump? What if we adopted a semver or similar scheme for API versioning? What if we required 'Major' (in Major.Minor.Patch) to increment for a backwards incompatible change? In our current tooling this would be hard, but is it what we should be doing? Is this the root of the problem? It seems to me that this is basically microversions except that it gives you the added knowledge that a backwards incompatible change has occurred. I'm not quite clear how that makes any difference though. For applications linking against libraries, the major version implies a dependency--the application requires that specific major version of the library, and a minor version at least as good as what it was built against. How would that translate to a REST API? Would the client code need to special-case every major version that they plan on supporting? What about minor versions that add functionality--if we special-case those as well then we're basically back to microversions. Chris __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 07/28/2015 10:51 PM, Devananda van der Veen wrote: On Tue, Jul 28, 2015 at 1:01 AM Dmitry Tantsur dtant...@redhat.com mailto:dtant...@redhat.com wrote: On 07/27/2015 10:41 PM, Sean Dague wrote: On 07/27/2015 04:35 PM, Jim Rollenhagen wrote: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. Actually what Nova is doing is slight different than this, the CLI will default to latest on the server. There will be an extra round trip to figure out what that is. And the CLI will (long term) just not present commands that aren't available at the server level you are talking to. Consider the CLI an auto negotiating microversion application of the python API client. And, realistically, should solve some of the issues of people running nova foo and getting cryptic errors from the server when they are hitting an old version of Nova that doesn't know how to foo. So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find weird about this and similar approaches is that we treat CLI and any different from other ways to use API. And I *suspect* this is because we, the developers, use it the most and point newcomers to it. And I agree it's troublesome to explain that to use manage provision verb you have to provide --ironic-api-version 1.6. Or was 1.6 for inspect? Hmm, I really don't remember. CLI is not different, CLI is not special and CLI is not an auto negotiating microversion application of the python API client. By saying any of these we just refusing it eat our dog's food. If we consciously believe (I personally don't) that versioning is the right thing to do for people using our API - lets stop dodging it ourselves. Otherwise it looks like we've invented an architecture that people presumably dream of, but we don't know if it's even usable (to say nothing about useful). I tried writing versioning-aware code for our devstack yesterday, and it wasn't that nice and shiny. If our versioning requires negotiations, lets have it on API level, so that all users get it. Actually, server has the same level of information as the client. Let's have X-OpenStack-XXX-Version: negotiate figure out a proper version for us - or refuse to process a request if it's not possible. And if we think that versioning as it is now is
Re: [openstack-dev] [Ironic] Let's talk about API versions
1. yes 2. no -- the client should default to the minimum supported version. We got that wrong previously, and that's what is hurting us now. So if we do this, simply shipping the code doesn't break anyone. Nobody has disagreed on this yet, best I can tell. We would still need a deprecation period here if we want to have the client to default to the minimum supported version again. People using the client may be relying on the features up to version 1.9 (which is the pinned one right now). __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
After reading through this thread as a whole, I¹d like to summarise my thoughts so far: * I've noticed all these discussions revolve around existing people using the API, and seem to ignore that most new users of the API don¹t care how it used to work, and just want the full feature set without having to opt-in². * While I was reading the thread, I realised how much I hate calling the client a client, I don¹t think we should think of it as a client (like a messaging or mail client) because it distances it from the actual API, I see it as a python API hook and as an API command line interface that you would build clients with. The level of abstraction should be just enough but not so much that it feels like a separate thing from the REST API. So if we solve the problem for the REST API then I think the python and command line should expose it in the same way. And I personally feel that explicit is the way forward, and if you don¹t specify a version we should error, provide no default, and no fall back, for those who don¹t want to use a specific version or are happy with whatever they are given, we should provide keywords that can be given instead of a version such as ³latest², ³given or something to that effect. In this situation everyone knows what they are getting. - Sam On 29/07/2015 10:01, Lucas Alvares Gomes lucasago...@gmail.com wrote: 1. yes 2. no -- the client should default to the minimum supported version. We got that wrong previously, and that's what is hurting us now. So if we do this, simply shipping the code doesn't break anyone. Nobody has disagreed on this yet, best I can tell. We would still need a deprecation period here if we want to have the client to default to the minimum supported version again. People using the client may be relying on the features up to version 1.9 (which is the pinned one right now). __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 07/27/2015 10:41 PM, Sean Dague wrote: On 07/27/2015 04:35 PM, Jim Rollenhagen wrote: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. Actually what Nova is doing is slight different than this, the CLI will default to latest on the server. There will be an extra round trip to figure out what that is. And the CLI will (long term) just not present commands that aren't available at the server level you are talking to. Consider the CLI an auto negotiating microversion application of the python API client. And, realistically, should solve some of the issues of people running nova foo and getting cryptic errors from the server when they are hitting an old version of Nova that doesn't know how to foo. So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find weird about this and similar approaches is that we treat CLI and any different from other ways to use API. And I *suspect* this is because we, the developers, use it the most and point newcomers to it. And I agree it's troublesome to explain that to use manage provision verb you have to provide --ironic-api-version 1.6. Or was 1.6 for inspect? Hmm, I really don't remember. CLI is not different, CLI is not special and CLI is not an auto negotiating microversion application of the python API client. By saying any of these we just refusing it eat our dog's food. If we consciously believe (I personally don't) that versioning is the right thing to do for people using our API - lets stop dodging it ourselves. Otherwise it looks like we've invented an architecture that people presumably dream of, but we don't know if it's even usable (to say nothing about useful). I tried writing versioning-aware code for our devstack yesterday, and it wasn't that nice and shiny. If our versioning requires negotiations, lets have it on API level, so that all users get it. Actually, server has the same level of information as the client. Let's have X-OpenStack-XXX-Version: negotiate figure out a proper version for us - or refuse to process a request if it's not possible. And if we think that versioning as it is now is unusable at all, lets rework the whole idea. tl;dr my vote if for CLI to strictly follow whatever server API does. That is, default to the lowest version, require explicit version argument to get new features. (it's up to a follow up discussion what to do during the deprecation period). -Sean __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 5:30 PM, Jim Rollenhagen j...@jimrollenhagen.com wrote: On Tue, Jul 28, 2015 at 09:19:46PM +, Devananda van der Veen wrote: On Tue, Jul 28, 2015 at 1:57 PM Jim Rollenhagen j...@jimrollenhagen.com wrote: On Tue, Jul 28, 2015 at 08:23:34PM +, Devananda van der Veen wrote: On Mon, Jul 27, 2015 at 4:58 PM Sean Dague s...@dague.net wrote: On 07/27/2015 07:10 PM, Jim Rollenhagen wrote: On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. Faithful representation of the API is an interesting way to put it; it is a faithful representation either way. This way is a representation of the newest state of the API. It sounds like you're expecting a representation of the oldest state, or the state that you're used to (the hardest to predict). So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. I tend to think that folks using the CLI for automation should be pinning the version in that automation. A quick IRONIC_API_VERSION=1.8 or whatever would solve this problem. When new versions are available, read the notes for that version and adjust your code as necessary. Or just leave it at the same version until it breaks. :) Yeh, it's a cli, not a bash API. Having had to maintain devstack exercise code for a while, I'll tell you that the above is just a time bomb waiting to go off. None of the CLIs have that kind of contract, nor should they. Inflicting the bad UX of today on future generations because someone thinks, incorrectly, that it's a bash SDK is not a good trade off. And people script against that CLI all. the. time. Is it pretty? No. But is it something that people do? Yep. Does that mean we should try to care? Yea, I think so, and I think that means we should try to avoid breaking it when reasonably possible. If you want to pin things, explicitly, like jroll said, do that. And microversions lets you until your clouds uplift past your legacy code. if you want to pin the version != all users must explicitly specify the version I believe Jim is advocating for the latter. I'm advocating for the former. The problem that I'm now seeing is you're advocating not just that people should be able to pin a version. You're advocating for: 1. People don't need to pin the version. Fine. 1.1. Side note: perhaps you're actually advocating for people should not need to pin the version? It's starting to sound that way. 2. The client should always default to the most recent compatible version. Fine. 3. We should never break a user. Fine. 4. 1-3 must all be true always. Not fine. We can't reasonably make progress while having the latest API version be compatible with the previous API version. The combination above breaks down when we also want to continue to produce software (preferably quickly). We need to let one of those things go; they can't all be true at the same time. I think the best thing to let go is 1 or 2, personally. Where we are today is letting 3 go, and that's why we're stuck here. Mmmm, close. I think I expanded on that in my last email (replying to Dmitry) ... but... tldr; 1. yes 2. no -- the client should default to the minimum supported version. We got that wrong previously, and that's what is hurting us now. So if we do this, simply shipping the code doesn't break anyone. Nobody has disagreed on this yet, best I can tell. So let's ship some code. :) // jim I'm not sure we can just ship some code, unless I've missed something in the discussion, at some point a user/operator workflow could still break if a future user client is upgraded with the current
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 09:55:03PM -0400, Julia Kreger wrote: So if we do this, simply shipping the code doesn't break anyone. Nobody has disagreed on this yet, best I can tell. So let's ship some code. :) // jim I'm not sure we can just ship some code, unless I've missed something in the discussion, at some point a user/operator workflow could still break if a future user client is upgraded with the current server code. Now if this is something the Ironic community is willing to accept, as I personally thought was originally the case, then that is another matter. My $0.02 is that forcing a workflow change should be handled with a deprecation period while avoiding the hard breaking change for the user workflow, because it is akin to taking away a feature, or in this case, forcing the user to use a feature they may not want nor need. What if we revert 523da21cd3f5fc3299f9b91ac6d885f0fb54eddb and 1410e59228c3835cfc4f89db1ec482137a3cfa10 in order to cut a release, then revert the reverts while layering on top a server side fix to remove the hard break for users? So that's the other part here - even if we have a way to make 1.11 easier for users to swallow, we can't. There are people that deploy master out there, so we need to treat master as already released. If we change how the enroll API works (again), that needs to be 1.12. If we revert it, that also needs to be 1.12, with 1.11 carrying the current code. // jim __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
Hi, Could you combine 1 and 4? Deprecate not specifying the version, but pin to the oldest one for now? That way users get the warnings that they need to adapt, but things keep working? Could be switched to just 4 after a few months. This is similar to what I would like to suggest. But I would leave the pin at the current version we have right now (which is 1.9 [1]) instead of the earliest one; We then add some deprecation messages when the user do not specify a version. Otherwise we may break people that are currently using the features up to version we have pinned right now. In the long run I think that option 4. is the best option. As @Jim already pointed out from a UX point of view it's not that it will make anything worse since we already require a number of arguments. This will also makes users understand the versions we provide and pin his environment at a specific version, that way it will not break due future changes to our API and he/she can, at his/her own pace, update his/her systems to a newest version knowing that he/she already has a version that works. I say that having just added some IP addresses to a server with iproute2, which has been telling me for probably 10 years that _not_ adding /32 to single IP's will eventually be deprecated... Heh we should be faster than that (-: [1] https://github.com/openstack/python-ironicclient/blob/52f4ba68ba8a2e45875783c3240fe58f27fa54c6/ironicclient/common/http.py#L40 Cheers, Lucas __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
I'm going to reply to several emails in this thread - but separately, because they're from separate people and with separate POV, and I think it will be even harder to discern what I'm saying if I merge the contexts before replying... so bear with me ... On Mon, Jul 27, 2015 at 1:36 PM Jim Rollenhagen j...@jimrollenhagen.com wrote: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. No, that patch isn't backwards compatible -- ** but it could be **. That's the biggest reason that I disagree with what's proposed here -- it would be trivially easy for us to make this change be backwards compatible by allowing an optional parameter in the POST command that changes the initial state of a node from AVAILABLE to ENROLL. Allow users to opt-in to the new behavior *and* discover its presence from the API version header. There is simply no reason for this to be a breaking change. I simply do not understand how folks think we can version the API means we should break users even when we don't have to. Anyway, I've said that before. There are other points I want to respond to as well, so I'll carry on... It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. The current approach is supposed to allow users to make use of new features as they become available, while also ensuring they don’t break due to incompatibilities [0] However, you're advocating against providing that right now -- if a user wants a feature added in 1.12, they will be forced to accept the breaking change in 1.11. While I have proposed some changes to our specification for API versioning [1], removing this statement of intent is not one of the changes I've proposed. [0] http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html#problem-description [1] https://review.openstack.org/#/c/196320/2/specs/devref/api-version-negotiation.rst,cm This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. You're conflating user and operator -- which I understand, because you are both. But not everyone is, and I'm concerned about the impact on users who are not operators. I'd say maybe we have none of those, except then I hear from folks like Clint that they care about this sort of change and how it affects them. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. The intent is to allow users' tooling to continue working while we evolve the REST API *and* to give users the ability to work with both old and new service installations (eg, because the user doesn't control what version of server they are using). Again, that goal is based on the assumption that some users are not also operators. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. In an environment where a user is interacting with 1 Ironic service of different versions, this default would lead to what I'll just call odd behavior. It ends up being your option 4 implicitly, to avoid frustration. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. 4) Require a version to use the client at all. This would be a one-time break with how applications initialize the client
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 08:23:34PM +, Devananda van der Veen wrote: On Mon, Jul 27, 2015 at 4:58 PM Sean Dague s...@dague.net wrote: On 07/27/2015 07:10 PM, Jim Rollenhagen wrote: On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. Faithful representation of the API is an interesting way to put it; it is a faithful representation either way. This way is a representation of the newest state of the API. It sounds like you're expecting a representation of the oldest state, or the state that you're used to (the hardest to predict). So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. I tend to think that folks using the CLI for automation should be pinning the version in that automation. A quick IRONIC_API_VERSION=1.8 or whatever would solve this problem. When new versions are available, read the notes for that version and adjust your code as necessary. Or just leave it at the same version until it breaks. :) Yeh, it's a cli, not a bash API. Having had to maintain devstack exercise code for a while, I'll tell you that the above is just a time bomb waiting to go off. None of the CLIs have that kind of contract, nor should they. Inflicting the bad UX of today on future generations because someone thinks, incorrectly, that it's a bash SDK is not a good trade off. And people script against that CLI all. the. time. Is it pretty? No. But is it something that people do? Yep. Does that mean we should try to care? Yea, I think so, and I think that means we should try to avoid breaking it when reasonably possible. If you want to pin things, explicitly, like jroll said, do that. And microversions lets you until your clouds uplift past your legacy code. if you want to pin the version != all users must explicitly specify the version I believe Jim is advocating for the latter. I'm advocating for the former. The problem that I'm now seeing is you're advocating not just that people should be able to pin a version. You're advocating for: 1. People don't need to pin the version. Fine. 1.1. Side note: perhaps you're actually advocating for people should not need to pin the version? It's starting to sound that way. 2. The client should always default to the most recent compatible version. Fine. 3. We should never break a user. Fine. 4. 1-3 must all be true always. Not fine. We can't reasonably make progress while having the latest API version be compatible with the previous API version. The combination above breaks down when we also want to continue to produce software (preferably quickly). We need to let one of those things go; they can't all be true at the same time. I think the best thing to let go is 1 or 2, personally. Where we are today is letting 3 go, and that's why we're stuck here. // jim -Deva __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 1:57 PM Jim Rollenhagen j...@jimrollenhagen.com wrote: On Tue, Jul 28, 2015 at 08:23:34PM +, Devananda van der Veen wrote: On Mon, Jul 27, 2015 at 4:58 PM Sean Dague s...@dague.net wrote: On 07/27/2015 07:10 PM, Jim Rollenhagen wrote: On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. Faithful representation of the API is an interesting way to put it; it is a faithful representation either way. This way is a representation of the newest state of the API. It sounds like you're expecting a representation of the oldest state, or the state that you're used to (the hardest to predict). So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. I tend to think that folks using the CLI for automation should be pinning the version in that automation. A quick IRONIC_API_VERSION=1.8 or whatever would solve this problem. When new versions are available, read the notes for that version and adjust your code as necessary. Or just leave it at the same version until it breaks. :) Yeh, it's a cli, not a bash API. Having had to maintain devstack exercise code for a while, I'll tell you that the above is just a time bomb waiting to go off. None of the CLIs have that kind of contract, nor should they. Inflicting the bad UX of today on future generations because someone thinks, incorrectly, that it's a bash SDK is not a good trade off. And people script against that CLI all. the. time. Is it pretty? No. But is it something that people do? Yep. Does that mean we should try to care? Yea, I think so, and I think that means we should try to avoid breaking it when reasonably possible. If you want to pin things, explicitly, like jroll said, do that. And microversions lets you until your clouds uplift past your legacy code. if you want to pin the version != all users must explicitly specify the version I believe Jim is advocating for the latter. I'm advocating for the former. The problem that I'm now seeing is you're advocating not just that people should be able to pin a version. You're advocating for: 1. People don't need to pin the version. Fine. 1.1. Side note: perhaps you're actually advocating for people should not need to pin the version? It's starting to sound that way. 2. The client should always default to the most recent compatible version. Fine. 3. We should never break a user. Fine. 4. 1-3 must all be true always. Not fine. We can't reasonably make progress while having the latest API version be compatible with the previous API version. The combination above breaks down when we also want to continue to produce software (preferably quickly). We need to let one of those things go; they can't all be true at the same time. I think the best thing to let go is 1 or 2, personally. Where we are today is letting 3 go, and that's why we're stuck here. Mmmm, close. I think I expanded on that in my last email (replying to Dmitry) ... but... tldr; 1. yes 2. no -- the client should default to the minimum supported version. We got that wrong previously, and that's what is hurting us now. 3. not quite -- we should be very intentional when ever we're going to break a user AND we should only do it when there is no other option AND we must provide a lot of warning and deprecation period. -Deva // jim -Deva __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 08:05:49PM +, Devananda van der Veen wrote: I'm going to reply to several emails in this thread - but separately, because they're from separate people and with separate POV, and I think it will be even harder to discern what I'm saying if I merge the contexts before replying... so bear with me ... On Mon, Jul 27, 2015 at 1:36 PM Jim Rollenhagen j...@jimrollenhagen.com wrote: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. No, that patch isn't backwards compatible -- ** but it could be **. That's the biggest reason that I disagree with what's proposed here -- it would be trivially easy for us to make this change be backwards compatible by allowing an optional parameter in the POST command that changes the initial state of a node from AVAILABLE to ENROLL. Allow users to opt-in to the new behavior *and* discover its presence from the API version header. There is simply no reason for this to be a breaking change. I simply do not understand how folks think we can version the API means we should break users even when we don't have to. I tend to think specifying that version *is* opting in. Anyway, I've said that before. There are other points I want to respond to as well, so I'll carry on... It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. The current approach is supposed to allow users to make use of new features as they become available, while also ensuring they don’t break due to incompatibilities [0] However, you're advocating against providing that right now -- if a user wants a feature added in 1.12, they will be forced to accept the breaking change in 1.11. I believe stating that users won't put in work to make their software work with the breaking change in 1.11, but will put in work to use a feature in 1.12, is a bit of a logical fallacy. However, even if someone gets themselves into that situation, there's nothing wrong with them using 1.11 for the call that breaks them, and 1.12 for the others. While I have proposed some changes to our specification for API versioning [1], removing this statement of intent is not one of the changes I've proposed. [0] http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html#problem-description [1] https://review.openstack.org/#/c/196320/2/specs/devref/api-version-negotiation.rst,cm This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. You're conflating user and operator -- which I understand, because you are both. But not everyone is, and I'm concerned about the impact on users who are not operators. I'd say maybe we have none of those, except then I hear from folks like Clint that they care about this sort of change and how it affects them. In an admin-only API, I tend to think operators and users are very close, if not the same. I also think that: 1) API version things, especially incompatibilities, should also be in the release notes for the client. 2) Operators should be distributing release notes that affect users to the users. When I deploy a new version of Ironic, I certainly distribute a note with any changes other users/operators should be aware of. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. The intent is to allow users' tooling to continue working while we evolve the REST API *and* to give users the ability to work with both old and new service installations (eg, because the user doesn't control what version of server they are using). If the user pins the version, this just works. Again,
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 09:19:46PM +, Devananda van der Veen wrote: On Tue, Jul 28, 2015 at 1:57 PM Jim Rollenhagen j...@jimrollenhagen.com wrote: On Tue, Jul 28, 2015 at 08:23:34PM +, Devananda van der Veen wrote: On Mon, Jul 27, 2015 at 4:58 PM Sean Dague s...@dague.net wrote: On 07/27/2015 07:10 PM, Jim Rollenhagen wrote: On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. Faithful representation of the API is an interesting way to put it; it is a faithful representation either way. This way is a representation of the newest state of the API. It sounds like you're expecting a representation of the oldest state, or the state that you're used to (the hardest to predict). So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. I tend to think that folks using the CLI for automation should be pinning the version in that automation. A quick IRONIC_API_VERSION=1.8 or whatever would solve this problem. When new versions are available, read the notes for that version and adjust your code as necessary. Or just leave it at the same version until it breaks. :) Yeh, it's a cli, not a bash API. Having had to maintain devstack exercise code for a while, I'll tell you that the above is just a time bomb waiting to go off. None of the CLIs have that kind of contract, nor should they. Inflicting the bad UX of today on future generations because someone thinks, incorrectly, that it's a bash SDK is not a good trade off. And people script against that CLI all. the. time. Is it pretty? No. But is it something that people do? Yep. Does that mean we should try to care? Yea, I think so, and I think that means we should try to avoid breaking it when reasonably possible. If you want to pin things, explicitly, like jroll said, do that. And microversions lets you until your clouds uplift past your legacy code. if you want to pin the version != all users must explicitly specify the version I believe Jim is advocating for the latter. I'm advocating for the former. The problem that I'm now seeing is you're advocating not just that people should be able to pin a version. You're advocating for: 1. People don't need to pin the version. Fine. 1.1. Side note: perhaps you're actually advocating for people should not need to pin the version? It's starting to sound that way. 2. The client should always default to the most recent compatible version. Fine. 3. We should never break a user. Fine. 4. 1-3 must all be true always. Not fine. We can't reasonably make progress while having the latest API version be compatible with the previous API version. The combination above breaks down when we also want to continue to produce software (preferably quickly). We need to let one of those things go; they can't all be true at the same time. I think the best thing to let go is 1 or 2, personally. Where we are today is letting 3 go, and that's why we're stuck here. Mmmm, close. I think I expanded on that in my last email (replying to Dmitry) ... but... tldr; 1. yes 2. no -- the client should default to the minimum supported version. We got that wrong previously, and that's what is hurting us now. So if we do this, simply shipping the code doesn't break anyone. Nobody has disagreed on this yet, best I can tell. So let's ship some code. :) // jim 3. not quite -- we should be very intentional when ever we're going to break a user AND we should only do it when there is no other option AND we must provide a lot of warning and deprecation period. -Deva // jim -Deva __ OpenStack Development Mailing List (not for usage questions) Unsubscribe:
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Mon, Jul 27, 2015 at 4:58 PM Sean Dague s...@dague.net wrote: On 07/27/2015 07:10 PM, Jim Rollenhagen wrote: On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. Faithful representation of the API is an interesting way to put it; it is a faithful representation either way. This way is a representation of the newest state of the API. It sounds like you're expecting a representation of the oldest state, or the state that you're used to (the hardest to predict). So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. I tend to think that folks using the CLI for automation should be pinning the version in that automation. A quick IRONIC_API_VERSION=1.8 or whatever would solve this problem. When new versions are available, read the notes for that version and adjust your code as necessary. Or just leave it at the same version until it breaks. :) Yeh, it's a cli, not a bash API. Having had to maintain devstack exercise code for a while, I'll tell you that the above is just a time bomb waiting to go off. None of the CLIs have that kind of contract, nor should they. Inflicting the bad UX of today on future generations because someone thinks, incorrectly, that it's a bash SDK is not a good trade off. And people script against that CLI all. the. time. Is it pretty? No. But is it something that people do? Yep. Does that mean we should try to care? Yea, I think so, and I think that means we should try to avoid breaking it when reasonably possible. If you want to pin things, explicitly, like jroll said, do that. And microversions lets you until your clouds uplift past your legacy code. if you want to pin the version != all users must explicitly specify the version I believe Jim is advocating for the latter. I'm advocating for the former. -Deva __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Mon, Jul 27, 2015 at 1:41 PM Sean Dague s...@dague.net wrote: Consider the CLI an auto negotiating microversion application of the python API client. And, realistically, should solve some of the issues of people running nova foo and getting cryptic errors from the server when they are hitting an old version of Nova that doesn't know how to foo. So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. Not a lot to add here -- except to agree and say that the client breaking in predictable and helpful ways (like giving a useful error message about a feature not being available in an older service) is far better for users, and easier for developers to implement with version headers than it was before. And that's a win for users, IMO. -Deva __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Tue, Jul 28, 2015 at 1:01 AM Dmitry Tantsur dtant...@redhat.com wrote: On 07/27/2015 10:41 PM, Sean Dague wrote: On 07/27/2015 04:35 PM, Jim Rollenhagen wrote: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. Actually what Nova is doing is slight different than this, the CLI will default to latest on the server. There will be an extra round trip to figure out what that is. And the CLI will (long term) just not present commands that aren't available at the server level you are talking to. Consider the CLI an auto negotiating microversion application of the python API client. And, realistically, should solve some of the issues of people running nova foo and getting cryptic errors from the server when they are hitting an old version of Nova that doesn't know how to foo. So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find weird about this and similar approaches is that we treat CLI and any different from other ways to use API. And I *suspect* this is because we, the developers, use it the most and point newcomers to it. And I agree it's troublesome to explain that to use manage provision verb you have to provide --ironic-api-version 1.6. Or was 1.6 for inspect? Hmm, I really don't remember. CLI is not different, CLI is not special and CLI is not an auto negotiating microversion application of the python API client. By saying any of these we just refusing it eat our dog's food. If we consciously believe (I personally don't) that versioning is the right thing to do for people using our API - lets stop dodging it ourselves. Otherwise it looks like we've invented an architecture that people presumably dream of, but we don't know if it's even usable (to say nothing about useful). I tried writing versioning-aware code for our devstack yesterday, and it wasn't that nice and shiny. If our versioning requires negotiations, lets have it on API level, so that all users get it. Actually, server has the same level of information as the client. Let's have X-OpenStack-XXX-Version: negotiate figure out a proper version for us - or refuse to process a request if it's not possible. And if we think that versioning as it is now is unusable at all, lets rework the whole idea. tl;dr my vote if for CLI to strictly follow whatever server API does. That is, default to the lowest version, require explicit version argument to get new features. (it's up to a follow up discussion what to do during the deprecation period). Hi Dmitry, I appreciate a good rant as much as anyone -- and I post them, too -- but aside from the last paragraph, it's hard for me to tell what your intent here is, so I'm going to take a
[openstack-dev] [Ironic] Let's talk about API versions
Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. 4) Require a version to use the client at all. This would be a one-time break with how applications initialize the client (perhaps we could fall back to the earliest version or something for a deprecation period). This isn't a great user experience, however, it's the best way to get users to think about versioning. And no, this requires typing another argument every time! is not a valid argument against this; we already require a number of arguments, anyone sane doesn't type --ironic-api-url or --os-username every time they use the client. 5) Do what we're doing now. Bump the client's default version with every release. This mostly hides these versions from end users, and in general those users probably won't know they exist. And then we run into arguments every time we want to make a breaking change to the API. :) I think I like option 1 or 3 the best. I certainly don't like option 5 because we're going to break users every time we release a new client. What do other folks think we should do? // jim [0] https://github.com/openstack/ironic/commit/1410e59228c3835cfc4f89db1ec482137a3cfa10 [1] http://specs.openstack.org/openstack/nova-specs/specs/liberty/approved/novaclient-api-microversions.html __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 07/27/2015 04:35 PM, Jim Rollenhagen wrote: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. Actually what Nova is doing is slight different than this, the CLI will default to latest on the server. There will be an extra round trip to figure out what that is. And the CLI will (long term) just not present commands that aren't available at the server level you are talking to. Consider the CLI an auto negotiating microversion application of the python API client. And, realistically, should solve some of the issues of people running nova foo and getting cryptic errors from the server when they are hitting an old version of Nova that doesn't know how to foo. So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. -Sean -- Sean Dague http://dague.net __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. Faithful representation of the API is an interesting way to put it; it is a faithful representation either way. This way is a representation of the newest state of the API. It sounds like you're expecting a representation of the oldest state, or the state that you're used to (the hardest to predict). So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. I tend to think that folks using the CLI for automation should be pinning the version in that automation. A quick IRONIC_API_VERSION=1.8 or whatever would solve this problem. When new versions are available, read the notes for that version and adjust your code as necessary. Or just leave it at the same version until it breaks. :) // jim __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: On 07/27/2015 04:35 PM, Jim Rollenhagen wrote: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. Actually what Nova is doing is slight different than this, the CLI will default to latest on the server. There will be an extra round trip to figure out what that is. And the CLI will (long term) just not present commands that aren't available at the server level you are talking to. Consider the CLI an auto negotiating microversion application of the python API client. And, realistically, should solve some of the issues of people running nova foo and getting cryptic errors from the server when they are hitting an old version of Nova that doesn't know how to foo. So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
On 07/27/2015 07:10 PM, Jim Rollenhagen wrote: On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote: Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700: So the CLI should actually break less often, and will expose the most functionality you can get out of your cloud. What I find odd about this is that I want the CLI to be a faithful representation of the API, because many times the CLI is the only way I can access the API for integration purposes. Faithful representation of the API is an interesting way to put it; it is a faithful representation either way. This way is a representation of the newest state of the API. It sounds like you're expecting a representation of the oldest state, or the state that you're used to (the hardest to predict). So lets say I just want a very simple bash script to do something with nodes: id=$(ironic node-create ...|getid) while true ; do state=$(ironic node-get $id | get_state) case $state in AVAILABLE) break;; ERROR) # retry or something ;; *) splode(UNKNOWN STATE) ;; esac done Then the script is going to start exploding with a CLI that shows me ENROLL state. So I'm not sure having the CLI go faster than the python client is a great way to avoid breakage. It might be the opposite of that, and that might just be a large burden on users. I tend to think that folks using the CLI for automation should be pinning the version in that automation. A quick IRONIC_API_VERSION=1.8 or whatever would solve this problem. When new versions are available, read the notes for that version and adjust your code as necessary. Or just leave it at the same version until it breaks. :) Yeh, it's a cli, not a bash API. Having had to maintain devstack exercise code for a while, I'll tell you that the above is just a time bomb waiting to go off. None of the CLIs have that kind of contract, nor should they. Inflicting the bad UX of today on future generations because someone thinks, incorrectly, that it's a bash SDK is not a good trade off. If you want to pin things, explicitly, like jroll said, do that. And microversions lets you until your clouds uplift past your legacy code. -Sean -- Sean Dague http://dague.net signature.asc Description: OpenPGP digital signature __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ironic] Let's talk about API versions
Excerpts from Jim Rollenhagen's message of 2015-07-27 13:35:25 -0700: Hi friends. Ironic implemented API micro versions in Kilo. We originally did this to allow for breaking changes in the API while allowing users to opt in to the breakage. Since then, we've had a default version for our client that we bump to something sensible with each release. Currently it is at 1.8. Negotiation is done with the server to figure out what is supported and adjust accordingly. Now we've landed a patch[0] with a new version (1.11) that is not backward compatible. It causes newly added Node objects to begin life in the ENROLL state, rather than AVAILABLE. This is a good thing, and people should want this! However, it is a breaking change. Automation that adds nodes to Ironic will need to do different things after the node-create call. Our API versioning scheme makes this opt-in (by specifying the API version). However, some folks have a problem with releasing this change as-is. The logic is that we might release a client that defaults to 1.11 or higher, or the user may request 1.12 later to get a new feature, thus breaking their application that enrolls nodes. This is clearly backwards. Users should read release notes and be aware of what changes between versions in the API. Users need to be aware of the fact that our API is versioned, and use that to their advantage. It seems to me that the goal of the version negotiation in our client has been to pretend that our API versions don't exist, from a user perspective. We need to stop doing this and force users to think about what they are doing when they interact with our API. It seems to me we have a few options here: 1) Default the python client and CLI to the earliest supported version. This will never break users by default. 2) Default the python client and CLI to use the special version 'latest'. This will always use the latest API version, and always break people when a new server version (that is not backwards compatible) is deployed. 3) Do what Nova does[1]. Default CLI to latest and python client to earliest. This assumes that CLI is typically used for one-time commands (and it isn't a big deal if we break a one-off command once), and the python client is used for applications. 4) Require a version to use the client at all. This would be a one-time break with how applications initialize the client (perhaps we could fall back to the earliest version or something for a deprecation period). This isn't a great user experience, however, it's the best way to get users to think about versioning. And no, this requires typing another argument every time! is not a valid argument against this; we already require a number of arguments, anyone sane doesn't type --ironic-api-url or --os-username every time they use the client. 5) Do what we're doing now. Bump the client's default version with every release. This mostly hides these versions from end users, and in general those users probably won't know they exist. And then we run into arguments every time we want to make a breaking change to the API. :) Could you combine 1 and 4? Deprecate not specifying the version, but pin to the oldest one for now? That way users get the warnings that they need to adapt, but things keep working? Could be switched to just 4 after a few months. I say that having just added some IP addresses to a server with iproute2, which has been telling me for probably 10 years that _not_ adding /32 to single IP's will eventually be deprecated... __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
