Pantavisor implements a lightweight container run-time with the help of Linux Containers (LXC). Each container, in its minimal form, is then comprised of a rootfs that will be run isolated in its own name-space and an LXC configuration file. All these, as well as more advanced configuration, are included in the state JSON.
The most basic storage unit is always the rootfs. In addition to this, a container may define several more auxiliary storage volumes. Pantavisor gives flexibility to configure persistence of changes and encryption.
There a three types of persistence options:
- permanent: changes are stored in a single writable location.
- revision: changes are stored in a writable location pegged to the revision.
- boot: a pure tmpfs storage that will throw away changes after a reset.
Storage can be linked to a storage disk.
- required: these drivers will be loaded as soon as container is STARTED. The revision will fail if the drivers are not enabled through BSP as managed drivers.
- optional: these drivers will be loaded as soon as container is STARTED too. In this case the revision will not fail if the drivers are not defined in the BSP.
- manual: drivers can be loaded from within containers trough local control. The success or failure of loading drivers using the REST API will not determine whether a revision fails or not, but the calls will return an error response if necessary.
Containers, by default, will automatically direct these logs from the container to the log server:
- lxc log
- lxc console
This list can be expanded to other files using the state JSON.
Containers can be grouped.
Groups main function is to define the order in which containers are started. Groups are ordered and will not begin the mount and/or start up of their containers until all status goals from all the containers belonging to the previous group are achieved. The status goal of each container can be configured at group level as well as overloaded for each container. If not configured at container level, group also determines the restart policy in a similar way as the status goal.
If groups are not explicitly configured, Pantavisor will create the default ones:
|name||default status goal||default restart policy||description|
|data||MOUNTED||system||containers which volumes we want to mount but not to be started|
|root||STARTED||system||container or containers that are in charge of setting network connectivity up for the board|
|platform||STARTED||system||middleware and utility containers|
|app||STARTED||container||application level containers|
When using the default groups and if a container is not linked to a group, it will be automatically set to platform, except if it is the first container in alphabetical order and no other container has been set to root, in which case it will be set to root. If not using the default groups and if a container is not linked to a group, the revision will fail.
Roles can be set to a given container. Roles will determine the elements that Pantavisor will make available in the container rootfs. There is just one role supported for now: mgmt.
If no role is defined, Pantavisor just mounts these elements into the container under the /pantavisor path:
- pv-ctrl socket with no privileges (only allows to report signals to alter the status goal).
- pv-ctrl-log socket to send logs to Pantavisor.
- The stored logs for that container and revision.
- The stored user metadata and device metadata for that container.
In addition to this, mgmt containers get these elements in /pantavisor:
- pv-ctrl socket with privileges (full request support).
- pv-ctrl-log socket to send logs to Pantavisor.
- Full logs for all containers and revisions.
- The stored user metadata and device metadata for all containers.
- Challenge and device-id information for Pantacor Hub.
- 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
These are the different status containers can be at:
- INSTALLED: the container is installed and ready to go.
- MOUNTED: the container volumes are mounted, but not yet started.
- BLOCKED: any of the status goals from a container belonging to the previous group are not yet achieved.
- STARTING: container is starting.
- STARTED: container PID is running.
- READY: Pantavisor has received a readiness signal from the container.
- STOPPING: container is stopping because of a update transition.
- STOPPED: container has stopped.
These are the status goals currently supported:
- MOUNTED: for containers whose volumes we want to be mounted but not started.
- STARTED: rest of containers that we want mounted and started, but we only check if its PID is running.
- READY: same as STARTED, but a readiness signal coming from the container namespace is required.
For now, we only support the READY signal, which can be used to get to the READY status goal from a container.
Before starting a container, Pantavisor will mount its main rootfs and any other configured volumes. Besides this, additional files can be attached to a revision to create a new overlay that will overwrite whatever is in that location in the rootfs of the container, creating the directories or files if necessary.
Thanks to this, configuration files or scripts can be added or modified without having to do it in the rootfs itself when preparing a new revision.