Compatibility checks

As the System Device is running Mender, it stores all information about currently installed Artifacts in its database, allowing direct comparisons between a given Artifact and what's currently present on the Device. This is used to check if an Artifact is currently installed and if an Artifact can be installed on the Device.

However, as the Components do not need to run Mender in order to be updated by the Orchestrator, there's no requirement for them to keep track of all the data from the Artifact.

To allow the Components to handle the updates and not require them to have a database, Orchestrator checks are different.

This section contains details on how Orchestrator checks whether an Artifact is currently installed on a Component and if an Artifact can be installed on a Component.

Artifact versioning for Components

Interface requirements

Every Interface other than:

• Interface for updating the System Device running Mender

• Any Interface communicating with a Component running Mender

Must include a version identifier in its Provides data using the following format: rootfs-image.<INTERFACE_NAME>.version

For the System Device (or any Component running mender-update), rootfs-image.version is reported automatically. In these cases, providing an additional rootfs-image.<INTERFACE_NAME>.version field is not necessary.

This requirement enables the Orchestrator to interact with the metadata automatically generated by mender-artifact. When building an Artifact for an Interface, mender-artifact automatically adds versioning information as defined in the Software Versioning specification.

Usage

The rootfs-image.<INTERFACE_NAME>.version field is used for two operations:

Inventory Reporting: The Component reports this specific field to the Mender Server as its currently installed software version.

Checking if an Artifact is currently installed: Orchestrator compares the reported version against the incoming Artifact's artifact_provides to determine if the Artifact is already installed, preventing redundant updates.

Compatibility and Dependency Checking

Orchestrator follows standard Mender logic for checking Artifact compatibility, i.e. whether an Artifact can be installed on a Component:

Artifact Depends: If an Artifact contains artifact_depends metadata for a specific value, the Orchestrator validates that the target Component meets these requirements.

No Dependency: If no artifact_depends: rootfs-image.<INTERFACE_NAME>.version is specified, the version information is not checked for compatibility, and the update is permitted regardless of the version currently installed on the Component.

Flexibility

The requirement for the version field does not restrict the inclusion of other metadata. Users can add any arbitrary key-value pairs to the Provides section of an Interface, exactly as they would for standard Mender Artifacts.

These fields will be checked as for any other Artifact, i.e. if an Artifact depends on a specific field, it will be installed only if the Interface includes it in Provides command output.

Example

Creating an Artifact for an rtos-interface:

INTERFACE=rtos-interface
COMPONENT_TYPE=rtos
VERSION=rtos-v1
PAYLOAD=$VERSION-payload

touch $PAYLOAD
mender-artifact \
  write module-image \
  --type $INTERFACE \
  --compatible-types $COMPONENT_TYPE \
  --file $PAYLOAD \
  --output-path $VERSION.mender \
  --artifact-name $VERSION

rm $PAYLOAD

Will result in an Artifact like this:

Mender Artifact:
  Name: rtos-v1
  Format: mender
  Version: 3
  Signature: no signature
  Compatible types: [rtos]
  Provides group: 
  Depends on one of artifact(s): []
  Depends on one of group(s): []
  State scripts: []

Updates:
  - Type: rtos-interface
    Provides:
      rootfs-image.rtos-interface.version: rtos-v1
    Depends: {}
    Clears Provides: [rootfs-image.rtos-interface.*]
    Metadata: {}
    Files:
      - checksum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
        modified: 2026-04-27 15:16:29 +0200 CEST
        name: rtos-v1-payload
        size: 0

To ensure that, while deploying this Artifact to a Component that already uses it, the Artifact is not installed again, the Interface must report rootfs-image.rtos-interface.version=rtos-v1 in its Provides output.