Agent and Controller Version Compatibility
This section describes how version compatibility in the agent and controller system works.
Versions are MAJOR.MINOR.PATCH. Currently, both the agent and controller are built from the same git repository and share a common version. This means a minor patch in the controller may cause a version change in the agent, even if there were no changes in the agent code base.
Older agents are generally going to work with newer controllers, so long as the major version is the same. There is no guarantee if the major version is not identical.
If the major version changes:
Nothing is guaranteed to be backward compatible, although any changes should be well documented.
If the minor version changes:
Upgrading to the new version is required to use the new features.
Agent config.yaml may change because this is provided in the manifest, so customers should not care.
Agent service.yaml should be backward compatible.
Controller configuration should not generally be incompatible, however, this is less of a requirement as in a SaaS install this is the side we control.
The wire protocol (GRPC) remains compatible.
The controller command/control REST API remains compatible.
If the patch version changes:
No incompatibility should occur.
Patchlevel are always safe to upgrade to, even if this means the agent is newer than the controller. This allows bug fixes and such to be pushed in an emergency.
Version Touch Points
Five external compatibility points exist as follows:
The controller has a config file format.
The agent has a config file format that we provide, which includes things like the controller's endpoint, certificates to use, etc.
The agent has a services.yaml that is customer supplied.
The controller has an external API which is called to add agents and obtain credentials for services.
The controller and agent share a GRPC definition.
Each of these can change and could be a compatibility issue.
History
The first GRPC protocol and first config files could be called "V1" and implemented as a unidirectional HTTP proxy. The GRPC format used was hard to extend, and different concepts were all at the top level of the agent configuration file format. This made it difficult to add new features in a backward-compatible way.
V2 addresses this by making some rules to ensure older agents will remain compatible with newer controllers, and a versioning scheme to indicate when compatibility issues could arise.
At this point, the "V2" protocol is able to be altered, and so should be ignored when discussing agent versions.
Versioning Scheme
Semantic versions are used, where the format is MAJOR.MINOR.PATCH, such as v3.5.2.
When the major version changes chances are there will be incompatibility, and this should be documented.
Minor versions indicate added features or larger changes, but should generally not cause incompatibility at any level. It is more of a minimum level needed to use new features. For example, if a new feature is added to the agent that sends additional data to the controller, and this was added in 1.3.0, both controller and agent would need to be at least 1.3.0 for this feature to fully operate.
Patch versions should never cause incompatibility and should always be safe to upgrade to.
Only the latest version is supported. That is, if a bug is found in version 1.4.5 and 1.8.9 is the latest, the expectation is that the agents and controller will be upgraded to the latest version with the bug fix.
Version Compatibility
The greatest effort and promise is that older agent versions should always be able to connect to a newer controller.
There is no guarantee that newer agents should be able to connect to an older controller, although this is most likely the case. However, it is not promised nor intended (except for the patch version, which can by definition never cause a compatibility issue.)
Agent Version Compatibility
Major version changes may break anything, but this should not be done without a good reason. This is not a frequent issue, and no major upgrades are planned at this time.
Minor (feature) changes will occur frequently. Adding a new feature may require changes to the configuration file, but that is only when that feature is to be used. Existing configurations should cause compatible behavior. That is, going from 1.2.5 to 1.3.0 should not require changing the agent's service.yaml file, although the config.yaml may change as we ship this in a manifest. However, incompatibility should also be avoided.
Controller Version Compatibility
The controller is a bit more relaxed in compatibility with configuration files, as the largest use case is a SaaS install, where we control the controller and its associated configuration file directly, and can upgrade both when needed.
The command/control API is treated similarly to the agent compatibility, in that the API should not become incompatible without good reason, and generally handle incompatible changes with an API version change (/api/v2 vs /api/v2) for that endpoint, with a timeline on when the older API version will be deprecated.
Last updated