balena-supervisor/docs/dependent-apps.md

Using the balena Supervisor to manage dependent applications

Since version 2.5.0 the balena Supervisor can act as a proxy for dependent apps.

Only Supervisors after version 2.5.0 have this functionality, and some of the endpoints appeared in later versions (we've noted it down where this is the case).

What is a dependent application

A dependent application is a balena application that targets devices not capable of interacting directly with the balena API - the reasons can be several, the most common are:

• no direct Internet capabilities
• not able to run balenaOS (being a microcontroller, for example)

The dependent application is scoped under a balena application, which gets the definition of gateway application.

The gateway application is responsible for detecting, provisioning and managing dependent devices belonging to one of its dependent applications. This is possible leveraging a new set of endpoints exposed by the balena Supervisor.

When a new version of the dependent application is git pushed, the supervisor will download the docker image and expose the assets in one of the endpoints detailed below. It is then the gateway application (i.e. the user app that is run by the supervisor) that is responsible for ensuring those assets get deployed to the dependent devices, using the provided endpoints to perform the management.

A dependent application follows the same development cycle of a conventional balena application:

• it binds to your git workspace via the balena remote
• it consists in a Docker application
• it offers the same environment and configuration variables management

There are some differences:

• it does not support Dockerfile templating
• the Dockerfile must target either an x86 or amd64 base image
• the actual firmware/business logic must be stored in the /assets folder within the built docker image.
  • You can either just COPY a pre-built artifact in that folder, or build your artifact at push time and then store it in the /assets folder.
• a dependent application Docker image is only used to build, package and deliver the firmware on the dependent device via balena-supervisor - it won't be run at any point.

How a dependent application works

Endpoints

The supervisor exposes a REST API to interact with the dependent applications and dependent devices models that come from the balena API - it also allows using a set of hooks to have push functionality, both documented below.

HTTP API reference

Applications

GET /v1/dependent-apps

Dependent Applications List

Example

curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/dependent-apps?apikey=$BALENA_SUPERVISOR_API_KEY

Response HTTP/1.1 200 OK

[
     {
         "id": 13015,
         "name": "edgeApp1",
         "commit": "d43bea5e16658e653088ce4b9a91b6606c3c2a0d",
         "config": {}
     },
     {
         "id": 13016,
         "name": "edgeApp2",
         "commit": "d0f6624d6410fa079159fa3ebe0d3af46753d75d",
         "config": {}
     }
 ]

GET /v1/dependent-apps/:appId/assets/:commit

Dependent Application Updates Registry

Example

curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/dependent-apps/<appId>/assets/<commit>?apikey=$BALENA_SUPERVISOR_API_KEY

Response HTTP/1.1 200 OK

[application/x-tar] .tar

Devices

GET /v1/devices

Dependent Devices List

Example

curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/devices?apikey=$BALENA_SUPERVISOR_API_KEY

Response HTTP/1.1 200 OK

[
     {
         "id": 1,
         "uuid": "5ae8cf6e062c033ea38435498ad9b487bcc714e9eab0fed0404ee56e397790",
         "appId": 13015,
         "device_type": "generic-amd64",
         "logs_channel": "69f961abffaad1ff66031b29f712be4fb19e1bfabf1fee7a9ebfb5fa75a1fbdb",
         "deviceId": "47270",
         "is_online": null,
         "name": "blue-sun",
         "status": "Provisioned",
         "download_progress": null,
         "commit": "d43bea5e16658e693088ce4b9a91b6606c3c2a0d",
         "targetCommit": "d43bea5e16653e653088ce4b9a91b6606c3c2a0d",
         "environment":{},
         "targetEnvironment":{},
         "config":{},
         "targetConfig":{"RESIN_SUPERVISOR_DELTA":"1"}
     },
     {
         "id": 3,
         "uuid": "8dc608765fd32665d49d218a7eb4657bc2ab8a56db06d2c57ef7c7e9a115da",
         "appId": 13015,
         "device_type": "generic-amd64",
         "logs_channel": "d0244a90e8cd6e9a1ab410d3d599dea7f15110a6fe37b2a8fd69bb6ee0bce043",
         "deviceId": "47318",
         "is_online": null,
         "name": "wild-paper",
         "status": "Provisioned",
         "download_progress": null,
         "commit": "d43bea5e16658e253088ce4b9a91b6606c3c2a0d",
         "targetCommit": "d43bea5e11658e653088ce4b9a91b6606c3c2a0d",
         "environment":{},
         "targetEnvironment":{},
         "config":{},
         "targetConfig":{"RESIN_SUPERVISOR_DELTA":"1"}
     }
 ]

POST /v1/devices

Dependent Device Provision

The device_type parameter is optional, defaulting to generic-amd64. You should only set this if you need to provision a dependent device to an application with the deprecated edge device type.

Example

curl -H "Content-Type: application/json" -X POST --data '{"appId": <appId>,
"device_type": "edge"}' /
$BALENA_SUPERVISOR_ADDRESS/v1/devices?apikey=$BALENA_SUPERVISOR_API_KEY

