Mender Hub - Mender Binary Delta.diff

Mender Hub - Mender Binary Delta.diff

--- "Mender Hub - Mender Binary Delta - orig.md"	2020-04-20 14:10:32.774369664 +0200
+++ "Mender Hub - Mender Binary Delta.md"	2020-04-21 11:20:47.557365686 +0200
@@ -123,7 +123,7 @@
 
 **NOTE!** The trailing `:` in `FILESEXTRAPATHS_prepend_pn-mender-binary-delta` is intentional and important to have in place.
 
-## Generating images, artifacts and deltas
+## Preparing images and artifacts
 
 For the purpose of this tutorial you can set the `MENDER_ARTIFACT_NAME` to the following:
 
@@ -200,16 +200,20 @@
 mender-binary-delta  mender-binary-delta-generator  release-v.1.0.mender  release-v.2.0.mender
 ```
 
+## Generating delta Artifacts
+
+This tutorial assumes that Mender Enterprise is being used. If not, then dependencies need to be tracked manually, which is not recommended. See the [troubleshooting](#troubleshooting) section for ways to deal with this.
+
 Generate delta for `v1.0 -> v2.0` update path:
 
 ```
-./mender-binary-delta-generator -n v2.0-deltafrom-v1.0 -o v2.0-deltafrom-v1.0.mender release-v.1.0.mender release-v.2.0.mender
+./mender-binary-delta-generator -o v2.0-deltafrom-v1.0.mender release-v.1.0.mender release-v.2.0.mender
 ```
 
 Generate delta for `v2.0 -> v1.0` update path:
 
 ```
-./mender-binary-delta-generator -n v1.0-deltafrom-v2.0 -o v1.0-deltafrom-v2.0.mender release-v.2.0.mender release-v.1.0.mender
+./mender-binary-delta-generator -o v1.0-deltafrom-v2.0.mender release-v.2.0.mender release-v.1.0.mender
 ```
 
 ## Using the delta Mender Artifacts
@@ -221,13 +225,34 @@
 - v1.0-deltafrom-v2.0.mender (mender-binary-delta)
 - v2.0-deltafrom-v1.0.mender (mender-binary-delta)
 
+After having uploaded these four Artifacts, you should have two Releases in the Mender UI. This is because the rootfs-image Artifact and the corresponding mender-binary-delta Artifact are referring to the same software.
+
 If you have followed this tutorial your provisioned device should be running `release-v1.0` which was provisioned using a disk image (e.g `sdimg`).
 
-### First deploy a full image update (Yocto Project thud or older)
+### Deploy delta updates
+Start off with deploying `release-v.2.0.mender` to the device, and once that is completed you can deploy `release-v.1.0.mender`. Note that at this point there is no distinction between deploying a full rootfs-image Artifact and a mender-binary-delta Artifact. Mender keeps track of dependencies automatically and selects the correct one. More formally, it selects the smallest Artifact which satisfies the dependencies, but will select the bigger rootfs-image Artifact if the device has an unknown delta base.
+
+Note that the very first update after provisioning a device is always a `rootfs-image` update. This is needed because the checksum is not tracked when using a `sdimg` file, only when using a `mender` file. This is only needed **once** after you have provisioned a device, and after the first deployment is done, delta Artifacts will be used if they are available. This requirement may be lifted in the future, see [this ticket](https://tracker.mender.io/browse/MEN-2834) for more information.
 
-If you are using Yocto Project **warrior (2.7) or newer** you can skip this section, as it is not required.
+If you want to verify that the mender-binary-delta Artifact is indeed being used, delete the rootfs-image from the one of the Releases in the UI, and then deploy that release.
 
-If you are using Yocto Project version **thud (2.6) or older**, you must deploy a `rootfs-image` update **once** after you have provisioned your device, e.g using the disk image (`sdimg`). This is needed because the checksum of the file system image is not the same in an `sdimg` and in a `mender` file, even if they are generated during the same build. And because we generated the delta Artifacts from the `mender` files, we must deploy one of these first before we can proceed in deploying deltas. As mentioned this is only needed **once** after you have provisioned a device, after that is done you can use delta Artifacts. This requirement may be lifted in the future, see [this ticket](https://tracker.mender.io/browse/MEN-2834) for more information.
 
-### Deploy delta updates
-Start of with deploying `release-v.2.0.mender` to the device, and once that is completed you can deploy `v1.0-deltafrom-v2.0.mender` and after one is completed you can deploy `v2.0-deltafrom-v1.0.mender`.
+## Troubleshooting
+
+### Error message: `Artifact dependency "rootfs_image_checksum" not satisfied by currently installed artifact`
+
+This message will usually only be reported if you are not using Mender Enterprise, and is usually because of one of these reasons:
+
+* You are using a non-Enterprise version of Mender, and there are several mender-binary-delta and/or rootfs-image Artifacts with the same name (grouped under the same Release in the UI). In non-Enterprise versions of Mender, there is no automatic dependency tracking, so each Artifact needs to have a different name, even if the only difference between two Artifacts is the delta base.
+
+* You are trying to deploy a mender-binary-delta Artifact onto a device which does not have the delta base checksum that the Artifact was made for. If this is the case, you need to make a new mender-binary-delta Artifact based on the Artifact which is currently installed on the device, and install that instead.
+
+* It can also be an indication that [the very first rootfs-image Artifact](#first-deploy-a-full-image-update) has not been deployed yet. If so, you need to install a rootfs-image Artifact to the device first, and make sure that the next mender-binary-delta Artifact uses this Artifact as a base. This only needs to be done once for each device. This requirement may be lifted in the future, see [this ticket](https://tracker.mender.io/browse/MEN-2834) for more information.
+
+### Deployment finishes with "No artifact" without updating the device
+
+This can happen if a Release only has mender-binary-delta Artifacts uploaded, and none of them match the delta base on the device. If so, you need to do one of these things:
+
+* Upload a mender-binary-delta Artifact using the currently installed Artifact of the device as a base.
+
+* Upload a rootfs-image Artifact, which will always match, but will also use more bandwidth than a mender-binary-delta Artifact.

@estenberg, @mirzak: This is my proposed edit to Mender Hub to document the new mender-binary-delta behavior.

Notice that in the Enterprise section, I don't mention that the first update will always be a rootfs-image. I'm torn on whether we should mention this. It is still required, but due to the automatic nature of delta updates in Enterprise, it will just happen automatically. So the only concern is potentially bandwidth. This only happens once, so maybe we should save the cognitive overhead?

I would actually remove the "without Enterprise" thread in this docs, rather just note that dependencies need to be tracked manually if not using Mender Enterprise. The main reasons are that 1) I think most people will use Enterprise for this, at least in production and 2) we will hopefully soon have an eval environment that includes all Enterprise features.

And I would include that a full image update is needed once first. Otherwise people might see that Mender does this and think they have done something wrong. This sentence explains it for Enterprise, just need some minor tweaks I think (to say this will happen automatically): "You must deploy a rootfs-image update once after you have provisioned your device, e.g using the disk image (sdimg). This is needed because the checksum is not tracked when using a sdimg file, only when using a mender file. As mentioned this is only needed once after you have provisioned a device, after that is done you can use delta Artifacts. This requirement may be lifted in the future, see this ticket for more information."

@estenberg: Alright, updated!

Looks good!