Updates¶
Getting back to revisions, these can be modified and upgraded, thus creating a new revision of the device.
Flow¶
Updates will be processed differently depending on the source being remote or local.
Remote¶
The diagram shows a high level concept of how remote updates work. In this case, we have a periodic routine that checks for pending updates upstream and executes the installation and transition to them one by one:
Local¶
In this diagram, you can see how local updates work. In the case of this kind of update, we have a one-shot process triggered by a run revision command:
Progress¶
Pantavisor keeps the update progress information for each revision in storage.
This info will also be reported to the cloud in case of the device being remote and communication available at that moment.
Pantavisor will only progress to the new revision in case of success. Otherwise, no action or rollback will ensue, depending on the point where the error is detected. This is the list of possible update states:
NEW¶
Initial state for remote updates. Set by the cloud side.
SYNCING¶
Device is syncing its first revision with the cloud. Set by the cloud side.
QUEUED¶
Only valid for remote updates.
Pantavisor has got the state JSON of the new revision, but is performing other operations and has put it to the queue to be processed later.
| Messages |
|---|
| Retried X of Y |
DOWNLOADING¶
Only valid for remote updates.
Downloading the artifacts for the new revision.
| Messages |
|---|
| Retry X of Y |
INPROGRESS¶
Installing or progressing to this revision. Transitions to new revisions can either require a reboot or not.
To finish this state, it is necessary that all status goals existing in the new revision have been achieved. Also, in the case of a remote update, Pantavisor needs to have performed communication with Pantacor Hub. If these two conditions are not met within a configurable time, Pantavisor will rollback the revision.
| Messages |
|---|
| Update objects downloaded |
| Update applied |
| Update installed |
| Starting updated version |
| Transitioning to new revision without rebooting |
| Rebooting |
Reboot transition¶
Reboot transitions are performed based on the location of the changes belonging to the new revision update:
- In the root of the status JSON
- In the BSP
- In any of the containers with a system restart policy
- In any additional file that belongs to a container with system restart policy
- In any additional file that does not belong to any container
In this case, Pantavisor will stop all the containers and reboot the board.
Non-reboot transition¶
Non-reboot transitions are performed after an update that does not contain any changes in any of the components described for the reboot updates.
In this case, Pantavisor will only stop the containers that were affected by the update and restart them with the recently installed new revision artifacts.
TESTING¶
Waiting to see if the revision is stable. During this stage, Pantavisor checks if all containers are running and will rollback if any of them exits. Besides that, in the case of a remote update, it will also rollback in case Pantacor Hub communication is lost.
| Messages |
|---|
| Awaiting to set rollback point if update is stable |
| Awaiting to see if update is stable |
UPDATED¶
The revision is stable, but the update did not need a board reboot, so the rollback point is not set until you force a reboot.
| Messages |
|---|
| Update finished, revision not set as rollback point |
DONE¶
The revision has been fully booted and is stable. The rollback point is set.
| Messages |
|---|
| Update finished, revision set as rollback point |
| Factory revision |
WONTGO¶
The new revision cannot be installed because of a bad state JSON, so it is aborted before getting into INPROGRESS or TESTING.
| Messages | Possible causes |
|---|---|
| Update aborted | Local update cancelled by a command |
| Max download retries reached | The maximum processing or download retry number was reached for a remote update |
| Space required X B, available Y B | Not enough space in disk for remote update |
| Internal error | Memory allocation error or code bug |
| State not fully covered by signatures | The revision has some element that is not signed |
| Signature validation failed | Any of the revision signatures is not up to date with its covered content |
| Unknown error | Signature failed without a known cause |
| State JSON has bad format | State JSON could not be parsed |
ERROR¶
The new revision failed during INPROGRESS or TESTING stages. Pantavisor will try to rollback to the latest DONE revision.
| Messages | Possible causes |
|---|---|
| Internal error | Memory allocation error or code bug |
| State not fully covered by signatures | The revision has some element that is not signed |
| Signature validation failed | Any of the revision signatures is not up to date with its covered content |
| Unknown error | Signature failed without a known cause |
| Object validation went wrong | Stored object used by the revision changed or went corrupt |
| Hub not reachable | Connection with hub could not be achieved after a remote update |
| Hub communication not stable | Connection with hub was established but then failed during TESTING |
| Stale revision | An revision was found in hub with an index that is less than the current running revision one |
| Status goal not reached | Status goal of a container could not be reached before the end of TESTING |
| A container could not be started | A container failed during LXC start up |
| Unexpected rollback | Crash or power cycle before having the chance to report any meaningful status |
CANCELLED¶
Only applicable on remote updates. The revision has been marked as cancelled by the cloud side.