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
- 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:
======================================================
- 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.
Thanks.
--
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
[email protected]
https://lists.fedorahosted.org/mailman/listinfo/vdsm-devel
