Skip to content

Latest commit

 

History

History
123 lines (81 loc) · 7.54 KB

README.md

File metadata and controls

123 lines (81 loc) · 7.54 KB
Raw

balenaHUP

Tool for balena host OS updates. It downloads an update bundle that replaces the balenaOS for a balena device, updating both the boot partition and the rootfs (using an inactive rootfs partition).

Be aware that in the current stage of development this tool is not meant to be ran by itself but through a wrapper developed in meta-balena. This wrapper takes care of all the prerequisites needed for this tool and adds support for balena Supervisor updates as well. In this way, using that wrapper, a device can be updated completely (balenaOS + Supervisor).

The current development stage uses docker images/containers to deploy and run this tool. This is because when we first developed this tool the balenaOS was not providing all the python prerequisites needed for it to successfully work. The long term plan would be to bring it completely in the balenaOS including all the prerequisites. This is not completely decided because balenaOS has hard requirements on rootfs size and we try to keep it as small as possible. So this docker container solution is kept for now even though it adds the overhead of downloading an image before being able to run the updater.

Docker containers versus git repository

The releases for balenaHUP are marked in this git repository as git tags. As well the git repository includes Dockerfiles for each balenaHUP supported resin board. For example there is a Dockerfile called Dockerfile.raspberrypi3 which is the Dockerfile for creating a balenaHUP docker image for Raspberry Pi 3 boards. We currently upload our balenaHUP docker images to resin registry (registry.resinstaging.io). We do this because old resin devices were using docker 1.4 which can't pull from registry v2 dockerhub.

For each balenaHUP release (tag) there will be a set of docker images with the same tag uploaded to the above mentioned registry. The images have the name format: balenaHUP-<board-slug>. The full docker images URL format becomes registry.resinstaging.io/balenaHUP/balenaHUP-<board slug> .

Example. For release 1.0 (git tag 1.0), balenaHUP supports the following device slugs: beaglebone-black, intel-nuc, raspberry-pi, raspberry-pi2 and raspberrypi3. For each slug there is a corresponding Dockerfile: Dockerfile.beaglebone-black, Dockerfile.intel-nuc, Dockerfile.raspberry-pi, Dockerfile.raspberry-pi2 and Dockerfile.raspberrypi3. For each Dockerfile there are docker image pushed to the registry:

registry.resinstaging.io/resinhup/resinhup-raspberrypi3       1.0  c324b00459f3        2 days ago          241.4 MB
registry.resinstaging.io/resinhup/resinhup-raspberry-pi2      1.0  4ca1d77c1457        2 days ago          174.3 MB
registry.resinstaging.io/resinhup/resinhup-raspberry-pi       1.0  4ca1d77c1457        2 days ago          174.3 MB
registry.resinstaging.io/resinhup/resinhup-intel-nuc          1.0  63cc85875b84        2 days ago          225.3 MB
registry.resinstaging.io/resinhup/resinhup-beaglebone-black   1.0  7553637ea826        2 days ago          258.3 MB

The images taged as latest are following the HEAD of master branch.

Hint: there is a script helper called docker-build-and-push.sh for pushing images to registry. Check its help.

How to use

Use run-resinhup.sh wrapper developed in meta-balena. Check run-resinhup.sh help message for all the configuration you can use. Make sure the run-resinhup.sh along with update-resin-supervisor and resin-device-progress scripts are updated.

Pro Hint: In order to make sure these scripts are updated and able to run balenaHUP on multiple devices (batch/fleet updates), admins can use a wrapper on top of run-resinhup.sh called run-resinhup-ssh.sh. This wrapper is not intended for public use as it requires SSH access to the devices over VPN along with admin permissions for API queries. Check run-resinhup-ssh.sh help message for all the configurations you can use.

BalenaHUP architecture for 1.x->1.x updates

Currently there are 3 components involved in updating a device:

  • balenaHUP (docker images)
  • run-resinhup.sh (bash wrapper)
  • run-resinhup-ssh.sh (bash wrapper)

balenaHUP

This component is distributed from this repository as docker images (explained above). The overall workflow of the tool is: Minion

run-resinhup.sh

This is a wrapper which pulls the proper balenaHUP image and runs the updater:

  • takes care of all the prerequisites
  • adds support for supervisor update
  • pulls balenaHUP image
  • runs balenaHUP container
  • if updater is successful, reboots the board

This script is found in balena-os/meta-balena, 1.x branch/.

run-resinhup-ssh.sh

This is a tool which:

  • Uploads over ssh all the needed tools from meta-balena (update-resin-supervisor, run-resinhup.sh and resin-device-progress).
  • Runs run-resinhup.sh over a set of devices and saves the log in a file called <uuid>.resinhup.log
  • Can run the updater over multiple devices in parallel.

It requires SSH access over VPN to devices.

This script is found in balena-os/meta-balena, 1.x branch/.

balenaHUP architecture for 1.x->2.x and 2.x->2.x updates

Currently there are 2 components involved in updating a device for these versions

  • upgrade-<...>.sh (bash wrapper)
  • upgrade-ssh-<...>.sh (bash wrapper)

upgrade-<...>.sh

The upgrade-1.x-to-2.x.sh and upgrade-2.x.sh are wrappers that which pulls the proper host OS image and runs the updater:

  • takes care of all the prerequisites
  • adds support for supervisor update
  • if updater is successful, reboots the board (default, but adjustable over command line parameters)

Run them with the --help flag to see all the options

upgrade-ssh-<...>.sh

The upgrade-ssh-1.x-to-2.x.sh and upgrade-ssh-2.x.sh scripts are wrappers which:

  • Runs run-resinhup.sh over a set of devices.
  • Can run the updater over multiple devices in parallel.

It requires SSH access over VPN to devices, which is enabled for general users for balenaOS version 2.7.5 and above.

Set up your device connection settings in your SSH config by adding a record like this:

Host resindevice
  User <username>
  Hostname ssh.resindevice.io
  LogLevel ERROR
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null
  ControlMaster no
  IdentityFile <path-to-identity-file>

The User and IdentityFile sections are optional, and depend on your SSH setup. The name resindevice is arbitrary, and you can use any other value (unique within the config). That will be the name that you need to use with the -s command line flag.

For for staging use Hostname ssh.devices.resinstaging.io.

Development

Want to contribute? Great! Throw pull requests at us.

TODOs

  • Safety checks for "to be updated" partition (size, existent fs etc.)
  • Use the boot file from a directory in the rootfs update partition called "/assets"
  • Add support for other resin supported targets

Version

See balenahupmeta.py.

License

See balenahupmeta.py.