On Wed, Jan 22, 2014 at 12:12:53PM +0100, Vinzenz Feenstra wrote: > Hi, > > With the increasing complexity on different version of the guest > agent and vdsm > I have proposed a patchset for each the guest agent and vdsm to > implement it on > top of the current protocol, in a way that it will not affect the > existing protocol. > This patchset has created some controversy about its implementation > and design > and I was asked to kick off a discussion to design a better > implementation or > validate the suggested approach. > > > My goals for the API versioning: > =============================== > - Make VDSM and the Guest Agent both aware of what the other side > understands > (which messages) to avoid logging errors > > - The used version of the API should be automatically and > immediately be agreed > upon in case any change happened. And in case one end doesn't > support it but > the other does, the supporting end must revert back to a > compatible state. > > Possible scenarios: > - a VM gets migrated from a VDSM version with API version support > to a VDSM > without API version support (or lower version) > > - VDSM gets downgraded or upgraded and the API version changed or is no > longer supported > > - The ovirt-guest-agent gets up or downgraded
and Vdsm upgrade, too. > > - Make use of existing messages which allow extending without > generating errors > or would result in VDSM API changes due to direct export of the > message, to be > backwards compatible on both ends > > From my side not considered as goals for the API Versioning: > ====================================================== (sorry, I do not understand this section and its title. are these things you need? nice-to-have? would like to avoid?) > - Deprecation of messages, because you can send alternatives if the > other side > supports it > - Raising the lowest supported API version, as this would actually > break backwards > compatibility > > > The proposed solution: > ====================== > > VDSM: > - Add a field to the 'refresh' message reporting the highest API version > supported by VDSM > > - Upon receiving the 'heartbeat' message check for the `apiVersion` field > to know if the guest agent supports api versioning. > - If the fields is not present: > The guest agent won't support api versioning. And it needs to be > disabled on the VDSM side and the version 0 has to be assumed. That > simply means only messages can be sent which were supported > before the > API versioning was introduced. > - If the field is present: > The value of the field is supposed to represent the maximum version > supported by the guest agent. > > VDSM then makes a `min(vdsmMaxApiVersion, guestAgentMaxApiVersion)` > to determine the highest common value and uses this value as > supported > API version. > When the value has changed since the last time a heartbeat was > received. > VDSM will send a message 'api-version' to update the guest > agent about > the determined value. And sets the internally stored apiVersion value > to this new value. > > Guest Agent: > - Adds the field `apiVersion` to the heartbeat containing the > highest API > version supported by the guest agent > > - Upon receiving the `refresh` message without a `apiVersion` field, the > guest agent immediately will revert immediately fall back to version 0 > To avoid sending any messages which are not yet supported. > > - Upon receiving the `api-version` message, the guest agent will > verify the > value received and sets the value to min(received, maxAgentApiVersion) > which should, of course, result in setting the received value (this is > just an additional step to ensure it does not send more than > supported by > VDSM. > > > Once having the API version, we can use some lookup table for the messages > before sending and check which version is required to send it. And we would > even be able to give some feedback if we support a feature or not on > the guest > side. > > Please let me know your opinion and I would be welcoming suggestions or any > other comment related to this. I find this reasonable solution - despite several comments that I had regarding the implementation's clarity. _______________________________________________ vdsm-devel mailing list vdsm-devel@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/vdsm-devel
