----- Original Message -----
> From: "Vinzenz Feenstra" <vfeen...@redhat.com>
> To: "Dan Kenigsberg" <dan...@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
>
_______________________________________________
vdsm-devel mailing list
vdsm-devel@lists.fedorahosted.org
https://lists.fedorahosted.org/mailman/listinfo/vdsm-devel
