Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend Offline Updates documentation for low bandwidth networks #1589

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Extend Offline Updates documentation for low bandwidth networks #1589

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 32 additions & 24 deletions pages/learn/deploy/offline-updates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ Offline update includes the following steps:
- [Configure balenaOS image](#configure-balenaos-image)
- [Create and preload release](#create-and-preload-release)
- [Create update media](#create-update-media)
- [Process of reprovisioning](#process-of-reprovisioning)
- [Update device registration(s)](#update-device-registrations)
- [Process of reprovisioning](#process-of-reprovisioning)

The process needs some prerequiste knowledge of the balena ecosystem, [balena-cli][balena-cli] commands and shell commands. Please read all instructions carefully and make sure to try the update process first on a test device.

Expand Down Expand Up @@ -174,7 +174,7 @@ $ commit=$(balena app ${app_slug} | grep COMMIT | awk '{print $2}')
$ balena preload ${tmpimg} \
--app ${app_slug} \
--commit ${commit} \
--pin-device-to-release
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we do this for a device that has partial connectivity, then the remote device will start updating at the moment we run this command.

--no-pin-device-to-release
Copy link
Member Author

@thgreasi thgreasi Feb 12, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need a single line CLI PR for this to add allowNo: true.
See: https://oclif.io/docs/flags

```

### Create Update Media
Expand All @@ -194,33 +194,25 @@ $ sudo balena local flash ${tmpimg} \
$ rm ${tmpimg}
```

### Process of Reprovisioning

> Warning: For devices with internal storage, this procedure erases the internal media of your device. Hence, remove any mass storage devices containing user data.

With the update media ready having the latest release of the application preloaded. Follow the device's provisioning instructions present on balenaCloud dashboard for your specific device.

For example: For Raspberry Pi devices, insert the recently flashed SD card and power up the device. When the process is complete, (re)connect any mass storage devices containing user data back to the device. Reconnect the device to the local air-gapped network(s). Later, use SSH to connect and inspect application logs, etc.

#### Strategies to remotely update with an SD card or USB device

If a device isn't locally deployed, one can ship the flashed SD cards or USB sticks/drives to a remote location. There someone can run the update by simply inserting them into the devices and booting.

If the target device exists on an air-gapped or Internet restricted network, [inserting ssh keys][insert-ssh-key] during the configuration step will allow fleet managers at the remote site to connect into the device directly via OpenSSH and verify the update by examining container logs, etc.

If the target device is connected via a low-bandwidth connection, it should eventually establish a connection to balenaCloud. Depending on the connection's quality, it may respond to [web terminal][web-terminal] commands and output container logs to the dashboard.

### Update Device Registration(s)

This section deals with device registration in the cloud (balenaCloud or openBalena). The following steps help in manually reflecting the new state of the device for offline devices or devices on private networks without Internet access.
This section deals with device registration in the cloud (balenaCloud or openBalena). The following steps help in
* manually reflecting the new state of the device for offline devices or devices on private networks without Internet access
* prevent devices with restricted or low bandwidth connectivity from trying to download newer releases.

#### Patch State Endpoint - Update Device State in the Cloud

This step updates the device state in the cloud (balenaCloud or openBalena)
on behalf of the device, as if the device was online. It is only required for
devices that do not have an internet connection. If the device has an internet
connection, even if low bandwidth, this step may be skipped because the device
itself will be able to contact the cloud to update its state.
on behalf of the device, as if the had just installed the new release. It is
optional for devices that do not have an internet connection, but mandatory if
the device has a unreliable/limited connectivity or low bandwidth internet
connection.

In such unreliable or limited bandwidth connection situations, you will need to
run the commands of this step after you have powered off the device. This step
will pin the device to the release that was preloaded to the image, to ensure
that the device doesn't attempt to download a newer release over an unreliable
or limited bandwidth connection.

```bash
$ os_version_tag=$(echo ${os_version} | awk -F'+' '{print $1}')
Expand All @@ -244,7 +236,7 @@ $ curl --silent \
-X 'PATCH' "https://api.${BALENARC_BALENA_URL}/v6/device(uuid='${uuid}')" \
-H "Authorization: Bearer $(cat ~/.balena/token)" \
-H 'Content-type: application/json' \
--data-binary "{\"os_variant\":\"${os_variant}\",\"os_version\":\"balenaOS ${os_version_semver}+${os_revision}\",\"supervisor_version\":\"${supervisor_version}\",\"is_running__release\":${release_id}}"
--data-binary "{\"os_variant\":\"${os_variant}\",\"os_version\":\"balenaOS ${os_version_semver}+${os_revision}\",\"supervisor_version\":\"${supervisor_version}\",\"is_running__release\":${release_id},\"should_be_running__release\":${release_id}}"
```

#### [Optional] Set Tags on Devices
Expand All @@ -259,6 +251,22 @@ $ balena tag set 'offline:hostOS' "${os_version}" \
--device ${uuid}
```

### Process of Reprovisioning

> Warning: For devices with internal storage, this procedure erases the internal media of your device. Hence, remove any mass storage devices containing user data.

With the update media ready having the latest release of the application preloaded. Follow the device's provisioning instructions present on balenaCloud dashboard for your specific device.

For example: For Raspberry Pi devices, insert the recently flashed SD card and power up the device. When the process is complete, (re)connect any mass storage devices containing user data back to the device. Reconnect the device to the local air-gapped network(s). Later, use SSH to connect and inspect application logs, etc.

#### Strategies to remotely update with an SD card or USB device

If a device isn't locally deployed, one can ship the flashed SD cards or USB sticks/drives to a remote location.

If the target device exists on an air-gapped or Internet restricted network, [inserting ssh keys][insert-ssh-key] during the configuration step will allow fleet managers at the remote site to connect into the device directly via OpenSSH and verify the update by examining container logs, etc. In such cases someone can run the update by simply inserting them into the devices and booting.

If the target device is connected via a low-bandwidth connection, it should eventually establish a connection to balenaCloud. Depending on the connection's quality, it may respond to [web terminal][web-terminal] commands and output container logs to the dashboard.

Read more about how the process can work better for your usecase in the [offline updates](https://balena.io/blog/offline-updates-make-it-easier-to-update-balena-devices-without-the-internet) blog.

[named-volumes]: /learn/develop/multicontainer/#named-volumes
Expand Down