The Balena Supervisor has a /v1/device endpoint and a status boolean to get the overall state of the device. I have a web interface running on the device and when the device is downloading, installing, starting or in any other ‘non-ready’ state I will display a holding page. I was going to do this by getting the status from the /v1/device endpoint, but I’m reading that this is now deprecated: Supervisor status (via /v1/device) doesn't reflect downloading state - #2 by cywang117
What is the current equivalent to be able to achieve the same? I see a /v2/applications/stateand /v2/state/status but it’s not very clear what the equivalent would be, or what the different responses would be. For example:
Hi, thanks for your question, you are right that the documentation is not clear on the range of values for the endpoints /v2/state/status and /v2/applications/state, I’ll make a note to improve the documentation.
Regarding overallDownloadProgress, that field is an average of the download progress of all the images in the target release for the device. Is the multi-container equivalent for the single container endpoint /v1/device endpoint.
Regarding the possible values of status, for images in /v2/state/status, the range of possible values are Downloading, Downloaded, Deleting, you can se where they are defined here
For services, the list of values is defined here, and corresponds with the possible statuses for a service in the dashboard (Stopping, Stopped, Running, Installing, Installed, Dead, Exited, Paused, Restarting, Removing).
The /v2/applications/state endpoint aggregates images and services, so the status corresponds to the combination of the values shown above.
For appState, the valid values are applying or applied depending of whether there are still pending operations pending for the release install.
Regarding deprecation status, while it’s true that we advise against the use of the /v1/device endpoint as its meant for single container applications, we won’t be getting rid of any endpoints in /v1 and /v2/ until we can go to balenaOS 3 (no ETA yet).
Please let us know if this helps you or if you need more information about the existing endpoints.
v2/applications/state sounds like what I am looking for when you say it aggregates the status of the containers but the example in the docs only shows a status for each individual container. Is my best option then to loop through the output or v2/applications/state and check each status to get an aggregate status of the device? And I am assuming the ‘Installed’ state is only temporary, that will switch to ‘Running’ as soon as the container starts?
When I said /v2/applications/state “aggregates” the status I meant that it merges the concept of images and containers into “services”, not that it aggregates all service statuses into a single indicator. For instance, when a service is shown as downloaded, it means that the image has been downloaded but the container has not yet been created, Installing means the container is being created (you are correct is a temporary state) and Running means the service container has been started.
if you just need the overall status of the app, you can use the appState in the /v2/state/status endpoint which will return either applying or applied depending on whether there are any more operations pending for the latest release or not. If there are no more operations, that means that the device has reached the target state, i.e. all services have been started.
To clarify, applied is the equivalent of all containers displaying ‘running’ and nothing less or just related to installs? For example would things like paused or exited still be possible at the same time as an ‘applied’?
So “applied” is related to the target state sent to the supervisor. For instance on an app update a new target state is sent to the supervisor, with the new configuration of services. The supervisor will perform the necessary operations to get the device to the target configuration (download images, stop old containers and start new ones). Once it can get all services to a running state (no more pending operations), the target state is considered “applied”. A service may later exit or crash, but that doesn’t change that the supervisor already applied the target state.
However other configuration changes (device variables or device configurations) will also require the supervisor to go back to an “applying” state, even though no container changes are really necessary.
Given your initial question about the device in a ‘non-ready’ state, I think appStatus is probably the most consistent with what you are looking for, although feel free to let me know if I’m missing something.
Hi @maggie0002, this is unrelated to what my colleague Felipe is helping you with, but I noticed in your initial post that you are implementing a sort of “Local device UI” for your fleet. May I ask what the use case is? If you wouldn’t mind, could you comment your use case in this thread: Good Starting Place for Local Balena Device UI? Any time you can spare would be appreciated! We are looking at developing a device local UI which would provide the sort of information you are mentioning here, and the more user feedback we have, the better