Response HTTP/1.1 201 CREATED

{
          "id": 47318,
          "uuid": "8dc608765fd32665d49a268a7eb4657bc2ab8a56db06d2c57ef7c7e9a115da",
          "name": "wild-paper",
          "note": null,
          "device_type": "edge"
    }

GET /v1/devices/:uuid

Dependent Device Information

Example

curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/devices/<uuid>?apikey=$BALENA_SUPERVISOR_API_KEY

Response HTTP/1.1 200 OK

{
           "id": 1,
           "uuid": "5ae8cf6e062c033ea57837498ad9b487bfc714e9eab0fed0404ee56e397790",
           "appId": 13015,
           "device_type": "generic-amd64",
           "logs_channel": "69f961abffaad2ff00031b29f718be4fb19e1bfabf1fee7a9ebfb5fa75a1fbdb",
           "deviceId": "47270",
           "is_online": null,
           "name": "blue-sun",
           "status": "Provisioned",
           "download_progress": null,
           "commit": "d43bea5e16658e623088je4b9a91b6606c3c2a0d",
           "targetCommit": "d43bea5e16658e651088ce4b9a21b6606c3c2a0d",
           "env": null,
           "targetEnv": null
       }

PUT /v1/devices/:uuid

Dependent Device Information Update

Example

curl -H "Content-Type: application/json" -X PUT --data /
'{"is_online":true, "status": "Updating", "commit": "339125a7529cb2c2a8c93a0bbd8af69f2d96286ab4f4552cb5cfe99b0d3ee9"}' /
$BALENA_SUPERVISOR_ADDRESS/v1/devices/<uuid>?apikey=$BALENA_SUPERVISOR_API_KEY

Response HTTP/1.1 200 OK

{
           "id": 1,
           "uuid": "5ae8cf6e062c033ea38437498ad9b482bcc714e9eab0fed0404ee56e397790",
           "appId": 13015,
           "device_type": "generic-amd64",
           "logs_channel": "69f961abffaad2ff66031b29f712be4fb19e1bfabf1fee7a9ebfb5fa05a1fbdb",
           "deviceId": "47270",
           "is_online": true,
           "name": "blue-sun",
           "status": "Updating",
           "download_progress": null,
           "commit": "d43bea5e16658e653088ce4b9a11b6606c3c2a0d",
           "targetCommit": "d43bea5e16658e653088se4b9a91b6606c3c2a0d",
           "env": null,
           "targetEnv": null
       }

POST /v1/devices/:uuid/logs

Dependent Device Log

Example

curl -H "Content-Type: application/json" -X POST --data '{"message":"detected movement","timestamp":1472142960}' /
$BALENA_SUPERVISOR_ADDRESS/v1/devices/<uuid>/logs?apikey=$BALENA_SUPERVISOR_API_KEY

Response HTTP/1.1 202 ACCEPTED

Hooks (the requests the balena Supervisor performs)

Hook configuration

You can point the supervisor where to find the hook server via a configuration variable.

• BALENA_DEPENDENT_DEVICES_HOOK_ADDRESS (defaults to http://0.0.0.0:1337/v1/devices/)

It's worth mentioning (as described below) that the supervisor will append the dependent device uuid (<uuid> in the hook descriptions) to every hook request URL

PUT /v1/devices/:uuid/restart

Dependent Device Restart Notification

Example

curl -H "Content-Type: application/json" -X PUT /
http://127.0.0.1:1337/v1/devices/<uuid>/restart

Response HTTP/1.1 200 OK

PUT /v1/devices/:uuid

Dependent Device Update Notification

Example

curl -H "Content-Type: application/json" -X PUT /
--data '{"commit":" <commit>","environment": "<environment>"}' http://127.0.0.1:1337/v1/devices/<uuid>

Responses

• HTTP/1.1 200 OK Acknowledgement of the notification without further trials: The Supervisor won't repeat the hook request
• HTTP/1.1 202 ACCEPTEDAcknowledgement of the notification with validation: the Supervisor will repeat the hook request until the dependent device information gets updated via Dependent Device Information Update endpoint

DELETE /v1/devices/:uuid

Dependent Device Delete Notification

Example

curl -X DELETE http://127.0.0.1:1337/v1/devices/<uuid>

Response HTTP/1.1 200 OK