Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/26/2015 11:10 AM, Dmitry Tantsur wrote: On 06/26/2015 04:57 PM, Joe Gordon wrote: To address this, nova has the following document: http://docs.openstack.org/developer/nova/api_microversion_history.html Btw 2.3 looks big, were it really one feature (and one commit, as we're talking about people deploying from master)? Yes, it was one feature and one commit. -jay __ 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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Fri, Jun 26, 2015 at 3:43 PM, Dmitry Tantsur divius.ins...@gmail.com wrote: 26 июня 2015 г. 2:47 пользователь GHANSHYAM MANN ghanshyamm...@gmail.com написал: On Sat, Jun 20, 2015 at 9:14 AM, Devananda van der Veen devananda@gmail.com wrote: Almost all of our discussions so far on this topic have left something out, which Monty pointed out to me last week. I'm following up now because E_TRAVEL... tldr; What we're versioning here are API's, not packages. It's not a question of numbering and dependency ordering, but of communicating support[ed|able] interfaces between running services. Libtool is more relevant than semver. http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html Right now we lack a means to express that the API response is compatible-with a particular previously-released version of the API. If we had that, instead of current-version, I believe we would have much happier users (and a happier Dmitry and jroll). Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) This is nice idea to return compatible-with information. But I feel each microversion either backward compatible or not should have their unique output only for what they had been introduced (not include new version changes). Sigh. Please provide some justification. I am considering the case of interoperatibility for Apps based on OpenStack cloud. where they are going to break when upgrade happens. Returning compatible-with information makes them encourage and well instance information about versions whether they are backward compatible or not. Even we have well written document for each version about what they are introduced for but still that information in new version can be useful. If older version shows what is in newer version(backward comp) then, there is no meaning of introducing those compatible changes as microversion. And if so then it blank out whole idea of publishing changes/features through microversion even they are backward compatible. The main reason for versioning is feature discovery. It had nothing to do with feature hiding. Please read the whole thread to see why feature hiding is actually harmful. I can understand your concern here and somehow i agree on the problems you mentioned in initial thread. But we have to trade-off between developers pain vs breaking Apps ion upgrade. i also agree feature hiding can be very painful in some cases as you mentioned ironic node state, and their testing more, but allow new feature automatically in older version on upgrade does break the App as mentioned ijn early mail and Sean blog. IMO, OpenSatck users/App/its usability takes priority than developers/testing pain till we have better solution to
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Fri, Jun 26, 2015 at 3:46 PM, Dmitry Tantsur divius.ins...@gmail.com wrote: 26 июня 2015 г. 2:48 пользователь GHANSHYAM MANN ghanshyamm...@gmail.com написал: On Thu, Jun 25, 2015 at 5:18 PM, Ken'ichi Ohmichi ken1ohmi...@gmail.com wrote: Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. After that, he needed to switch to the other cloud because of cost merit or something. The specified microversion was v1.1, so he did think his application can work fine on cloud B also because of cloud B's max microversion. But yes, his application could not work because his application had already used newer features which are implemented on v1.2+. In the real world, there are a lot of clouds and it is easy to imagine this situation. By the way, feature hiding did not change the situation: the application using new features won't work on older cloud, period. But application can control the new feature usage with version (with current design of hiding new features in older versions). With that its going to work on both new or older cloud. If older cloud is not upgraded, app knows their max supported version, and can behave/control new feature usage in their app. This is really nice point. We should give power to users to decide whether they need/want to use/get the new features introduced in new microversion irrespective of it is backward compatible or not. I'm already tried of asking why, but I'll try
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
26 июня 2015 г. 2:47 пользователь GHANSHYAM MANN ghanshyamm...@gmail.com написал: On Sat, Jun 20, 2015 at 9:14 AM, Devananda van der Veen devananda@gmail.com wrote: Almost all of our discussions so far on this topic have left something out, which Monty pointed out to me last week. I'm following up now because E_TRAVEL... tldr; What we're versioning here are API's, not packages. It's not a question of numbering and dependency ordering, but of communicating support[ed|able] interfaces between running services. Libtool is more relevant than semver. http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html Right now we lack a means to express that the API response is compatible-with a particular previously-released version of the API. If we had that, instead of current-version, I believe we would have much happier users (and a happier Dmitry and jroll). Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) This is nice idea to return compatible-with information. But I feel each microversion either backward compatible or not should have their unique output only for what they had been introduced (not include new version changes). Sigh. Please provide some justification. If older version shows what is in newer version(backward comp) then, there is no meaning of introducing those compatible changes as microversion. And if so then it blank out whole idea of publishing changes/features through microversion even they are backward compatible. The main reason for versioning is feature discovery. It had nothing to do with feature hiding. Please read the whole thread to see why feature hiding is actually harmful. How about combining those means older version do not include anything from newer version but it returns compatible-with: information also which can be useful for user to bump version easily. Yes -- (b) and (c) are identical responses. Discuss. -Devananda On Tue, Jun 16, 2015 at 7:13 AM Dmitry Tantsur dtant...@redhat.com wrote: On 06/16/2015 03:47 PM, Jim Rollenhagen wrote: On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
26 июня 2015 г. 2:48 пользователь GHANSHYAM MANN ghanshyamm...@gmail.com написал: On Thu, Jun 25, 2015 at 5:18 PM, Ken'ichi Ohmichi ken1ohmi...@gmail.com wrote: Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. After that, he needed to switch to the other cloud because of cost merit or something. The specified microversion was v1.1, so he did think his application can work fine on cloud B also because of cloud B's max microversion. But yes, his application could not work because his application had already used newer features which are implemented on v1.2+. In the real world, there are a lot of clouds and it is easy to imagine this situation. By the way, feature hiding did not change the situation: the application using new features won't work on older cloud, period. This is really nice point. We should give power to users to decide whether they need/want to use/get the new features introduced in new microversion irrespective of it is backward compatible or not. I'm already tried of asking why, but I'll try again: why? Did you even read this thread? It's not power, it's limitation, and a pretty nasty one. Current microversion implementation of Nova is blocking this situation by making backwards every compatible change appear on each microversion. Nova team needs to consider interoperability between clouds so well because Nova API is one of general external interfaces for end users. On the other hand, Ironic API is
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Fri, Jun 26, 2015 at 7:39 AM, Dmitry Tantsur dtant...@redhat.com wrote: On 06/26/2015 04:08 PM, Sean Dague wrote: On 06/26/2015 07:43 AM, Dmitry Tantsur wrote: On 06/26/2015 01:14 PM, Sean Dague wrote: On 06/16/2015 09:51 AM, Dmitry Tantsur wrote: On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: To sum this long post up, I'm seeing that hiding new features based on microversions brings much more problems, than it solves (I'm not aware of the latter at all). I'm very opposed to continuing doing it in Ironic, and I'm going to propose patch stopping gating Kilo changes (non-breaking obviously). I'm talking about this patch: https://review.openstack.org/#/c/192196/ We have to do it right now, as otherwise we can't test inspection in tempest (it does not seem to be microversion-aware). Dmitry, How do you solve for the following situation? 2 Clouds (A and B), both being Continuously Deployed. Assume both clouds start at same revision of code. At point in time T a new compatable change is added to the API. For instance, another field returned by some resource. Cloud B upgrades to that change. Brand new developer shows up. Starts writing application against Cloud B. Sees that change is available at version 1.4. Hard codes her application to use this parameter. Then she points her application at Cloud A. And it explodes. I clearly agree that my solutions do not solve this situation. Neither does yours. Now let us see: A compatible change is getting added and is guarded behind version 1.5. A new developer starts requiring this new version, because she needs this new feature (that's your assumption). Then she points her application at cloud A. And it explodes. But with different error message and probably a bit earlier. But explodes. Which, by the way, means we still must know precisely which API version is served by all clouds we might apply our utility to. But it fails with Your application is attempting to use API 1.5 which is not supported in this cloud. Because if you don't specify a version, you get the base 1.0, and never had new features. That's an error which is extremely clear to understand what went wrong. Has docs to figure out if the application could work at an earlier release version, and provides the ability for the client to do some selection logic based on supported versions. I agree that error is clear. I'm not sure it's worth doing despite all the problems that I mentioned in the beginning of this thread. In particular, situation around official CLI and testing. E.g. do you agree with Jim that we should make API version a required argument for both CLI and Python library? -Sean So I agree, hitting API version error could make a person realize that a change to the utility is no longer compatible with the current version of API. So if this change wasn't intended - fine. If it was (which is the most likely situation), it won't help you. By the way, I've heard some people wanting to deprecate API version with time. If we do so, it will open some new horizons for breakages. If we don't, we'll soon end put with dozens of version to support and test. How to solve it? (in Ironic IIRC we just only gate test one version, namely Kilo aka 1.6, which is very, very bad IMO). I feel like in your concerns there has been an assumption that the operation across all clouds effectively always goes forwards. But because we're trying to encourage and create a multicloud ecosystem a user application might experience the world the following way. Cloud A - Cloud A' - Cloud A'' - Cloud D - Cloud B' - Cloud C - Cloud C'. I think that versioning actually encourages this (wrong) assumption. Because versions grow with time naturally, and we, the developers, like new and shiny stuff so much :) see below for my alternative idea. While no individual cloud is likely to downgrade code (though we can't fully rule that out), the fact that we'd like applications to work against a wide range of deployments means effectively applications are going to experience the world as if the code bases both upgrade and downgrade over time. Which means that a change is only compatable if the inverse of the change is also compatable. So a field add is only compatable if the field delete is also considered compatible, because people are going to experience that when they hop to another cloud. Which is also why feature hiding is a thing. Because we don't control when every cloud is going to upgrade, and what they'll upgrade to. So the best idea so far about getting this right is that API 1.4 is *exactly* a specific surface. Features added in 1.5 are not visibile if you ask for 1.4. Because if they were, and you now wrote applications that used that bleed through, when you jump to a cloud without 1.5 yet deployed, all your application code breaks. Note that if you rely on version 1.4 with feature hiding, your
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/26/2015 01:14 PM, Sean Dague wrote: On 06/16/2015 09:51 AM, Dmitry Tantsur wrote: On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: To sum this long post up, I'm seeing that hiding new features based on microversions brings much more problems, than it solves (I'm not aware of the latter at all). I'm very opposed to continuing doing it in Ironic, and I'm going to propose patch stopping gating Kilo changes (non-breaking obviously). I'm talking about this patch: https://review.openstack.org/#/c/192196/ We have to do it right now, as otherwise we can't test inspection in tempest (it does not seem to be microversion-aware). Dmitry, How do you solve for the following situation? 2 Clouds (A and B), both being Continuously Deployed. Assume both clouds start at same revision of code. At point in time T a new compatable change is added to the API. For instance, another field returned by some resource. Cloud B upgrades to that change. Brand new developer shows up. Starts writing application against Cloud B. Sees that change is available at version 1.4. Hard codes her application to use this parameter. Then she points her application at Cloud A. And it explodes. I clearly agree that my solutions do not solve this situation. Neither does yours. Now let us see: A compatible change is getting added and is guarded behind version 1.5. A new developer starts requiring this new version, because she needs this new feature (that's your assumption). Then she points her application at cloud A. And it explodes. But with different error message and probably a bit earlier. But explodes. Which, by the way, means we still must know precisely which API version is served by all clouds we might apply our utility to. So I agree, hitting API version error could make a person realize that a change to the utility is no longer compatible with the current version of API. So if this change wasn't intended - fine. If it was (which is the most likely situation), it won't help you. By the way, I've heard some people wanting to deprecate API version with time. If we do so, it will open some new horizons for breakages. If we don't, we'll soon end put with dozens of version to support and test. How to solve it? (in Ironic IIRC we just only gate test one version, namely Kilo aka 1.6, which is very, very bad IMO). I feel like in your concerns there has been an assumption that the operation across all clouds effectively always goes forwards. But because we're trying to encourage and create a multicloud ecosystem a user application might experience the world the following way. Cloud A - Cloud A' - Cloud A'' - Cloud D - Cloud B' - Cloud C - Cloud C'. I think that versioning actually encourages this (wrong) assumption. Because versions grow with time naturally, and we, the developers, like new and shiny stuff so much :) see below for my alternative idea. While no individual cloud is likely to downgrade code (though we can't fully rule that out), the fact that we'd like applications to work against a wide range of deployments means effectively applications are going to experience the world as if the code bases both upgrade and downgrade over time. Which means that a change is only compatable if the inverse of the change is also compatable. So a field add is only compatable if the field delete is also considered compatible, because people are going to experience that when they hop to another cloud. Which is also why feature hiding is a thing. Because we don't control when every cloud is going to upgrade, and what they'll upgrade to. So the best idea so far about getting this right is that API 1.4 is *exactly* a specific surface. Features added in 1.5 are not visibile if you ask for 1.4. Because if they were, and you now wrote applications that used that bleed through, when you jump to a cloud without 1.5 yet deployed, all your application code breaks. Note that if you rely on version 1.4 with feature hiding, your application will also break. I.e. I agree it's a valid situation to fix, I just don't see feature hiding fixing *all* cases of this problem. While an API exposing feature explicitly might be more handy, imagine e.g. $ curl http://ironic.host/v1/features ['inspection', 'raid', ...] Exposing interface like that would encourage people to think about their application in terms of mandatory and optional features, not some numbers. If we were only working on a single install of OpenStack in the world, like EC2, github, meetup, or any other proprietary API service out there, it would be a different story. We'd control time's arrow, and never would have to worry about going back in time. But we're not working on that. We're working on software we hope will bloom 10,000+ clouds. At all scales. And the challenge to provide a consistent programming experience for application writers that want to work against any of those clouds means we needed to come up with some new models here. If you
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/26/2015 04:08 PM, Sean Dague wrote: On 06/26/2015 07:43 AM, Dmitry Tantsur wrote: On 06/26/2015 01:14 PM, Sean Dague wrote: On 06/16/2015 09:51 AM, Dmitry Tantsur wrote: On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: To sum this long post up, I'm seeing that hiding new features based on microversions brings much more problems, than it solves (I'm not aware of the latter at all). I'm very opposed to continuing doing it in Ironic, and I'm going to propose patch stopping gating Kilo changes (non-breaking obviously). I'm talking about this patch: https://review.openstack.org/#/c/192196/ We have to do it right now, as otherwise we can't test inspection in tempest (it does not seem to be microversion-aware). Dmitry, How do you solve for the following situation? 2 Clouds (A and B), both being Continuously Deployed. Assume both clouds start at same revision of code. At point in time T a new compatable change is added to the API. For instance, another field returned by some resource. Cloud B upgrades to that change. Brand new developer shows up. Starts writing application against Cloud B. Sees that change is available at version 1.4. Hard codes her application to use this parameter. Then she points her application at Cloud A. And it explodes. I clearly agree that my solutions do not solve this situation. Neither does yours. Now let us see: A compatible change is getting added and is guarded behind version 1.5. A new developer starts requiring this new version, because she needs this new feature (that's your assumption). Then she points her application at cloud A. And it explodes. But with different error message and probably a bit earlier. But explodes. Which, by the way, means we still must know precisely which API version is served by all clouds we might apply our utility to. But it fails with Your application is attempting to use API 1.5 which is not supported in this cloud. Because if you don't specify a version, you get the base 1.0, and never had new features. That's an error which is extremely clear to understand what went wrong. Has docs to figure out if the application could work at an earlier release version, and provides the ability for the client to do some selection logic based on supported versions. I agree that error is clear. I'm not sure it's worth doing despite all the problems that I mentioned in the beginning of this thread. In particular, situation around official CLI and testing. E.g. do you agree with Jim that we should make API version a required argument for both CLI and Python library? -Sean So I agree, hitting API version error could make a person realize that a change to the utility is no longer compatible with the current version of API. So if this change wasn't intended - fine. If it was (which is the most likely situation), it won't help you. By the way, I've heard some people wanting to deprecate API version with time. If we do so, it will open some new horizons for breakages. If we don't, we'll soon end put with dozens of version to support and test. How to solve it? (in Ironic IIRC we just only gate test one version, namely Kilo aka 1.6, which is very, very bad IMO). I feel like in your concerns there has been an assumption that the operation across all clouds effectively always goes forwards. But because we're trying to encourage and create a multicloud ecosystem a user application might experience the world the following way. Cloud A - Cloud A' - Cloud A'' - Cloud D - Cloud B' - Cloud C - Cloud C'. I think that versioning actually encourages this (wrong) assumption. Because versions grow with time naturally, and we, the developers, like new and shiny stuff so much :) see below for my alternative idea. While no individual cloud is likely to downgrade code (though we can't fully rule that out), the fact that we'd like applications to work against a wide range of deployments means effectively applications are going to experience the world as if the code bases both upgrade and downgrade over time. Which means that a change is only compatable if the inverse of the change is also compatable. So a field add is only compatable if the field delete is also considered compatible, because people are going to experience that when they hop to another cloud. Which is also why feature hiding is a thing. Because we don't control when every cloud is going to upgrade, and what they'll upgrade to. So the best idea so far about getting this right is that API 1.4 is *exactly* a specific surface. Features added in 1.5 are not visibile if you ask for 1.4. Because if they were, and you now wrote applications that used that bleed through, when you jump to a cloud without 1.5 yet deployed, all your application code breaks. Note that if you rely on version 1.4 with feature hiding, your application will also break. I.e. I agree it's a valid situation to fix, I just don't see feature hiding fixing *all* cases of this problem. While an API
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/26/2015 07:43 AM, Dmitry Tantsur wrote: On 06/26/2015 01:14 PM, Sean Dague wrote: On 06/16/2015 09:51 AM, Dmitry Tantsur wrote: On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: To sum this long post up, I'm seeing that hiding new features based on microversions brings much more problems, than it solves (I'm not aware of the latter at all). I'm very opposed to continuing doing it in Ironic, and I'm going to propose patch stopping gating Kilo changes (non-breaking obviously). I'm talking about this patch: https://review.openstack.org/#/c/192196/ We have to do it right now, as otherwise we can't test inspection in tempest (it does not seem to be microversion-aware). Dmitry, How do you solve for the following situation? 2 Clouds (A and B), both being Continuously Deployed. Assume both clouds start at same revision of code. At point in time T a new compatable change is added to the API. For instance, another field returned by some resource. Cloud B upgrades to that change. Brand new developer shows up. Starts writing application against Cloud B. Sees that change is available at version 1.4. Hard codes her application to use this parameter. Then she points her application at Cloud A. And it explodes. I clearly agree that my solutions do not solve this situation. Neither does yours. Now let us see: A compatible change is getting added and is guarded behind version 1.5. A new developer starts requiring this new version, because she needs this new feature (that's your assumption). Then she points her application at cloud A. And it explodes. But with different error message and probably a bit earlier. But explodes. Which, by the way, means we still must know precisely which API version is served by all clouds we might apply our utility to. But it fails with Your application is attempting to use API 1.5 which is not supported in this cloud. Because if you don't specify a version, you get the base 1.0, and never had new features. That's an error which is extremely clear to understand what went wrong. Has docs to figure out if the application could work at an earlier release version, and provides the ability for the client to do some selection logic based on supported versions. -Sean So I agree, hitting API version error could make a person realize that a change to the utility is no longer compatible with the current version of API. So if this change wasn't intended - fine. If it was (which is the most likely situation), it won't help you. By the way, I've heard some people wanting to deprecate API version with time. If we do so, it will open some new horizons for breakages. If we don't, we'll soon end put with dozens of version to support and test. How to solve it? (in Ironic IIRC we just only gate test one version, namely Kilo aka 1.6, which is very, very bad IMO). I feel like in your concerns there has been an assumption that the operation across all clouds effectively always goes forwards. But because we're trying to encourage and create a multicloud ecosystem a user application might experience the world the following way. Cloud A - Cloud A' - Cloud A'' - Cloud D - Cloud B' - Cloud C - Cloud C'. I think that versioning actually encourages this (wrong) assumption. Because versions grow with time naturally, and we, the developers, like new and shiny stuff so much :) see below for my alternative idea. While no individual cloud is likely to downgrade code (though we can't fully rule that out), the fact that we'd like applications to work against a wide range of deployments means effectively applications are going to experience the world as if the code bases both upgrade and downgrade over time. Which means that a change is only compatable if the inverse of the change is also compatable. So a field add is only compatable if the field delete is also considered compatible, because people are going to experience that when they hop to another cloud. Which is also why feature hiding is a thing. Because we don't control when every cloud is going to upgrade, and what they'll upgrade to. So the best idea so far about getting this right is that API 1.4 is *exactly* a specific surface. Features added in 1.5 are not visibile if you ask for 1.4. Because if they were, and you now wrote applications that used that bleed through, when you jump to a cloud without 1.5 yet deployed, all your application code breaks. Note that if you rely on version 1.4 with feature hiding, your application will also break. I.e. I agree it's a valid situation to fix, I just don't see feature hiding fixing *all* cases of this problem. While an API exposing feature explicitly might be more handy, imagine e.g. $ curl http://ironic.host/v1/features ['inspection', 'raid', ...] Exposing interface like that would encourage people to think about their application in terms of mandatory and optional features, not some numbers. Yes,
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/26/2015 04:57 PM, Joe Gordon wrote: On Fri, Jun 26, 2015 at 7:39 AM, Dmitry Tantsur dtant...@redhat.com mailto:dtant...@redhat.com wrote: On 06/26/2015 04:08 PM, Sean Dague wrote: On 06/26/2015 07:43 AM, Dmitry Tantsur wrote: On 06/26/2015 01:14 PM, Sean Dague wrote: On 06/16/2015 09:51 AM, Dmitry Tantsur wrote: On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: To sum this long post up, I'm seeing that hiding new features based on microversions brings much more problems, than it solves (I'm not aware of the latter at all). I'm very opposed to continuing doing it in Ironic, and I'm going to propose patch stopping gating Kilo changes (non-breaking obviously). I'm talking about this patch: https://review.openstack.org/#/c/192196/ We have to do it right now, as otherwise we can't test inspection in tempest (it does not seem to be microversion-aware). Dmitry, How do you solve for the following situation? 2 Clouds (A and B), both being Continuously Deployed. Assume both clouds start at same revision of code. At point in time T a new compatable change is added to the API. For instance, another field returned by some resource. Cloud B upgrades to that change. Brand new developer shows up. Starts writing application against Cloud B. Sees that change is available at version 1.4. Hard codes her application to use this parameter. Then she points her application at Cloud A. And it explodes. I clearly agree that my solutions do not solve this situation. Neither does yours. Now let us see: A compatible change is getting added and is guarded behind version 1.5. A new developer starts requiring this new version, because she needs this new feature (that's your assumption). Then she points her application at cloud A. And it explodes. But with different error message and probably a bit earlier. But explodes. Which, by the way, means we still must know precisely which API version is served by all clouds we might apply our utility to. But it fails with Your application is attempting to use API 1.5 which is not supported in this cloud. Because if you don't specify a version, you get the base 1.0, and never had new features. That's an error which is extremely clear to understand what went wrong. Has docs to figure out if the application could work at an earlier release version, and provides the ability for the client to do some selection logic based on supported versions. I agree that error is clear. I'm not sure it's worth doing despite all the problems that I mentioned in the beginning of this thread. In particular, situation around official CLI and testing. E.g. do you agree with Jim that we should make API version a required argument for both CLI and Python library? -Sean So I agree, hitting API version error could make a person realize that a change to the utility is no longer compatible with the current version of API. So if this change wasn't intended - fine. If it was (which is the most likely situation), it won't help you. By the way, I've heard some people wanting to deprecate API version with time. If we do so, it will open some new horizons for breakages. If we don't, we'll soon end put with dozens of version to support and test. How to solve it? (in Ironic IIRC we just only gate test one version, namely Kilo aka 1.6, which is very, very bad IMO). I feel like in your concerns there has been an assumption that the operation across all clouds effectively always goes forwards. But because we're trying to encourage and create a multicloud ecosystem a user application might experience the world the following way. Cloud A - Cloud A' - Cloud A'' - Cloud D - Cloud B' - Cloud C - Cloud C'. I think that versioning actually
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/26/2015 04:58 PM, Devananda van der Veen wrote: Dmitry, Feature strings won't work. It only makes things more complex, without addressing the underlying issue. What happens when we change, even in a small way, the API surface exposed by an existing feature? How is that change exposed -- unless we include a version number along with your feature string? And now we're right back where we started. Ok, maybe this idea is just as broken. Still, the current proposal brings more problems than it solves. -Deva On Fri, Jun 26, 2015, 07:41 Dmitry Tantsur dtant...@redhat.com mailto:dtant...@redhat.com wrote: On 06/26/2015 04:08 PM, Sean Dague wrote: On 06/26/2015 07:43 AM, Dmitry Tantsur wrote: On 06/26/2015 01:14 PM, Sean Dague wrote: On 06/16/2015 09:51 AM, Dmitry Tantsur wrote: On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: To sum this long post up, I'm seeing that hiding new features based on microversions brings much more problems, than it solves (I'm not aware of the latter at all). I'm very opposed to continuing doing it in Ironic, and I'm going to propose patch stopping gating Kilo changes (non-breaking obviously). I'm talking about this patch: https://review.openstack.org/#/c/192196/ We have to do it right now, as otherwise we can't test inspection in tempest (it does not seem to be microversion-aware). Dmitry, How do you solve for the following situation? 2 Clouds (A and B), both being Continuously Deployed. Assume both clouds start at same revision of code. At point in time T a new compatable change is added to the API. For instance, another field returned by some resource. Cloud B upgrades to that change. Brand new developer shows up. Starts writing application against Cloud B. Sees that change is available at version 1.4. Hard codes her application to use this parameter. Then she points her application at Cloud A. And it explodes. I clearly agree that my solutions do not solve this situation. Neither does yours. Now let us see: A compatible change is getting added and is guarded behind version 1.5. A new developer starts requiring this new version, because she needs this new feature (that's your assumption). Then she points her application at cloud A. And it explodes. But with different error message and probably a bit earlier. But explodes. Which, by the way, means we still must know precisely which API version is served by all clouds we might apply our utility to. But it fails with Your application is attempting to use API 1.5 which is not supported in this cloud. Because if you don't specify a version, you get the base 1.0, and never had new features. That's an error which is extremely clear to understand what went wrong. Has docs to figure out if the application could work at an earlier release version, and provides the ability for the client to do some selection logic based on supported versions. I agree that error is clear. I'm not sure it's worth doing despite all the problems that I mentioned in the beginning of this thread. In particular, situation around official CLI and testing. E.g. do you agree with Jim that we should make API version a required argument for both CLI and Python library? -Sean So I agree, hitting API version error could make a person realize that a change to the utility is no longer compatible with the current version of API. So if this change wasn't intended - fine. If it was (which is the most likely situation), it won't help you. By the way, I've heard some people wanting to deprecate API version with time. If we do so, it will open some new horizons for breakages. If we don't, we'll soon end put with dozens of version to support and test. How to solve it? (in Ironic IIRC we just only gate test one version, namely Kilo aka 1.6, which is very, very bad IMO). I feel like in your concerns there has been an assumption that the operation across all clouds effectively always goes forwards. But because we're trying to encourage and create a multicloud ecosystem a user application might experience the world the following way. Cloud A - Cloud A' - Cloud A'' - Cloud D - Cloud B' - Cloud C - Cloud C'. I think that versioning actually encourages this (wrong) assumption. Because versions grow with time naturally, and we, the developers, like new and shiny stuff so much :) see below for my alternative idea. While no individual cloud is likely to
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/16/2015 09:51 AM, Dmitry Tantsur wrote: On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: To sum this long post up, I'm seeing that hiding new features based on microversions brings much more problems, than it solves (I'm not aware of the latter at all). I'm very opposed to continuing doing it in Ironic, and I'm going to propose patch stopping gating Kilo changes (non-breaking obviously). I'm talking about this patch: https://review.openstack.org/#/c/192196/ We have to do it right now, as otherwise we can't test inspection in tempest (it does not seem to be microversion-aware). Dmitry, How do you solve for the following situation? 2 Clouds (A and B), both being Continuously Deployed. Assume both clouds start at same revision of code. At point in time T a new compatable change is added to the API. For instance, another field returned by some resource. Cloud B upgrades to that change. Brand new developer shows up. Starts writing application against Cloud B. Sees that change is available at version 1.4. Hard codes her application to use this parameter. Then she points her application at Cloud A. And it explodes. I feel like in your concerns there has been an assumption that the operation across all clouds effectively always goes forwards. But because we're trying to encourage and create a multicloud ecosystem a user application might experience the world the following way. Cloud A - Cloud A' - Cloud A'' - Cloud D - Cloud B' - Cloud C - Cloud C'. While no individual cloud is likely to downgrade code (though we can't fully rule that out), the fact that we'd like applications to work against a wide range of deployments means effectively applications are going to experience the world as if the code bases both upgrade and downgrade over time. Which means that a change is only compatable if the inverse of the change is also compatable. So a field add is only compatable if the field delete is also considered compatible, because people are going to experience that when they hop to another cloud. Which is also why feature hiding is a thing. Because we don't control when every cloud is going to upgrade, and what they'll upgrade to. So the best idea so far about getting this right is that API 1.4 is *exactly* a specific surface. Features added in 1.5 are not visibile if you ask for 1.4. Because if they were, and you now wrote applications that used that bleed through, when you jump to a cloud without 1.5 yet deployed, all your application code breaks. If we were only working on a single install of OpenStack in the world, like EC2, github, meetup, or any other proprietary API service out there, it would be a different story. We'd control time's arrow, and never would have to worry about going back in time. But we're not working on that. We're working on software we hope will bloom 10,000+ clouds. At all scales. And the challenge to provide a consistent programming experience for application writers that want to work against any of those clouds means we needed to come up with some new models here. If you have other solutions to the time's arrow issue, that would be great to here. But it is the crux of why the model looks like it does. -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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Sat, Jun 20, 2015 at 9:14 AM, Devananda van der Veen devananda@gmail.com wrote: Almost all of our discussions so far on this topic have left something out, which Monty pointed out to me last week. I'm following up now because E_TRAVEL... tldr; What we're versioning here are API's, not packages. It's not a question of numbering and dependency ordering, but of communicating support[ed|able] interfaces between running services. Libtool is more relevant than semver. http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html Right now we lack a means to express that the API response is compatible-with a particular previously-released version of the API. If we had that, instead of current-version, I believe we would have much happier users (and a happier Dmitry and jroll). Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) This is nice idea to return compatible-with information. But I feel each microversion either backward compatible or not should have their unique output only for what they had been introduced (not include new version changes). If older version shows what is in newer version(backward comp) then, there is no meaning of introducing those compatible changes as microversion. And if so then it blank out whole idea of publishing changes/features through microversion even they are backward compatible. How about combining those means older version do not include anything from newer version but it returns compatible-with: information also which can be useful for user to bump version easily. Yes -- (b) and (c) are identical responses. Discuss. -Devananda On Tue, Jun 16, 2015 at 7:13 AM Dmitry Tantsur dtant...@redhat.com wrote: On 06/16/2015 03:47 PM, Jim Rollenhagen wrote: On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Thu, Jun 25, 2015 at 5:18 PM, Ken'ichi Ohmichi ken1ohmi...@gmail.com wrote: Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. After that, he needed to switch to the other cloud because of cost merit or something. The specified microversion was v1.1, so he did think his application can work fine on cloud B also because of cloud B's max microversion. But yes, his application could not work because his application had already used newer features which are implemented on v1.2+. In the real world, there are a lot of clouds and it is easy to imagine this situation. This is really nice point. We should give power to users to decide whether they need/want to use/get the new features introduced in new microversion irrespective of it is backward compatible or not. Current microversion implementation of Nova is blocking this situation by making backwards every compatible change appear on each microversion. Nova team needs to consider interoperability between clouds so well because Nova API is one of general external interfaces for end users. On the other hand, Ironic API is for administrators, not for end users. I am imaging that: * Some administrator wrote his application for using Ironic API. * From the viewpoint of administrator, the switching destination cloud in newer in most cases. * The application can continue working on newer clouds even after switching many times. So I feel the above interoperable issue example would not happen on Ironic in most cases unless hiding backwards compatible changes on lower
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. After that, he needed to switch to the other cloud because of cost merit or something. The specified microversion was v1.1, so he did think his application can work fine on cloud B also because of cloud B's max microversion. But yes, his application could not work because his application had already used newer features which are implemented on v1.2+. In the real world, there are a lot of clouds and it is easy to imagine this situation. Current microversion implementation of Nova is blocking this situation by making backwards every compatible change appear on each microversion. Nova team needs to consider interoperability between clouds so well because Nova API is one of general external interfaces for end users. On the other hand, Ironic API is for administrators, not for end users. I am imaging that: * Some administrator wrote his application for using Ironic API. * From the viewpoint of administrator, the switching destination cloud in newer in most cases. * The application can continue working on newer clouds even after switching many times. So I feel the above interoperable issue example would not happen on Ironic in most cases unless hiding backwards compatible changes on lower microversion. I guess this is the difference between Nova and Ironic on interoperability discussion. I cannot/don't want to enforce Ironic way at all, and it's fine to find the best way on each project as OSS projects. But only my concern here is that we cannot use Microversions as a perfect keyword for OpenStack
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/25/2015 10:18 AM, Ken'ichi Ohmichi wrote: Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. It's a valid concern, but it does not justify such a insanely complex measure with so many downsides. We can't and shouldn't prevent people from trying to work around the API contract. It's like people who will claim version 1.3 while they actually are not compatible with it: they are asking for breakage. And with hiding new features you WILL get this situation. On the other hand, I've put up a lot of concerns with Nova's implementation, that people didn't even try to address. I'm not going to consider this one overweighting. After that, he needed to switch to the other cloud because of cost merit or something. The specified microversion was v1.1, so he did think his application can work fine on cloud B also because of cloud B's max microversion. But yes, his application could not work because his application had already used newer features which are implemented on v1.2+. In the real world, there are a lot of clouds and it is easy to imagine this situation. Current microversion implementation of Nova is blocking this situation by making backwards every compatible change appear on each microversion. Nova team needs to consider interoperability between clouds so well because Nova API is one of general external interfaces for end users. On the other hand, Ironic API is for administrators, not for end users. I am imaging that: * Some administrator wrote his application for using Ironic API. * From the viewpoint of administrator, the switching destination cloud in newer in most cases.
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/25/2015 11:11 AM, Ken'ichi Ohmichi wrote: 2015-06-25 17:31 GMT+09:00 Dmitry Tantsur dtant...@redhat.com: On 06/25/2015 10:18 AM, Ken'ichi Ohmichi wrote: Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. It's a valid concern, but it does not justify such a insanely complex measure with so many downsides. We can't and shouldn't prevent people from trying to work around the API contract. It's like people who will claim version 1.3 while they actually are not compatible with it: they are asking for breakage. And with hiding new features you WILL get this situation. Sorry, to be honest, I cannot understand your comment here. Are you saying the above interoperable issue is not matter by comparing downsides requirements? If so, is that just for Ironic? or for whole OpenStack projects including Nova? What is the reason for justifying your requirement? Just many people are saying so around you without considering this interoperable issue? I'm only saying that these (theoretical) issue is smaller than issues that your approach introduces. Please see all my upper posts for details. Thanks Ken Ohmichi. --- On the other hand, I've put up a lot of concerns with Nova's implementation, that people didn't even try to address. I'm not going to consider this one overweighting. After that, he needed to switch to the other cloud because of cost merit or something. The specified microversion was v1.1, so he did think his application can work fine on cloud B also because of cloud B's max microversion. But yes, his application could not work because his application had already used newer
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
2015-06-25 18:16 GMT+09:00 Dmitry Tantsur dtant...@redhat.com: On 06/25/2015 11:11 AM, Ken'ichi Ohmichi wrote: 2015-06-25 17:31 GMT+09:00 Dmitry Tantsur dtant...@redhat.com: On 06/25/2015 10:18 AM, Ken'ichi Ohmichi wrote: Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. It's a valid concern, but it does not justify such a insanely complex measure with so many downsides. We can't and shouldn't prevent people from trying to work around the API contract. It's like people who will claim version 1.3 while they actually are not compatible with it: they are asking for breakage. And with hiding new features you WILL get this situation. Sorry, to be honest, I cannot understand your comment here. Are you saying the above interoperable issue is not matter by comparing downsides requirements? If so, is that just for Ironic? or for whole OpenStack projects including Nova? What is the reason for justifying your requirement? Just many people are saying so around you without considering this interoperable issue? I'm only saying that these (theoretical) issue is smaller than issues that your approach introduces. Please see all my upper posts for details. I just want to know your point is just for Ironic or whole projects. I tried explaining the difference between Nova and Ironic expectation related to microversions and your comment seems not considering this difference at all. and your posts were too many already, so I'm not sure the mail.. Thanks Ken Ohmichi --- On the other hand, I've put up
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
2015-06-25 17:31 GMT+09:00 Dmitry Tantsur dtant...@redhat.com: On 06/25/2015 10:18 AM, Ken'ichi Ohmichi wrote: Sorry for late response here, 2015-06-20 9:14 GMT+09:00 Devananda van der Veen devananda@gmail.com: Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. I think it is good that backwards compatible changes(new features) are available on older microversion also *only* if the clouds which are used by users continue upgrading. I think Sophia's role on The Backwards Compatibility Fallacy of Sean's blog[1] has answered to this question, but I'd like to try explaining it here for considering Ironic situation. As the example, there are multiple public clouds which provide different max microversions like: Cloud A: Max microversion: v1.5 Cloud B: Max microversion: v1.1 A user wrote his own application for running on cloud A and specifying v1.1 on the first application implementation. The first application used small number of APIs, and he wanted to extend the application. If all backwards compatible changes(v1.2 - v1.5) appear on lower microversion(in this case v1.1), he can use all new features even if specifying v1.1. That seemed really great for users at this time, and he extended the application for using all features as possible. but the specified microversion still is v1.1 because his application worked fine even if using newer features. It's a valid concern, but it does not justify such a insanely complex measure with so many downsides. We can't and shouldn't prevent people from trying to work around the API contract. It's like people who will claim version 1.3 while they actually are not compatible with it: they are asking for breakage. And with hiding new features you WILL get this situation. Sorry, to be honest, I cannot understand your comment here. Are you saying the above interoperable issue is not matter by comparing downsides requirements? If so, is that just for Ironic? or for whole OpenStack projects including Nova? What is the reason for justifying your requirement? Just many people are saying so around you without considering this interoperable issue? Thanks Ken Ohmichi. --- On the other hand, I've put up a lot of concerns with Nova's implementation, that people didn't even try to address. I'm not going to consider this one overweighting. After that, he needed to switch to the other cloud because of cost merit or something. The specified microversion was v1.1, so he did think his application can work fine on cloud B also because of cloud B's max microversion. But yes, his application could not work because his application had already used newer features which are implemented on v1.2+. In the real world, there are a lot of clouds and it is easy to imagine this
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/22/2015 05:28 AM, John Garbutt wrote: On 22 June 2015 at 00:14, Michael Still mi...@stillhq.com wrote: As an aside, do we think that exposing the exact version of a server process is safe from a security perspective? During discussions in the Nova API meeting, it was noted that while we do expose the exact API version, we are not exposing the git hash of the deployed cloud. Its certainly something we need to consider when we talk about bumping the micro-version for a security fix, but I suspect the need to backport is likely to force us to not bump the API version for such changes. Its certainly a concern that should be noted, in the hope we can get some extra eyes on that detail. First, I don't think this is an issue. Like John said, we aren't exposing git hash. Secondly... the API is a programing interface. Hiding the version number on a programing interface is... kind of crazy. It would be like making uname -a return (Probably Linux) instead of anything specific. Or probably libc, your guess is as good as mine. I get where people get freaked out about sharing, but, you can't have an API without sharing information about what it is and how to use it. The logical follow on from hiding the API version is we should delete all the API documentation as well, because someone might use it to do a bad thing. Thirdly, we're building an endpoint that we expect to be on the internet. If we think the only security for it is by hiding information about it, I think we've got to go back to the drawing board about a lot of things. Yes, it's hard to get that right. But that's kind of the whole point of the project. :) -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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
(Noting that its kind of late where I am). Sean, I totally agree that we should fix uname. Let's get on that. Michael On Mon, Jun 22, 2015 at 8:52 PM, Sean Dague s...@dague.net wrote: On 06/22/2015 05:28 AM, John Garbutt wrote: On 22 June 2015 at 00:14, Michael Still mi...@stillhq.com wrote: As an aside, do we think that exposing the exact version of a server process is safe from a security perspective? During discussions in the Nova API meeting, it was noted that while we do expose the exact API version, we are not exposing the git hash of the deployed cloud. Its certainly something we need to consider when we talk about bumping the micro-version for a security fix, but I suspect the need to backport is likely to force us to not bump the API version for such changes. Its certainly a concern that should be noted, in the hope we can get some extra eyes on that detail. First, I don't think this is an issue. Like John said, we aren't exposing git hash. Secondly... the API is a programing interface. Hiding the version number on a programing interface is... kind of crazy. It would be like making uname -a return (Probably Linux) instead of anything specific. Or probably libc, your guess is as good as mine. I get where people get freaked out about sharing, but, you can't have an API without sharing information about what it is and how to use it. The logical follow on from hiding the API version is we should delete all the API documentation as well, because someone might use it to do a bad thing. Thirdly, we're building an endpoint that we expect to be on the internet. If we think the only security for it is by hiding information about it, I think we've got to go back to the drawing board about a lot of things. Yes, it's hard to get that right. But that's kind of the whole point of the project. :) -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 -- Rackspace 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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 22 June 2015 at 00:14, Michael Still mi...@stillhq.com wrote: As an aside, do we think that exposing the exact version of a server process is safe from a security perspective? During discussions in the Nova API meeting, it was noted that while we do expose the exact API version, we are not exposing the git hash of the deployed cloud. Its certainly something we need to consider when we talk about bumping the micro-version for a security fix, but I suspect the need to backport is likely to force us to not bump the API version for such changes. Its certainly a concern that should be noted, in the hope we can get some extra eyes on that detail. Thanks, John On Sat, Jun 20, 2015 at 10:14 AM, Devananda van der Veen devananda@gmail.com wrote: Almost all of our discussions so far on this topic have left something out, which Monty pointed out to me last week. I'm following up now because E_TRAVEL... tldr; What we're versioning here are API's, not packages. It's not a question of numbering and dependency ordering, but of communicating support[ed|able] interfaces between running services. Libtool is more relevant than semver. http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html Right now we lack a means to express that the API response is compatible-with a particular previously-released version of the API. If we had that, instead of current-version, I believe we would have much happier users (and a happier Dmitry and jroll). Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. -Devananda On Tue, Jun 16, 2015 at 7:13 AM Dmitry Tantsur dtant...@redhat.com wrote: On 06/16/2015 03:47 PM, Jim Rollenhagen wrote: On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/20/2015 02:14 AM, Devananda van der Veen wrote: Almost all of our discussions so far on this topic have left something out, which Monty pointed out to me last week. I'm following up now because E_TRAVEL... tldr; What we're versioning here are API's, not packages. It's not a question of numbering and dependency ordering, but of communicating support[ed|able] interfaces between running services. Libtool is more relevant than semver. http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html Right now we lack a means to express that the API response is compatible-with a particular previously-released version of the API. If we had that, instead of current-version, I believe we would have much happier users (and a happier Dmitry and jroll). Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. +1 However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) That sounds really like something people actually want from us. Just one clarifying question: shouldn't b) and c) be compatible-with: 1.4, as 1.4 was a breaking change? Yes -- (b) and (c) are identical responses. Discuss. -Devananda On Tue, Jun 16, 2015 at 7:13 AM Dmitry Tantsur dtant...@redhat.com mailto:dtant...@redhat.com wrote: On 06/16/2015 03:47 PM, Jim Rollenhagen wrote: On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense?
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
As an aside, do we think that exposing the exact version of a server process is safe from a security perspective? Michael On Sat, Jun 20, 2015 at 10:14 AM, Devananda van der Veen devananda@gmail.com wrote: Almost all of our discussions so far on this topic have left something out, which Monty pointed out to me last week. I'm following up now because E_TRAVEL... tldr; What we're versioning here are API's, not packages. It's not a question of numbering and dependency ordering, but of communicating support[ed|able] interfaces between running services. Libtool is more relevant than semver. http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html Right now we lack a means to express that the API response is compatible-with a particular previously-released version of the API. If we had that, instead of current-version, I believe we would have much happier users (and a happier Dmitry and jroll). Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. -Devananda On Tue, Jun 16, 2015 at 7:13 AM Dmitry Tantsur dtant...@redhat.com wrote: On 06/16/2015 03:47 PM, Jim Rollenhagen wrote: On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Thanks Alex Xu Hi
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
Almost all of our discussions so far on this topic have left something out, which Monty pointed out to me last week. I'm following up now because E_TRAVEL... tldr; What we're versioning here are API's, not packages. It's not a question of numbering and dependency ordering, but of communicating support[ed|able] interfaces between running services. Libtool is more relevant than semver. http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html Right now we lack a means to express that the API response is compatible-with a particular previously-released version of the API. If we had that, instead of current-version, I believe we would have much happier users (and a happier Dmitry and jroll). Long version... Every HTTP response from Ironic today includes three headers: min, max, and version. The service can present an older API version, as long as it is greater-than-or-equal-to the minimum supported version, even if that version is incompatible with the maximum supported version. It does this by rewriting responses to match what was expected in the requested (older) version. When the newer version is identical *for all interfaces present* in the older version, this can be called compatible. Dmitry's point is that we don't need to hide newer interfaces from users who request an older API version, because the client won't know or care about things that weren't in the version it requested. However, we *do* need to signal their presence, and we don't have a good means for that right now. We also need to signal to the client that the response given is compatible with a certain age of API, even if it's not exactly the same. And we don't have any means for that, either. Time for an example Let's say that an incompatible change was made in v1.3. Let's also say that a change was made in v1.5 that added a new endpoint. Today, this is what the response headers would look like when calling a server running v1.5. a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4) c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5) What we have implemented today is that in case (b), the service will *hide* any changes that we introduced in v1.5. But those changes did not affect any functionality of the v1.4 API, so Dmitry objects to this. So do I. The issue at hand is the response in case (b) ... though after spending the last several months working on api versioning, I actually think all of those are poor responses. What I believe we should have: a) client requests v1.2, receives headers (min: 1.1, max: 1.5, compatible-with: 1.1) b) client requests v1.4, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) b) client requests v1.5, receives headers (min: 1.1, max: 1.5, compatible-with: 1.3) Yes -- (b) and (c) are identical responses. Discuss. -Devananda On Tue, Jun 16, 2015 at 7:13 AM Dmitry Tantsur dtant...@redhat.com wrote: On 06/16/2015 03:47 PM, Jim Rollenhagen wrote: On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Thanks Alex Xu Hi all! I'd like to try put in feedback based on living with microversions in Kilo release of Ironic. And here's my take, based on my experiences. Keep in mind I'm a core reviewer, a developer, and an operator of Ironic. Thanks Jim, much appreciated!
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Thanks Alex Xu Hi all! I'd like to try put in feedback based on living with microversions in Kilo release of Ironic. And here's my take, based on my experiences. Keep in mind I'm a core reviewer, a developer, and an operator of Ironic. From an ops perspective, our team has built our fair share of tooling to help us run Ironic. Some of it uses the REST API via python or node.js, and of course we all use the CLI client often. We also continuously deploy Ironic, for full transparency. My experience is not with how this works every 6 months, but in the day-to-day. First of all, after talking to folks off-list, I realized that we all, and the spec itself, confuse 3 aspects of microversion usage: 1. protecting from breaking changes. This is clearly a big win from user's point of view, and it allowed us to conduct painful change with renaming an important node state in our state machine. It will allows us even worse change this cycle: change of the default state. +1. Good stuff. My tooling doesn't break when I upgrade. Yay. 2. API discoverability. While I believe that there maybe be better implementation of this idea, I think I got it now. People want services to report API versions they support. People want to be able to request a specific version, and fail early if it is not present. Also +1 from me. I don't tend to personally do this. I usually am aware of what version of Ironic I'm running against. However I see how this could be useful for other folks. I do, however, use the versions to say, Oh, I can now request 1.5 which has logical names! That's useful, let's set those to the names in our CMDB. Now my tooling that interacts with the CMDB and Ironic can look at the version and decide to use node.name instead of the old hack we used to use. 3. hiding new features from older clients This is not directly stated by the spec, but many people imply it, and Nova and Ironic did it in Kilo. I want us to be clear: it is not the same as #2. You can report versions, but still allow new features to be used. This is still totally useful. If you know what version you are running against, you know exactly what features are available. I think the disconnect here is that we don't expect users (whether those are people or computers) to explicitly request a version. We need to message better that if you are using Ironic or building a tool against Ironic's API, you should be pinning the version. We also need to take this comment block[0] and put it in our docs, so users know what each version does. Knowing that I get feature X when I upgrade to version Y is useful. It is this particular thing that gets -2 from me, after I've seen how it worked in practice, and that's why. First of all, I don't believe anyone needs it. Seriously, I can't imagine a user asking please prevent me from using non-breaking changes. And attempt to implement it was IMO a big failure for the following reasons: a) It's hard to do. Even we, the core team, got confused, and for non-core people it took several iteration to do right. It's a big load on both developers and reviewers. I do agree with this. It's been painful. However, I think we're mostly past that pain at this point. Does this patch[1] look like developer pain? b) It's incomplete (at least for Ironic). We have several API-exposed things that are just impossible
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/16/2015 03:47 PM, Jim Rollenhagen wrote: On Tue, Jun 16, 2015 at 08:56:37AM +0200, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Thanks Alex Xu Hi all! I'd like to try put in feedback based on living with microversions in Kilo release of Ironic. And here's my take, based on my experiences. Keep in mind I'm a core reviewer, a developer, and an operator of Ironic. Thanks Jim, much appreciated! From an ops perspective, our team has built our fair share of tooling to help us run Ironic. Some of it uses the REST API via python or node.js, and of course we all use the CLI client often. We also continuously deploy Ironic, for full transparency. My experience is not with how this works every 6 months, but in the day-to-day. First of all, after talking to folks off-list, I realized that we all, and the spec itself, confuse 3 aspects of microversion usage: 1. protecting from breaking changes. This is clearly a big win from user's point of view, and it allowed us to conduct painful change with renaming an important node state in our state machine. It will allows us even worse change this cycle: change of the default state. +1. Good stuff. My tooling doesn't break when I upgrade. Yay. 2. API discoverability. While I believe that there maybe be better implementation of this idea, I think I got it now. People want services to report API versions they support. People want to be able to request a specific version, and fail early if it is not present. Also +1 from me. I don't tend to personally do this. I usually am aware of what version of Ironic I'm running against. However I see how this could be useful for other folks. I do, however, use the versions to say, Oh, I can now request 1.5 which has logical names! That's useful, let's set those to the names in our CMDB. Now my tooling that interacts with the CMDB and Ironic can look at the version and decide to use node.name instead of the old hack we used to use. 3. hiding new features from older clients This is not directly stated by the spec, but many people imply it, and Nova and Ironic did it in Kilo. I want us to be clear: it is not the same as #2. You can report versions, but still allow new features to be used. This is still totally useful. If you know what version you are running against, you know exactly what features are available. You know is about #2 - that's where confusion is :) so if you know, that moving to inspection state is disallowed for your tooling (but not for the whole system!), what does it give you? I think the disconnect here is that we don't expect users (whether those are people or computers) to explicitly request a version. We need to message better that if you are using Ironic or building a tool against Ironic's API, you should be pinning the version. We also need to take this comment block[0] and put it in our docs, so users know what each version does. Knowing that I get feature X when I upgrade to version Y is useful. It is this particular thing that gets -2 from me, after I've seen how it worked in practice, and that's why. First of all, I don't believe anyone needs it. Seriously, I can't imagine a user asking please prevent me from using non-breaking changes. And attempt to implement it was IMO a big failure for the following reasons: a) It's hard to do. Even we, the core team, got confused, and for non-core people it took several iteration to do right. It's a big load on both developers and reviewers. I do agree with this. It's
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/16/2015 08:56 AM, Dmitry Tantsur wrote: On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Thanks Alex Xu Hi all! I'd like to try put in feedback based on living with microversions in Kilo release of Ironic. First of all, after talking to folks off-list, I realized that we all, and the spec itself, confuse 3 aspects of microversion usage: 1. protecting from breaking changes. This is clearly a big win from user's point of view, and it allowed us to conduct painful change with renaming an important node state in our state machine. It will allows us even worse change this cycle: change of the default state. 2. API discoverability. While I believe that there maybe be better implementation of this idea, I think I got it now. People want services to report API versions they support. People want to be able to request a specific version, and fail early if it is not present. Also +1 from me. 3. hiding new features from older clients This is not directly stated by the spec, but many people imply it, and Nova and Ironic did it in Kilo. I want us to be clear: it is not the same as #2. You can report versions, but still allow new features to be used. It is this particular thing that gets -2 from me, after I've seen how it worked in practice, and that's why. First of all, I don't believe anyone needs it. Seriously, I can't imagine a user asking please prevent me from using non-breaking changes. And attempt to implement it was IMO a big failure for the following reasons: a) It's hard to do. Even we, the core team, got confused, and for non-core people it took several iteration to do right. It's a big load on both developers and reviewers. b) It's incomplete (at least for Ironic). We have several API-exposed things that are just impossible to hide. Good example are node states: if node is in a new state, we can't but expose it to older tooling. Our free-form JSON fields properties, instance_info, driver_info and driver_internal_info are examples as well. It's useless to speak about API contract, while we have those. c) It gives additional push back to making (required) breaking changes. We already got suggestions to have ONE MORE feature gating for breaking changes. Reason: people will need to increase microversions to get features, and your breaking change will prevent it. d) It requires a hard compromise on the CLI tool. You either default it to 1.0 forever, and force all the people to get used to figuring out version numbers and using `ironic --ironic-api-version x.y` every time (terrible user experience), or you default it to some known good version, bumping it from time to time. This, in turn, has 2 more serious problems: d.1) you start to break people \o/ that's not a theoretical concern: our downstream tooling did get broken by updating to newer ironicclient from git d.2) you require complex version negotiations on the client side. Otherwise imaging CLI tool defaulting to 1.6 will issue `node-create` to Ironic supporting only 1.5. Guess what? It will fail despite node-create being very old feature. Again, that's not something theoretical: that's how we broke TripleO CI. e) Every microversion should be fully tested separately. Which ended up in Ironic having 4 versions 1.2-1.5 that were never ever gate tested. Even worse, initially, our gate tested only the oldest version 1.1, but we solved it (though it took time to realize). The only good thing here is that these versions 1.2-1.5 were probably never used by anyone. To sum this long post up, I'm seeing that
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 06/04/2015 08:58 AM, Xu, Hejie wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum _https://review.openstack.org/#/c/184975/_ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): _https://review.openstack.org/#/c/187112_ And another guideline for when we should bump Mircoversion _https://review.openstack.org/#/c/187896/_ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Thanks Alex Xu Hi all! I'd like to try put in feedback based on living with microversions in Kilo release of Ironic. First of all, after talking to folks off-list, I realized that we all, and the spec itself, confuse 3 aspects of microversion usage: 1. protecting from breaking changes. This is clearly a big win from user's point of view, and it allowed us to conduct painful change with renaming an important node state in our state machine. It will allows us even worse change this cycle: change of the default state. 2. API discoverability. While I believe that there maybe be better implementation of this idea, I think I got it now. People want services to report API versions they support. People want to be able to request a specific version, and fail early if it is not present. Also +1 from me. 3. hiding new features from older clients This is not directly stated by the spec, but many people imply it, and Nova and Ironic did it in Kilo. I want us to be clear: it is not the same as #2. You can report versions, but still allow new features to be used. It is this particular thing that gets -2 from me, after I've seen how it worked in practice, and that's why. First of all, I don't believe anyone needs it. Seriously, I can't imagine a user asking please prevent me from using non-breaking changes. And attempt to implement it was IMO a big failure for the following reasons: a) It's hard to do. Even we, the core team, got confused, and for non-core people it took several iteration to do right. It's a big load on both developers and reviewers. b) It's incomplete (at least for Ironic). We have several API-exposed things that are just impossible to hide. Good example are node states: if node is in a new state, we can't but expose it to older tooling. Our free-form JSON fields properties, instance_info, driver_info and driver_internal_info are examples as well. It's useless to speak about API contract, while we have those. c) It gives additional push back to making (required) breaking changes. We already got suggestions to have ONE MORE feature gating for breaking changes. Reason: people will need to increase microversions to get features, and your breaking change will prevent it. d) It requires a hard compromise on the CLI tool. You either default it to 1.0 forever, and force all the people to get used to figuring out version numbers and using `ironic --ironic-api-version x.y` every time (terrible user experience), or you default it to some known good version, bumping it from time to time. This, in turn, has 2 more serious problems: d.1) you start to break people \o/ that's not a theoretical concern: our downstream tooling did get broken by updating to newer ironicclient from git d.2) you require complex version negotiations on the client side. Otherwise imaging CLI tool defaulting to 1.6 will issue `node-create` to Ironic supporting only 1.5. Guess what? It will fail despite node-create being very old feature. Again, that's not something theoretical: that's how we broke TripleO CI. e) Every microversion should be fully tested separately. Which ended up in Ironic having 4 versions 1.2-1.5 that were never ever gate tested. Even worse, initially, our gate tested only the oldest version 1.1, but we solved it (though it took time to realize). The only good thing here is that these versions 1.2-1.5 were probably never used by anyone. To sum this long post up, I'm seeing
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
2015-06-12 7:52 GMT+08:00 Rochelle Grober rochelle.gro...@huawei.com:
Just want to add that for logging purposes, consistency, as Devananda
explains and Adrian and Sean agree, is really important. The number of
fields in a header response should be consistent. If the field is not
always used, a placeholder should be put in (usually a “-“ in logs). Makes
parsing these things much easier.
Do you mean if X-OpenStack-Nova-API-Version is not in the response, the
server should return X-OpenStack-Nova-API-Version: -
or you mean if experimental flag is not in the response, the servers should
return X-OpenStack-Nova-API-Version: 2.2,-
BTW, is this described in http rfc?
Thanks for both consistency and for specific instance related info in the
message bodies. The operators also appreciate this.
--Rocky
*From:* Xu, Hejie [mailto:hejie...@intel.com]
*Sent:* Thursday, June 11, 2015 02:10
*To:* OpenStack Development Mailing List (not for usage questions)
*Subject:* Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum]
Microversion guideline in API-WG
Salvatore, thanks for the info, will try to review as soon as possible.
Hope we get consistent implementation.
*From:* Salvatore Orlando [mailto:sorla...@nicira.com]
*Sent:* Wednesday, June 10, 2015 4:51 PM
*To:* OpenStack Development Mailing List (not for usage questions)
*Subject:* Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum]
Microversion guideline in API-WG
As a further data point, Neutron has been trying to introduce
microversioning for a while, without success so far.
Given the sheer amount of backends the management layer integrates with,
and the constant need for the various subteams to experiment with the
API, the proposal [1] has probably some differences with the proposed
guideline.
Since the proposal is not yet approved nor implemented, perhaps it would
be worth looking at those differences, and get your advice on whether it
might be better if neutron adheres to the current guideline proposal or
whether it might be the case to include Neutron's requirements in the
current guideline proposal.
Salvatore
[1] https://review.openstack.org/#/c/136760/
On 10 June 2015 at 06:28, Xu, Hejie hejie...@intel.com wrote:
I updated the Microversion specification in API-WG
https://review.openstack.org/187112
The new patchset adds min/max version headers as Ironic used:
X-Openstack-[PROJECT]-API-Minimum-Version
X-Openstack-[PROJECT]-API-Maximum-Version
And new response body for invalid version request.
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
}
}
Which for backward compatible can add the existed fields in the response
also. For example, the nova response is
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
},
computeFault: {
message: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.,
code: 406
}
}
The “computeFault” fields is included by current implementation, we can
still add here, hope deprecated in the future.
And the “experimental” flag in the X-OpenStack-Nova-API-Version header was
deleted. It mentioned in the nova-spec but
It didn’t implement. And I didn’t saw the same thing in the ironic. For
current all the things satisfied all the cases. If we
“experimental” flag still usefull, we can propose separately.
Thanks
Alex
*From:* Devananda van der Veen [mailto:devananda@gmail.com]
*Sent:* Monday, June 8, 2015 1:59 AM
*To:* OpenStack Development Mailing List
*Subject:* Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum]
Microversion guideline in API-WG
On Jun 5, 2015 4:36 AM, Sean Dague s...@dague.net wrote:
On 06/05/2015 01:28 AM, Adrian Otto wrote:
On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
devananda@gmail.com mailto:devananda@gmail.com wrote:
On Jun 4, 2015 12:00 AM, Xu, Hejie hejie...@intel.com
mailto:hejie...@intel.com wrote:
Hi, guys,
I’m working on adding Microversion into the API-WG’s guideline
which
make sure we have consistent Microversion behavior in the API for
user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.
Hope all the projects which support( or plan to) Microversion can
join the review of guideline.
The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/
As I know
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
Salvatore, thanks for the info, will try to review as soon as possible. Hope we
get consistent implementation.
From: Salvatore Orlando [mailto:sorla...@nicira.com]
Sent: Wednesday, June 10, 2015 4:51 PM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
As a further data point, Neutron has been trying to introduce microversioning
for a while, without success so far.
Given the sheer amount of backends the management layer integrates with, and
the constant need for the various subteams to experiment with the API, the
proposal [1] has probably some differences with the proposed guideline.
Since the proposal is not yet approved nor implemented, perhaps it would be
worth looking at those differences, and get your advice on whether it might be
better if neutron adheres to the current guideline proposal or whether it might
be the case to include Neutron's requirements in the current guideline proposal.
Salvatore
[1] https://review.openstack.org/#/c/136760/
On 10 June 2015 at 06:28, Xu, Hejie
hejie...@intel.commailto:hejie...@intel.com wrote:
I updated the Microversion specification in API-WG
https://review.openstack.org/187112
The new patchset adds min/max version headers as Ironic used:
X-Openstack-[PROJECT]-API-Minimum-Version
X-Openstack-[PROJECT]-API-Maximum-Version
And new response body for invalid version request.
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
}
}
Which for backward compatible can add the existed fields in the response also.
For example, the nova response is
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
},
computeFault: {
message: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.,
code: 406
}
}
The “computeFault” fields is included by current implementation, we can still
add here, hope deprecated in the future.
And the “experimental” flag in the X-OpenStack-Nova-API-Version header was
deleted. It mentioned in the nova-spec but
It didn’t implement. And I didn’t saw the same thing in the ironic. For current
all the things satisfied all the cases. If we
“experimental” flag still usefull, we can propose separately.
Thanks
Alex
From: Devananda van der Veen
[mailto:devananda@gmail.commailto:devananda@gmail.com]
Sent: Monday, June 8, 2015 1:59 AM
To: OpenStack Development Mailing List
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
On Jun 5, 2015 4:36 AM, Sean Dague s...@dague.netmailto:s...@dague.net
wrote:
On 06/05/2015 01:28 AM, Adrian Otto wrote:
On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
devananda@gmail.commailto:devananda@gmail.com
mailto:devananda@gmail.commailto:devananda@gmail.com wrote:
On Jun 4, 2015 12:00 AM, Xu, Hejie
hejie...@intel.commailto:hejie...@intel.com
mailto:hejie...@intel.commailto:hejie...@intel.com wrote:
Hi, guys,
I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.
Hope all the projects which support( or plan to) Microversion can
join the review of guideline.
The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/
As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team
can take a
look at if you guys have compelling reason for using http headers.
And if we think return body instead of http headers, we probably
need think about back-compatible also. Because Microversion itself
isn’t versioned.
So I think we should keep those header for a while, does make sense?
Hope we have good guideline for Microversion, because we only can
change Mircoversion itself by back-compatible way.
Ironic returns the min/max/current API version in the http headers for
every request.
Why would it return this information in a header on success and in the
body on failure
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
Just want to add that for logging purposes, consistency, as Devananda explains
and Adrian and Sean agree, is really important. The number of fields in a
header response should be consistent. If the field is not always used, a
placeholder should be put in (usually a “-“ in logs). Makes parsing these
things much easier.
Thanks for both consistency and for specific instance related info in the
message bodies. The operators also appreciate this.
--Rocky
From: Xu, Hejie [mailto:hejie...@intel.com]
Sent: Thursday, June 11, 2015 02:10
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
Salvatore, thanks for the info, will try to review as soon as possible. Hope we
get consistent implementation.
From: Salvatore Orlando [mailto:sorla...@nicira.com]
Sent: Wednesday, June 10, 2015 4:51 PM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
As a further data point, Neutron has been trying to introduce microversioning
for a while, without success so far.
Given the sheer amount of backends the management layer integrates with, and
the constant need for the various subteams to experiment with the API, the
proposal [1] has probably some differences with the proposed guideline.
Since the proposal is not yet approved nor implemented, perhaps it would be
worth looking at those differences, and get your advice on whether it might be
better if neutron adheres to the current guideline proposal or whether it might
be the case to include Neutron's requirements in the current guideline proposal.
Salvatore
[1] https://review.openstack.org/#/c/136760/
On 10 June 2015 at 06:28, Xu, Hejie
hejie...@intel.commailto:hejie...@intel.com wrote:
I updated the Microversion specification in API-WG
https://review.openstack.org/187112
The new patchset adds min/max version headers as Ironic used:
X-Openstack-[PROJECT]-API-Minimum-Version
X-Openstack-[PROJECT]-API-Maximum-Version
And new response body for invalid version request.
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
}
}
Which for backward compatible can add the existed fields in the response also.
For example, the nova response is
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
},
computeFault: {
message: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.,
code: 406
}
}
The “computeFault” fields is included by current implementation, we can still
add here, hope deprecated in the future.
And the “experimental” flag in the X-OpenStack-Nova-API-Version header was
deleted. It mentioned in the nova-spec but
It didn’t implement. And I didn’t saw the same thing in the ironic. For current
all the things satisfied all the cases. If we
“experimental” flag still usefull, we can propose separately.
Thanks
Alex
From: Devananda van der Veen
[mailto:devananda@gmail.commailto:devananda@gmail.com]
Sent: Monday, June 8, 2015 1:59 AM
To: OpenStack Development Mailing List
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
On Jun 5, 2015 4:36 AM, Sean Dague s...@dague.netmailto:s...@dague.net
wrote:
On 06/05/2015 01:28 AM, Adrian Otto wrote:
On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
devananda@gmail.commailto:devananda@gmail.com
mailto:devananda@gmail.commailto:devananda@gmail.com wrote:
On Jun 4, 2015 12:00 AM, Xu, Hejie
hejie...@intel.commailto:hejie...@intel.com
mailto:hejie...@intel.commailto:hejie...@intel.com wrote:
Hi, guys,
I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.
Hope all the projects which support( or plan to) Microversion can
join the review of guideline.
The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/
As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
+1
On Jun 11, 2015, at 4:52 PM, Rochelle Grober
rochelle.gro...@huawei.commailto:rochelle.gro...@huawei.com wrote:
Just want to add that for logging purposes, consistency, as Devananda explains
and Adrian and Sean agree, is really important. The number of fields in a
header response should be consistent. If the field is not always used, a
placeholder should be put in (usually a “-“ in logs). Makes parsing these
things much easier.
Thanks for both consistency and for specific instance related info in the
message bodies. The operators also appreciate this.
--Rocky
From: Xu, Hejie [mailto:hejie...@intel.com]
Sent: Thursday, June 11, 2015 02:10
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
Salvatore, thanks for the info, will try to review as soon as possible. Hope we
get consistent implementation.
From: Salvatore Orlando [mailto:sorla...@nicira.com]
Sent: Wednesday, June 10, 2015 4:51 PM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
As a further data point, Neutron has been trying to introduce microversioning
for a while, without success so far.
Given the sheer amount of backends the management layer integrates with, and
the constant need for the various subteams to experiment with the API, the
proposal [1] has probably some differences with the proposed guideline.
Since the proposal is not yet approved nor implemented, perhaps it would be
worth looking at those differences, and get your advice on whether it might be
better if neutron adheres to the current guideline proposal or whether it might
be the case to include Neutron's requirements in the current guideline proposal.
Salvatore
[1] https://review.openstack.org/#/c/136760/
On 10 June 2015 at 06:28, Xu, Hejie
hejie...@intel.commailto:hejie...@intel.com wrote:
I updated the Microversion specification in API-WG
https://review.openstack.org/187112
The new patchset adds min/max version headers as Ironic used:
X-Openstack-[PROJECT]-API-Minimum-Version
X-Openstack-[PROJECT]-API-Maximum-Version
And new response body for invalid version request.
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
}
}
Which for backward compatible can add the existed fields in the response also.
For example, the nova response is
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
},
computeFault: {
message: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.,
code: 406
}
}
The “computeFault” fields is included by current implementation, we can still
add here, hope deprecated in the future.
And the “experimental” flag in the X-OpenStack-Nova-API-Version header was
deleted. It mentioned in the nova-spec but
It didn’t implement. And I didn’t saw the same thing in the ironic. For current
all the things satisfied all the cases. If we
“experimental” flag still usefull, we can propose separately.
Thanks
Alex
From: Devananda van der Veen
[mailto:devananda@gmail.commailto:devananda@gmail.com]
Sent: Monday, June 8, 2015 1:59 AM
To: OpenStack Development Mailing List
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
On Jun 5, 2015 4:36 AM, Sean Dague s...@dague.netmailto:s...@dague.net
wrote:
On 06/05/2015 01:28 AM, Adrian Otto wrote:
On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
devananda@gmail.commailto:devananda@gmail.com
mailto:devananda@gmail.commailto:devananda@gmail.com wrote:
On Jun 4, 2015 12:00 AM, Xu, Hejie
hejie...@intel.commailto:hejie...@intel.com
mailto:hejie...@intel.commailto:hejie...@intel.com wrote:
Hi, guys,
I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.
Hope all the projects which support( or plan to) Microversion can
join the review of guideline.
The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/
As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
As a further data point, Neutron has been trying to introduce
microversioning for a while, without success so far.
Given the sheer amount of backends the management layer integrates with,
and the constant need for the various subteams to experiment with the
API, the proposal [1] has probably some differences with the proposed
guideline.
Since the proposal is not yet approved nor implemented, perhaps it would be
worth looking at those differences, and get your advice on whether it might
be better if neutron adheres to the current guideline proposal or whether
it might be the case to include Neutron's requirements in the current
guideline proposal.
Salvatore
[1] https://review.openstack.org/#/c/136760/
On 10 June 2015 at 06:28, Xu, Hejie hejie...@intel.com wrote:
I updated the Microversion specification in API-WG
https://review.openstack.org/187112
The new patchset adds min/max version headers as Ironic used:
X-Openstack-[PROJECT]-API-Minimum-Version
X-Openstack-[PROJECT]-API-Maximum-Version
And new response body for invalid version request.
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
}
}
Which for backward compatible can add the existed fields in the response
also. For example, the nova response is
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
},
computeFault: {
message: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.,
code: 406
}
}
The “computeFault” fields is included by current implementation, we can
still add here, hope deprecated in the future.
And the “experimental” flag in the X-OpenStack-Nova-API-Version header was
deleted. It mentioned in the nova-spec but
It didn’t implement. And I didn’t saw the same thing in the ironic. For
current all the things satisfied all the cases. If we
“experimental” flag still usefull, we can propose separately.
Thanks
Alex
*From:* Devananda van der Veen [mailto:devananda@gmail.com]
*Sent:* Monday, June 8, 2015 1:59 AM
*To:* OpenStack Development Mailing List
*Subject:* Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum]
Microversion guideline in API-WG
On Jun 5, 2015 4:36 AM, Sean Dague s...@dague.net wrote:
On 06/05/2015 01:28 AM, Adrian Otto wrote:
On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
devananda@gmail.com mailto:devananda@gmail.com wrote:
On Jun 4, 2015 12:00 AM, Xu, Hejie hejie...@intel.com
mailto:hejie...@intel.com wrote:
Hi, guys,
I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for
user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.
Hope all the projects which support( or plan to) Microversion can
join the review of guideline.
The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/
As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the
requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team
can take a
look at if you guys have compelling reason for using http headers.
And if we think return body instead of http headers, we probably
need think about back-compatible also. Because Microversion itself
isn’t versioned.
So I think we should keep those header for a while, does make sense?
Hope we have good guideline for Microversion, because we only can
change Mircoversion itself by back-compatible way.
Ironic returns the min/max/current API version in the http headers for
every request.
Why would it return this information in a header on success and in the
body on failure? (How would this inconsistency benefit users?)
To be clear, I'm not opposed to *also* having a useful error message
in the body, but while writing the client side of api versioning,
parsing the range consistently from the response header is, IMO,
better than requiring a conditional.
+1. I fully agree with Devananda on this point. Use the headers
consistently, and add helpful errors into the body
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
I updated the Microversion specification in API-WG
https://review.openstack.org/187112
The new patchset adds min/max version headers as Ironic used:
X-Openstack-[PROJECT]-API-Minimum-Version
X-Openstack-[PROJECT]-API-Maximum-Version
And new response body for invalid version request.
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
}
}
Which for backward compatible can add the existed fields in the response also.
For example, the nova response is
{
versionFault: {
max_version: 5.2,
min_version: 2.1,
description: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.
},
computeFault: {
message: Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.,
code: 406
}
}
The “computeFault” fields is included by current implementation, we can still
add here, hope deprecated in the future.
And the “experimental” flag in the X-OpenStack-Nova-API-Version header was
deleted. It mentioned in the nova-spec but
It didn’t implement. And I didn’t saw the same thing in the ironic. For current
all the things satisfied all the cases. If we
“experimental” flag still usefull, we can propose separately.
Thanks
Alex
From: Devananda van der Veen [mailto:devananda@gmail.com]
Sent: Monday, June 8, 2015 1:59 AM
To: OpenStack Development Mailing List
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion
guideline in API-WG
On Jun 5, 2015 4:36 AM, Sean Dague s...@dague.netmailto:s...@dague.net
wrote:
On 06/05/2015 01:28 AM, Adrian Otto wrote:
On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
devananda@gmail.commailto:devananda@gmail.com
mailto:devananda@gmail.commailto:devananda@gmail.com wrote:
On Jun 4, 2015 12:00 AM, Xu, Hejie
hejie...@intel.commailto:hejie...@intel.com
mailto:hejie...@intel.commailto:hejie...@intel.com wrote:
Hi, guys,
I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.
Hope all the projects which support( or plan to) Microversion can
join the review of guideline.
The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/
As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team
can take a
look at if you guys have compelling reason for using http headers.
And if we think return body instead of http headers, we probably
need think about back-compatible also. Because Microversion itself
isn’t versioned.
So I think we should keep those header for a while, does make sense?
Hope we have good guideline for Microversion, because we only can
change Mircoversion itself by back-compatible way.
Ironic returns the min/max/current API version in the http headers for
every request.
Why would it return this information in a header on success and in the
body on failure? (How would this inconsistency benefit users?)
To be clear, I'm not opposed to *also* having a useful error message
in the body, but while writing the client side of api versioning,
parsing the range consistently from the response header is, IMO,
better than requiring a conditional.
+1. I fully agree with Devananda on this point. Use the headers
consistently, and add helpful errors into the body only as an addition
to that behavior, not a substitute.
I think the difference between Nova and Ironic here is that Nova doesn't
send all the headers all the time in the final implementation (that part
of the spec evolved out I think). Part of that was pressure about Header
bloat that people were concerned about, as that impacts caching layers.
I would a agree that if Ironic is sending all the headers all the time,
that's fine. However, for consistency it would be great to also put a
real body that explains the issue as well,
Agreed.
as headers are not the first
place people look when things go wrong, and are often not logged by
client side tools on errors (where the body would be).
-Sean
--
Sean Dague
http://dague.net
Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Jun 5, 2015 4:36 AM, Sean Dague s...@dague.net wrote: On 06/05/2015 01:28 AM, Adrian Otto wrote: On Jun 4, 2015, at 11:03 AM, Devananda van der Veen devananda@gmail.com mailto:devananda@gmail.com wrote: On Jun 4, 2015 12:00 AM, Xu, Hejie hejie...@intel.com mailto:hejie...@intel.com wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum https://review.openstack.org/#/c/184975/ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): https://review.openstack.org/#/c/187112 And another guideline for when we should bump Mircoversion https://review.openstack.org/#/c/187896/ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Ironic returns the min/max/current API version in the http headers for every request. Why would it return this information in a header on success and in the body on failure? (How would this inconsistency benefit users?) To be clear, I'm not opposed to *also* having a useful error message in the body, but while writing the client side of api versioning, parsing the range consistently from the response header is, IMO, better than requiring a conditional. +1. I fully agree with Devananda on this point. Use the headers consistently, and add helpful errors into the body only as an addition to that behavior, not a substitute. I think the difference between Nova and Ironic here is that Nova doesn't send all the headers all the time in the final implementation (that part of the spec evolved out I think). Part of that was pressure about Header bloat that people were concerned about, as that impacts caching layers. I would a agree that if Ironic is sending all the headers all the time, that's fine. However, for consistency it would be great to also put a real body that explains the issue as well, Agreed. as headers are not the first place people look when things go wrong, and are often not logged by client side tools on errors (where the body would be). -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 __ 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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
2015-06-04 22:23 GMT+08:00 Ruby Loo rlooya...@gmail.com: On 4 June 2015 at 02:58, Xu, Hejie hejie...@intel.com wrote: ... And another guideline for when we should bump Mircoversion *https://review.openstack.org/#/c/187896/* https://review.openstack.org/#/c/187896/ This is timely because just this very minute I was going to send out email to the Ironic community about this -- when *should* we bump the microversion. For fear of hijacking this thread, I'm going to start a new thread to discuss with Ironic folks first. Thanks Ruby As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. I don't want to change the ironic code so let's go with http headers. (That's a good enough reason, isn't it?) :-) So I translate to we want to back-compatible. By the way, did you see Ironic's spec on the/our desired behaviour between Ironic's server and client [1]? It's ... add your own adjective here. Emm... It's... great! Good news is there isn't big different between nova and ironic. Thanks Alex! --ruby [1] http://specs.openstack.org/openstack/ironic-specs/specs/kilo/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 __ 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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
2015-06-05 19:35 GMT+08:00 Sean Dague s...@dague.net: On 06/05/2015 01:28 AM, Adrian Otto wrote: On Jun 4, 2015, at 11:03 AM, Devananda van der Veen devananda@gmail.com mailto:devananda@gmail.com wrote: On Jun 4, 2015 12:00 AM, Xu, Hejie hejie...@intel.com mailto:hejie...@intel.com wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum https://review.openstack.org/#/c/184975/ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): https://review.openstack.org/#/c/187112 And another guideline for when we should bump Mircoversion https://review.openstack.org/#/c/187896/ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Ironic returns the min/max/current API version in the http headers for every request. Why would it return this information in a header on success and in the body on failure? (How would this inconsistency benefit users?) To be clear, I'm not opposed to *also* having a useful error message in the body, but while writing the client side of api versioning, parsing the range consistently from the response header is, IMO, better than requiring a conditional. +1. I fully agree with Devananda on this point. Use the headers consistently, and add helpful errors into the body only as an addition to that behavior, not a substitute. I think the difference between Nova and Ironic here is that Nova doesn't send all the headers all the time in the final implementation (that part of the spec evolved out I think). Part of that was pressure about Header bloat that people were concerned about, as that impacts caching layers. Can I ask more detail about this concern? Header bloat may have performance problem for extra data transfer between server and client. For the caching, we use Vary header. What impact you refer to? I would a agree that if Ironic is sending all the headers all the time, that's fine. However, for consistency it would be great to also put a real body that explains the issue as well, as headers are not the first place people look when things go wrong, and are often not logged by client side tools on errors (where the body would be). Thanks all the replied, let me update the guideline. -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 __ 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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Jun 4, 2015, at 11:03 AM, Devananda van der Veen devananda@gmail.commailto:devananda@gmail.com wrote: On Jun 4, 2015 12:00 AM, Xu, Hejie hejie...@intel.commailto:hejie...@intel.com wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum https://review.openstack.org/#/c/184975/ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): https://review.openstack.org/#/c/187112 And another guideline for when we should bump Mircoversion https://review.openstack.org/#/c/187896/ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Ironic returns the min/max/current API version in the http headers for every request. Why would it return this information in a header on success and in the body on failure? (How would this inconsistency benefit users?) To be clear, I'm not opposed to *also* having a useful error message in the body, but while writing the client side of api versioning, parsing the range consistently from the response header is, IMO, better than requiring a conditional. +1. I fully agree with Devananda on this point. Use the headers consistently, and add helpful errors into the body only as an addition to that behavior, not a substitute. Adrian -Deva __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.orgmailto: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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On Jun 4, 2015 12:00 AM, Xu, Hejie hejie...@intel.com wrote: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum https://review.openstack.org/#/c/184975/ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): https://review.openstack.org/#/c/187112 And another guideline for when we should bump Mircoversion https://review.openstack.org/#/c/187896/ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Ironic returns the min/max/current API version in the http headers for every request. Why would it return this information in a header on success and in the body on failure? (How would this inconsistency benefit users?) To be clear, I'm not opposed to *also* having a useful error message in the body, but while writing the client side of api versioning, parsing the range consistently from the response header is, IMO, better than requiring a conditional. -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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
On 4 June 2015 at 02:58, Xu, Hejie hejie...@intel.com wrote: ... And another guideline for when we should bump Mircoversion *https://review.openstack.org/#/c/187896/* https://review.openstack.org/#/c/187896/ This is timely because just this very minute I was going to send out email to the Ironic community about this -- when *should* we bump the microversion. For fear of hijacking this thread, I'm going to start a new thread to discuss with Ironic folks first. As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. I don't want to change the ironic code so let's go with http headers. (That's a good enough reason, isn't it?) :-) By the way, did you see Ironic's spec on the/our desired behaviour between Ironic's server and client [1]? It's ... add your own adjective here. Thanks Alex! --ruby [1] http://specs.openstack.org/openstack/ironic-specs/specs/kilo/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] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
Hi Alex, Based on my understanding, the Mangum code base is get from Ironic, that's why Magnum using http headers because when Magnum was created, Ironic is also using http headers. Perhaps Magnum can follow the way how Ironic move to use Microversion? Thanks. 2015-06-04 14:58 GMT+08:00 Xu, Hejie hejie...@intel.com: Hi, guys, I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user. The Nova and Ironic already have Microversion implementation, and as I know Magnum *https://review.openstack.org/#/c/184975/* https://review.openstack.org/#/c/184975/ is going to implement Microversion also. Hope all the projects which support( or plan to) Microversion can join the review of guideline. The Mircoversion specification(this almost copy from nova-specs): *https://review.openstack.org/#/c/187112* https://review.openstack.org/#/c/187112 And another guideline for when we should bump Mircoversion *https://review.openstack.org/#/c/187896/* https://review.openstack.org/#/c/187896/ As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also. Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a look at if you guys have compelling reason for using http headers. And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned. So I think we should keep those header for a while, does make sense? Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way. Thanks Alex Xu __ 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 -- Thanks, Jay Lau (Guangya Liu) __ 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
