OTA Connect Developer Guide

Add custom metadata fields to Targets metadata

You may want to include extra metadata about your software inside the signed Uptane metadata that OTA Connect delivers to your device. Some reasons you might want to do this include:

  • To provide installation instructions or scripts for an image that cannot or should not be included in the image itself.

  • To add extra tracking fields for internal compliance or auditing.

To accommodate this use case, you can manually manage your Uptane metadata and add custom fields to your targets.json file.

For more information on additional use cases that require customization of the Targets metadata, see the related section of the Uptane standard.

Prerequisites

Before you write a custom metadata handler, do the following:

Anatomy of the targets.json metadata

Your targets.json file includes:

  • The signatures block that contains key IDs and signatures generated over the signed block.

  • The signed block that contains the Uptane fields.

  • In the signed block, the targets block that lists all of your software versions.

    Target is a term from Uptane. Each Target corresponds to a software version available in your OTA Connect software repository.

    Each target is identified by its name and version and contains three objects:

    • hashes – the SHA256 hash of the software version.

    • length – the length of the target, in bytes.

    • custom – other metadata that aktualizr uses.

      Example 1. The custom object
      "custom": {
        "name": "aegisub-font",
        "version": "1",
        "hardwareIds": [
          "kmk-docker-debian"
        ],
        "targetFormat": null,
        "uri": null,
        "createdAt": "2018-08-20T09:28:27Z",
        "updatedAt": "2018-08-20T09:28:27Z"
      }

      You can add your custom metadata to the custom object.

Add custom metadata

You can always modify your targets.json file to include more metadata.

To add custom metadata:

  1. In the targets.json file, navigate to the custom object, and specify any metadata fields that you want to add.

    Do not modify any of the existing values. We recommend to add a new field namespaced to your organization or some other unique identifier, and then put any custom sub-keys under that field, as in the example below.

    Example 2. Custom metadata
    "custom": {
      "name": "aegisub-font",
      "version": "1",
      "hardwareIds": [
        "kmk-docker-debian"
      ],
      "targetFormat": null,
      "uri": null,
      "createdAt": "2018-08-20T09:28:27Z",
      "updatedAt": "2018-08-20T09:28:27Z",
      "acme_inc_metadata": {
        "application_install_handler": "com.dockerconfig.packager",
        "build_correlation_id": "2ce4ebaf-b3ca-411b-977f-cd6b98065d88"
      }
    }
  2. Sign the modified metadata.

    garage-sign targets sign --repo myimagerepo --key-name mytargets
  3. Upload your customized targets.json to OTA Connect.

    garage-sign targets push --repo myimagerepo
If you want to add custom metadata while bitbaking, modify the IMAGE_CMD_garagesign function in image_types_ostree.bbclass. For more information, see the Yocto Reference Manual.

To learn more about the garage-sign commands and options, see its reference documentation.