balena-io / contracts

Balena.io Base Contracts

Balena Base Contracts

The collection of contracts and partials across the balena system.

Contracts

Each contract is a .json file inside the contracts/ directory. The convention is to store one contract per file, located in contracts/<type>/<slug>.json.

Partials

This directory contains partials that apply to certain combinations of contracts. The convention is to store a partial in partials/<combination>/<combination instantiation>/<partial>.tpl. Here are some examples:

partials/sw.os+arch.sw/debian+amd64/installation.tpl
partials/sw.os+arch.sw/debian/installation.tpl
partials/hw.device-type/ts4900/remove-install-media.tpl

The combination section defines the types of contracts that come into play for a particular partials subtree, separated by a + symbol. If the combination is sw.os+arch.sw, then it means that the subtree will take into account the combination of operating systems and architectures. Note that there can be combinations of a single type.

The combination instantiation section defines a subtree for a specific set of contracts that match the combination type. If the combination is sw.os+arch.sw, a valid combination instantiation can be debian+amd64, which is the subtree that will be selected when matching the Debian GNU/Linux contract with the amd64 architecture contract.

Note that a combination instantiation may use @ symbols to define subtrees for a specific version of one or more contracts in the combination. For example, debian@wheezy+amd64 will be the subtree containing partials for the combination of Debian Wheezy and amd64.

You can also omit trailing portions of the combination instantiation to implement wildcards. If the combination is sw.os+arch.sw and the instantiation is debian, it means that such subtree will apply to the combination of Debian GNU/Linux with any architecture.

The partial tree is then traversed from specific to general, until a match is found. This is the path that the contract system will follow when searching for the download template on the sw.os+arch.sw combination:

sw.os+arch.sw/<os>@<version>+<arch>@<version>/download.tpl
sw.os+arch.sw/<os>@<version>+<arch>/download.tpl
sw.os+arch.sw/<os>+<arch>@<version>/download.tpl
sw.os+arch.sw/<os>+<arch>/download.tpl
sw.os+arch.sw/<os>/download.tpl

Instruction Partials

With a recent change, several changes were made to the overall contract spec to be able to work around problems happening and being able generate accurate provisioning instructions for device types using contracts. Some information is present below:

flashProtocol

If there is a flashProtocol defined then we know that we need to flash directly to the device. This process will require no storage media to be attached. After identifying which protocols etcher can or can't support will determine flash protocol for that device type and subsequently the instructions for the device type as well.

Example, in this case jetsonFlash is not supported by etcher so we will need to give jetson flashing specific instructions:

    "flashProtocol": "jetsonFlash",
    "media": {
      "defaultBoot": "internal",
      "altBoot": []
    },

On the other hand, another example of a flashProtocol that Etcher does supports would be RPIBOOT which is a flash protocol utilized by balena Fin.

defaultBoot

Defines the medium from which the device boots at runtime.

If the defaultBoot is internal and there is an alternative boot method like sdcard and no flashProtocol defined, then we know this is an installation where we need to flash to the sdcard with etcher and that sd card will have a flasher image to write to the internal storage

    "media": {
      "defaultBoot": "internal",
      "altBoot": ["sdcard"]
    },

If the defaultBoot is something not internal and there is no flashProtocol then we know the device will need to boot off of an external media in which we flash BalenaOS onto directly like a raspberry pi might have this definition:

    "media": {
      "defaultBoot": "sdcard",
      "altBoot": []
    },

There are other defaultBoot implementations as well that are available.

altBoot

altBoot describes the list of external mediums from which the device can be provisioned, if any of them are available for the DT.

Contribute

• Issue Tracker: github.com/balena-io/contracts/issues
• Source Code: github.com/balena-io/contracts

Dependencies

• Node.js

You can perform a set of static analysis checks to find the most common types of errors by running:

npm test

License

The project is licensed under the Apache 2.0 license.

contracts's Issues

Multicontainer getting started not working on iot-gate-imx8 device type

Te tag 10-stretch-run used by https://github.com/balena-io-examples/multicontainer-getting-started isn't available for the iot-gate-imx8 device type, the only ones available seem are:

https://hub.docker.com/r/balenalib/iot-gate-imx8-debian-node/tags?page=1&ordering=last_updated&name=1-stretch-run

[Success]   Successfully pulled cache images
[frontend]  Step 1/11 : FROM balenalib/iot-gate-imx8-debian-node:10-stretch-run
[proxy]     Step 1/2 : FROM arm64v8/haproxy:1-alpine
[data]      Step 1/6 : FROM balenalib/iot-gate-imx8-debian-node:10-stretch-run
[frontend]  manifest for balenalib/iot-gate-imx8-debian-node:10-stretch-run not found: manifest unknown: manifest unknown
[data]      manifest for balenalib/iot-gate-imx8-debian-node:10-stretch-run not found: manifest unknown: manifest unknown

Missing contract for Aetina N310 TX2 (n310-tx2)

This results in https://github.com/balena-io/balena-api/issues/3063, leading to a broken logo link on the balena.io webpage for this device.

sw.l4t contract and hw.soc

Hi,

Are these contracts also used in the Balena supervisor? I don't see the sw.l4t container contract for example.

If so, can a contract be added hw.soc? This is for the Jetson family devices to define t210,t186, ...

Try https://jsonnet.org to model contracts

Lint contracts against JSON Schemas for each type

So we make sure we don't accidentally add inconsistencies

Manifest not found for TX2 NX

When trying to build muiticontainer-getting-started app for the Jetson TX2 NX we observe:

Step 1/11 : FROM balenalib/jetson-tx2-nx-devkit-debian-node:10-stretch-run
manifest for balenalib/jetson-tx2-nx-devkit-debian-node:10-stretch-run not found: manifest unknown: manifest unknown

Add tags to base contract

Reference: https://github.com/resin-io/hq/pull/1002/files#diff-d4227a76b0ebcbf792402b8b48b4f7adR99

Switch all contracts to YAML

Add Go v1.17 contract

See https://go.dev/blog/go1.17

Add contracts for blueprints

These blueprints should be modelled as contracts in this repo

Manifest not found for RPI Zero 2 Wireless

[Error] Some services failed to build:
[Error] Service: main
[Error] Error: manifest for balenalib/raspberrypi0-2w-64-debian:stretch-run not found: manifest unknown: manifest unknown
[Info] Built on arm06
[Error] Not deploying release.

balenalabs/x11-window-manager cannot be built for now, most likely base image build not completed.
Should be closed when the build becomes available

New partial combination

Can we do something like:

sw.os+arch.sw/<os>@<version>+<arch>|<arch1>/download.tpl (Apply for combinations: os@version+arch and os@version+arch1)
sw.os+arch.sw/<os>@<version>+<arch>@<version>|<arch1>/download.tpl (Apply for combinations: os@version+arch@version and os@version+arch1)
sw.os+arch.sw/<os>@<version>+<arch>@<version>|<arch1>@<version1>/download.tpl (Apply for combinations: os@version+arch@version and os@version+arch1@version1)

That would be great if we can specify multiple arch since I only put 2 archs in this example.

add links to source repos on github in dockerhub templates

This specifically concerns the .tpl files in /contracts/balenalib/dockerhub/