Compatibility

reference

This document outlines the compatibility between different versions of Mender components, such as the client and server.

Backward compatibility policy

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, minor releases add new functionality (e.g from 1.2.0 to 1.3.0) so be sure to upgrade components to support the newer functionality before using it.

For example, when Mender releases a new Artifact format version, the new Mender client still supports 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, always update the server before the client.

Mender also follows different support durations for different minor versions with LTS releases. Please refer to the Release-information for more information about LTS releases and the release schedule.

Specific versioning criteria

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.

Changes resulting in new major version (M.m.p)

  • Removing or changing existing command line options

  • Removing or changing existing REST API

  • Edge case: Changing default behavior, with the old behavior still available. An example is changing the default artifact format version in mender-artifact. We have opted for upgrading the major version in this case, but this could also go into a minor release

Changes resulting in new minor version (m.M.p)

  • Adding command line options

  • Adding new REST API, or adding fields to responses of existing REST API

  • Doing a database migration that is incompatible with the old schema (downgrade usually not possible without restoring a backup)

Changes resulting in new patch version (m.m.P)

  • Any change to our Golang API. For example, the mender-artifact library has an API, used by other components, but this API is not considered public

  • It should always be possible to freely upgrade and downgrade between patch versions in the same minor series

Mender client and Yocto Project version

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.

Clarification of the table:

  • stable - recipe is maintained by Northern.tech
  • community - best effort maintenance from community and Northern.tech
  • no - recipe has never been released
Client vs meta-mender version warrior (2.7)2 zeus (3.0) dunfell (3.1)
Older no no no
Mender client 1.5.x no no no
Mender client 1.6.x no no no
Mender client 1.7.x1 community no no
Mender client 2.0.x community no no
Mender client 2.1.x community no no
Mender client 2.2.x community community stable
Mender client 2.3.x community community stable
Mender client 2.4.x community community stable
Mender client 2.5.x community community stable
Mender client 2.6.x community community stable
Mender client 3.0.x no community stable3
Mender client 3.1.x no community stable3
Mender client 3.2.x no community stable3
Mender client 3.3.x no community stable3

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

2 If upgrading from thud to newer versions, see also known issues when upgrading from thud to newer versions.

3 Mender client 3.0.0 and later are not installed by default in Yocto branches 3.1 (dunfell) and older. To enable this or a later version, please see the PREFERRED_VERSION setting when configuring the Yocto build.

Leverage Mender consulting services to support other versions of the Yocto Project for your board and environment.

Mender client/server and Artifact format

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
Mender 2.6.x / mender-artifact 3.5.x no yes yes
Mender 2.7.x / mender-artifact 3.5.x no yes yes
Mender 3.0.x / mender-artifact 3.6.x no yes yes
Mender 3.1.x / mender-artifact 3.6.x no yes yes
Mender 3.2.x / mender-artifact 3.7.x no yes yes
Mender 3.3.x / mender-artifact 3.8.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.

Mender server and client API

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.

The higher version API contains a mix of old and new API endpoints. For endpoints which haven't changed in the new version the previous version ones are assumed.

Example The device supports the V2 API. It expects the single V2 endpoint to be available. For all other endpoints it will use the V1.

API v1 API v2
Mender server 1.x.x and 2.x.x yes no
Mender server 3.0.0 and later yes yes
------------------------------- -------- --------
Mender client 1.x.x and 2.x.x yes no
Mender client 3.0.0 and later yes yes

Mender client and Mender connect

Mender client / mender-connect mender-connect version
2.6.x 1.0.x
2.7.x 1.1.x
3.0.x 1.2.x
3.1.x 1.2.x
3.2.x 2.0.x 1
3.3.x 2.0.x 1

1 mender-connect 2.0.0 and later are not installed by default in Yocto branches 3.1 (dunfell) and older. To enable this or a later version, please see the PREFERRED_VERSION setting when configuring the Yocto build.

We welcome contributions to improve this documentation. To submit a change, use the Edit link at the top of the page or email us at .