Add an orchestrator example using a deployment to distribute manifest.

Ticket: MEN-7016

Signed-off-by: Kristian Amlie <[email protected]>

09.Add-ons/05.Orchestrator/02.Examples/docs.md

@@ -20,6 +20,8 @@ REQUIREMENTS:
 ```bash
 mkdir orch-install
 ORCH_EVAL_DIR=$(realpath orch-install)
+mkdir -p $ORCH_EVAL_DIR/bin
+PATH=$PATH:$ORCH_EVAL_DIR/bin
 ```
 
 Clone the repository which contains the support files and the demo:
@@ -36,6 +38,24 @@ cp -r mender-orchestrator-update-interfaces/interfaces/v1/rootfs-image  \
       $ORCH_EVAL_DIR/share/mender-update-orchestrator/update-interfaces/v1
 ```
 
+Copy the update module and the inventory script:
+
+```bash
+mkdir -p $ORCH_EVAL_DIR/share/mender/modules/v3
+cp mender-orchestrator-update-interfaces/modules/mender-orchestrator-manifest/module/v3/mender-orchestrator-manifest \
+      $ORCH_EVAL_DIR/share/mender/modules/v3
+mkdir -p $ORCH_EVAL_DIR/share/mender/inventory
+cp mender-orchestrator-update-interfaces/inventory/mender-inventory-mender-orchestrator \
+      $ORCH_EVAL_DIR/share/mender/inventory
+```
+
+Install the manifest artifact generator for the host:
+
+```bash
+cp mender-orchestrator-update-interfaces/modules/mender-orchestrator-manifest/module-artifact-gen/mender-orchestrator-manifest-gen \
+      $ORCH_EVAL_DIR/bin
+```
+
 
 ## Preparing the QEMU host
 
@@ -268,13 +288,27 @@ mender-artifact write rootfs-image -f ssh://${USER}@${CONTAINER_IP} \
                                    --ssh-args '-o StrictHostKeyChecking=no'
 ```
 
+``` bash
+USER="root"
+DEVICE_TYPE="qemux86-64"
+TYPE="rootfs-image"
+mender-artifact write rootfs-image -f ssh://${USER}@${CONTAINER_IP} \
+                                   -n gateway-v5 \
+                                   -o gateway-v5.mender \
+                                   -t $DEVICE_TYPE \
+                                   --ssh-args '-p 8822' \
+                                   --ssh-args '-o UserKnownHostsFile=/dev/null' \
+                                   --ssh-args '-o StrictHostKeyChecking=no'
+```
+
 ```bash
 # This is the path on the device where we deliver the created artifact
 MOCK_DIR=/data/mender-update-orchestrator/mock_env
 scp -P 8822 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no gateway-v3.mender ${USER}@${CONTAINER_IP}:${MOCK_DIR}/system-core-v3/gateway-v3.mender
 ```
 
-Upload the `gateway-v4.mender` to Hosted Mender to the tenant the device is accepted on.
+Upload the `gateway-v4.mender` and `gateway-v5.mender` artifacts to Hosted Mender to the tenant the
+device is accepted on.
 
 
 ### Example: Standard system update - real gateway - offline
@@ -320,3 +354,71 @@ MOCK_DIR=/data/mender-update-orchestrator/mock_env
 mender-update-orchestrator resume
 mender-update-orchestrator show-provides
 ```
+
+
+### Example: Standard system update - real gateway - managed by Hosted Mender
+
+In this example we will perform the same update as in the previous example, but we will do so using
+a Hosted Mender deployment instead of installing the manifest using the command line. This makes use
+of the `mender-orchestrator-manifest` update module that we installed earlier.
+
+This works just like a regular Mender deployment, including rolling back automatically if a failure
+is detected.
+
+#### Prepare the deployment
+
+Let's introduce a failure to see this in action. On the **device**, execute this:
+
+```bash
+MOCK_DIR=/data/mender-update-orchestrator/mock_env
+touch $MOCK_DIR/mock_instances/R456/ArtifactCommit.FAIL
+```
+
+We need to create a special artifact containing the new manifest we want to install. For this we use
+the `mender-orchestrator-manifest-gen` tool. On the **host**, execute this:
+
+```bash
+DEVICE_TYPE="qemux86-64"
+mender-orchestrator-manifest-gen \
+    -n manifest-v5 \
+    -o manifest-v5.mender \
+    -t $DEVICE_TYPE \
+    $ORCH_EVAL_DIR/mock_env/system-core-v5/manifest.yaml
+```
+
+Upload the resulting `manifest-v5.mender` artifact to Hosted Mender.
+
+We also need to upload the `rtos-v5.mender` artifact for the mock device, in addition to the
+`gateway-v5.mender` artifact which we already uploaded above when creating the rootfs artifacts. Go
+ahead and upload the artifact which you can find at this path:
+`orch-install/mock_env/system-core-v5/rtos-v5.mender`.
+
+#### Launch the deployment
+
+While logged into Hosted Mender in your browser, click on the "Releases" tab and select the
+`manifest-v5` release from the list. Then select "Create a deployment from this release" from the
+"Release actions" menu, select "All devices" from the device group list, and click "Create
+deployment" to start the deployment.
+
+!!! Make sure the `gateway-v5` release is also present in the list, which we uploaded when preparing
+!!! the rootfs artifacts above.
+
+After a little while, the deployment should finish with the failed status, because of the failure we
+introduced above. View it under the "Finished" tab. Go ahead and take a look at the failure log by
+clicking "View details", and then "View log" while inside the failed deployment popout. Note in
+particular that it was not the rootfs update of the gateway that failed, but the rtos component
+which was updated after it, yet it caused both to be rolled back.
+
+Let's remove the failure and retry the deployment. On the **device**, execute this:
+
+```bash
+MOCK_DIR=/data/mender-update-orchestrator/mock_env
+rm -f $MOCK_DIR/mock_instances/R456/ArtifactCommit.FAIL
+```
+
+Then repeat the steps to start the deployment, and wait for it to finish. It should finish with
+success this time.
+
+Take a look at the updated inventory for the device by clicking the "Devices" tab in the UI, then
+click on the device. Then click on "Software" and "Inventory" tabs to view the installed software
+and the rest of the inventory, respectively.