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.
--
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