How-to: balena delta image preloading

gistfile1.md

1. Trigger an update with deltas enabled between release A and release B on a test device.
2. Find the delta image that gets pulled from balena images -- it should be REGISTRY_URL:DELTA_TAG
   • Alternatively, if running Supervisor v12.9.5 or greater (12.9.6 highly recommended), look in the Supervisor's journal logs.
   • Alternatively, make a request the delta endpoint with curl -H "Bearer: Authorization $(cat /mnt/boot/config.json | jq -r '.deviceApiKey)" "https://delta.balena-cloud.com/api/v3/delta?src=SOURCE_REGISTRY_URL&dest=TARGET_REGISTRY_URL". This should return the delta URL and is the best amongst these 3 alternatives, but from my own investigations and limited knowledge, this works sporadically so is not recommended.
3. After you have the registry delta URL, on production devices:
   • balena login registry2.balena-cloud.com -u d_$(cat /mnt/boot/config.json | jq -r '.uuid') -p $(cat /mnt/boot/config.json | jq -r '.deviceApiKey')
   • balena pull DELTA_URL
   • balena image tag DELTA_URL_ID YOUR_CUSTOM_TAG // Optional step but this will prevent your pulled image from being removed until you explicitly remove it with balena rmi
4. When you want to trigger an update, pin all devices that have already pulled the delta to your target release. The Supervisor will see the delta and not download anything.

This may be usable for rollbacks, theoretically with the following workflow:

1. Trigger an update on a test device from release B to release A on a test device. This is assuming B -> A is the rollback path.
2. Before updating from release A to release B, pull the delta from B -> A using the method listed above, if it's not already on the device.
3. Label the delta image something to keep a reference to it on the device.
4. After updating, if you want to rollback, label this delta image the REGISTRY_URL:DELTA_TAG you observed previously, then trigger the rollback via pinning. The Supervisor will see that the rollback delta image is on the device, and rollback without network.

CAVEATS:

• Host OS version >= 2.47 (HUP-ing to 2.77 so assuming this will not be a problem)
• Manually tagged images will theoretically remain forever on the device, make sure to cleanup unneeded custom tags between updates.
• Requires automation
• This is not a public method (namely, querying the delta server and performing a manual pull with balena-engine) and we are only providing this to unblock you, since your request of durable locks on the device is not a high priority or not in consideration at this time. This method may be adapted to replace your current method of update locks, which are not meant to be used in that way and are also not persistent, as you've found out.

I'll continue looking into the delta API method since it's the most ideal.

cywang117 - Christina
20k-ultra - Miguel