----- Original Message -----
From: "Vinzenz Feenstra" vfeenstr@redhat.com To: "Dan Kenigsberg" danken@redhat.com Cc: "VDSM Project Development" vdsm-devel@lists.fedorahosted.org Sent: Monday, January 27, 2014 4:00:55 PM Subject: Re: [vdsm] Introduction of VDSM <-> Guest Agent API Versioning
On 01/27/2014 02:57 PM, Dan Kenigsberg wrote:
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.
Second point "VDSM gets downgraded or upgraded..."
- 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?)
This section lists things which were suggested to be included in the thoughts, however I personally do not agree and describe why.
- 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.
same here.. don't see any problem with that suggestion. usually when protocol starts between 2 edges they both sync the same api version in one of the headers, so it sounds quite the same to me
-- Regards,
Vinzenz Feenstra | Senior Software Engineer RedHat Engineering Virtualization R & D Phone: +420 532 294 625 IRC: vfeenstr or evilissimo
Better technology. Faster innovation. Powered by community collaboration. See how it works at redhat.com
vdsm-devel mailing list vdsm-devel@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/vdsm-devel