Pantavisor 019 Features: Restart Policy

Tutorials
,
1

Pantavisor Update

In this post, we are going to talk about how to make use of our container restart policy feature included in the Pantavisor 019 release.

Firstly, we need to understand how Pantavisor manages updates. Specifically, how the transition to a new update is made after being installed (both remotely and locally) and validated.

Pantavisor will compare the currently running revision and the upcoming one. This means comparing all the artifacts (objects and JSON files) that are associated to those revisions. Depending on the artifacts that are added, deleted or modified, a reboot or non-reboot transition will be performed. Affected artifacts associated to the BSP will always trigger a reboot, while artifacts belonging to containers will depend on its restart policy. If the difference between the old and the new revisions contain artifacts coming from components with mixed policies, reboot transition will win.

There are currently two supported restart policies:

  • system: any update that modifies any object or JSON belonging to at least one of the containers with system restart policy will result in a reboot transition.
  • container: any update that only modifies objects or JSONs belonging to containers with the container restart policy will result in a non-reboot transition.
2

Setting a Restart Policy to a Container

As an example, we are going to add a Home Assistant container to an existing Pantavisor-enabled device claimed from my Pantacor Hub account:

device
device1544×380 56.2 KB

First step will be to clone our device as usual, in this case, a Raspberry Pi 4 board with the Pantavisor 019 image installed:

pvr clone https://pvr.pantahub.com/anibal/home_rpi64_latest
cd home_rpi64_latest

To add the container with system restart policy, we have to explicitly set it in the pvr app add command:

pvr app add --from homeassistant/raspberrypi3-homeassistant --restart-policy system homeassistant
pvr add .
pvr commit
pvr post -m "add a new homeassistant container with system restart policy"

The added container with system restart policy will trigger a full board reboot after we post the changes. A DONE status indicate the new update has been fully validated after a reboot and set as a checkpoint for potential rollbacks in the future:

done
done1544×233 37.2 KB

If we prefer to only restart the container and perform a non-reboot transition, we can set the new container with the container restart policy:

rm -r homeassistant
pvr app add --from homeassistant/raspberrypi3-homeassistant --restart-policy container homeassistant
pvr add .
pvr commit
pvr post -m "add a new homeassistant container with container restart policy"

Posting this will make Pantavisor transition to the new revision without rebooting. Notice the UPDATED status which means that the revision was correctly transitioned to, but not set as a checkpoint for rollbacks:

updated
updated1538×230 36.7 KB

Any further update that affects any of the artifacts associated with the homeassistant container will be transitioned to according to its restart policy.

3

Modifying the Restart Policy of a Container

Let us get back to our previous example and go to the cloned checkout of our device:

cd home_rpi64_latest
ls

In there, we will find the container homeassistant that we just installed with pvr. Inside the homeassistant container, we will find the src.json and the run.json files. The first one will be used by pvr, while the second one will be parsed by Pantavisor itself. Let us first take a look at the configured restart policy in the run.json first:

$ jq .restart_policy homeassistant/run.json 
"container"

As we can see, pvr app add has set that restart_policy from the one we last set with the --restart-policy option. If we want to change that without having to reinstall the container, we have to do it in the src.json, as run.json is not meant to be directly edited:

$ jq .args.PV_RESTART_POLICY homeassistant/src.json 
"container"

And manually edit it to look like this:

$ jq .args.PV_RESTART_POLICY homeassistant/src.json 
"system"

Now, if we use the pvr app install command:

pvr app install homeassistant

The pvr tool will take the value from the src.json file and apply it at the run.json:

$ jq .restart_policy homeassistant/run.json 
"system"

Now, again, you can commit and post the changes to start using them in your device:

pvr add .
pvr commit
pvr post -m "change homeassistant restart policy to system"