This document outlines the compatibility between different versions of Mender components, such as the client and server.
Mender always provides an upgrade path from the past patch (e.g. 1.2.0 to 1.2.1) and minor version (e.g. 1.1.1 to 1.2.0), and releases follow Semantic Versioning. Note that according to Semantic Versioning, new functionality can be added in minor releases (e.g from 1.2.0 to 1.3.0) so be sure to upgrade components to support the newer functionality before starting to use it.
For example, when a new Artifact format version is released, the new Mender client would support older versions of the Artifact format. However, the inverse is not true; the Mender client does not support newer versions of the Artifact format. So in this case you need to upgrade all Mender clients before starting to use new versions of the Artifact format (and the features it enables).
As another example, the Mender client supports one version of the server API, while the server can support several API versions. Therefore, the server should always be upgraded before the client.
Since Semantic Versioning was primarily written for libraries, it is not necessarily clear what constitutes an API in the context of Mender. Below are the lists of specific criteria we use for our versioning policy.
Removing or changing existing command line options
Removing or changing existing REST API
mender-artifact. We have opted for upgrading the major version in this case, but this could also go into a minor release
Adding command line options
Adding new REST API, or adding fields to responses of existing REST API
Any change to our Golang API. For example, the
mender-artifact library has
an API, which is used by some other components, but this API is not considered
In general the Mender client introduces new features in minor (e.g. 1.2.0 to 1.3.0) versions and the meta-mender layer is updated accordingly to easily support these new features (e.g. by exposing new MENDER_* variables). The meta-mender layer has branches corresponding to versions of the Yocto Project.
|Client vs meta-mender version||Older||warrior (2.7)3||zeus (3.0)||dunfell (3.1)|
|Mender client 1.5.x||community||no||no||no|
|Mender client 1.6.x||community||no||no||no|
|Mender client 1.7.x2||community||community||no||no|
|Mender client 2.0.x||community||community||no||no|
|Mender client 2.1.x||community||community||no||no|
|Mender client 2.2.x||community||community||community||stable|
|Mender client 2.3.x||community||community||community||stable|
|Mender client 2.4.x||community||community||community||stable|
1 For very old versions of Yocto, check the documentation for that specific Mender version using the left hand menu.
2 Rolling back to 1.x.x from a failed upgrade to 2.x.x is supported. However, it is not possible to downgrade to a Mender 1.x.x client from a 2.x.x client, once the update containing 2.x.x has been committed.
3 If upgrading from thud to warrior, see also known issues when upgrading from thud to warrior.
Leverage Mender consulting services to support other versions of the Yocto Project for your board and environment.
The Mender Artifact format is managed by the Mender Artifacts Library, which is included in the Mender client and server (for reading Artifacts) as well as in a standalone utility
mender-artifact (for writing Artifacts).
|Artifact v1||Artifact v2||Artifact v3|
|Mender 1.0.x / mender-artifact 1.0.x||yes||no||no|
|Mender 1.1.x / mender-artifact 2.0.x||yes||yes||no|
|Mender 1.2.x / mender-artifact 2.1.x||yes||yes||no|
|Mender 1.3.x / mender-artifact 2.1.x||yes||yes||no|
|Mender 1.4.x / mender-artifact 2.2.x||yes||yes||no|
|Mender 1.5.x / mender-artifact 2.2.x||yes||yes||no|
|Mender 1.6.x / mender-artifact 2.3.x||yes||yes||no|
|Mender 1.7.x / mender-artifact 2.4.x||yes||yes||no|
|Mender 2.0.x / mender-artifact 3.0.x||no||yes||yes|
|Mender 2.1.x / mender-artifact 3.1.x||no||yes||yes|
|Mender 2.2.x / mender-artifact 3.2.x||no||yes||yes|
|Mender 2.3.x / mender-artifact 3.3.x||no||yes||yes|
|Mender 2.4.x / mender-artifact 3.4.x||no||yes||yes|
|Mender 2.5.x / mender-artifact 3.4.x||no||yes||yes|
Older Mender clients do not support newer versions of the Artifact format; they will abort the deployment. You can build older versions of the Mender Artifact format to upgrade older Mender clients. See Write a new Artifact for an introduction how to do this.
The compatibility between the Mender server and client is managed by the Device API versions exposed by the server and used by the client. If the Mender server supports the API version of the Mender client, they are compatible. However, please ensure that the client and server support the Artifact format version you are using. Device API docs are available in the API chapter.
|Mender server versions||Mender client versions|
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to submit changes.
© 2020 Northern.tech AS