balena_device v0.1.0 BalenaDevice.V2

This module contains the version two API endpoints as described in the API documentation.

Link to this section Summary

Functions

application_state(app_id)

Use this endpoint to get the state of a single application, given the app_id.

applications_state()

Returns a map of applications and their state.

cleanup_volumes()

Cleanup volumes with no references

container_id(service_name)

Use this endpoint to match a service name to a container ID.

container_ids()

Use this endpoint to match a service name to a container ID.

device_name()

Get the last returned device name from the balena API. Note that this differs from the BALENA_DEVICE_NAME_AT_INIT environment variable provided to containers, as this will not change throughout the runtime of the container, but the endpoint will always return the latest known device name.

device_tags()

Retrieve any device tags from the balena API. Note that this endpoint will not work when the device does not have an available connection to the balena API.

journald_logs(options \\ [])

journald logs

local_device_info()

Get the architecture and device type of the device.

local_log_stream()

Stream local mode application logs from the device.

local_target_state()

Get the current target state. Note that if a local mode target state has not been set then the apps section of the response will always be empty.

local_target_state(config)

Set the current target state.

purge(app_id)

Use this endpoint to purge all user data for a given application id.

restart_service(app_id, arg2)

Restart an application's service based on it's service name or image id.

restart_services(app_id)

Restart all services in an application.

start_service(app_id, arg2)

Start an application's service based on it's service name or image id.

status()

This will return a list of images, containers, the overall download progress and the status of the state engine.

stop_service(app_id, arg2)

Stop an application's service based on it's service name or image id.

supervisor_version()

This endpoint returns the supervisor version currently running the device api.

Link to this section Types

journald_option()

journald_option() ::
  {:all, boolean()}
  | {:follow, boolean()}
  | {:count, non_neg_integer()}
  | {:unit, String.t()}
  | {:format, String.t()}

journald_options()

journald_options() :: [journald_option()]

Link to this section Functions

application_state(app_id)

application_state(BalenaDevice.app_id()) :: {:ok, map()} | {:error, term()}

Use this endpoint to get the state of a single application, given the app_id.

applications_state()

applications_state() :: {:ok, [map()]} | {:error, term()}

Returns a map of applications and their state.

cleanup_volumes()

cleanup_volumes() :: :ok | {:error, term()}

Cleanup volumes with no references

Added in supervisor version v10.0.0

Starting with balena-supervisor v10.0.0, volumes which have no references are no longer automatically removed as part of the standard update flow. To cleanup up any orphaned volumes, use this supervisor endpoint.

container_id(service_name)

container_id(String.t()) :: {:ok, String.t()} | {:error, term()}

Use this endpoint to match a service name to a container ID.

container_ids()

container_ids() :: {:ok, map()} | {:error, term()}

Use this endpoint to match a service name to a container ID.

device_name()

device_name() :: {:ok, String.t()} | {:error, term()}

device_tags()

device_tags() :: {:ok, [map()]} | {:error, term()}

Retrieve any device tags from the balena API. Note that this endpoint will not work when the device does not have an available connection to the balena API.

journald_logs(options \\ [])

journald_logs(journald_options()) ::
  {:ok, String.t()} | {:ok, pid()} | {:error, term()}

journald logs

Added in supervisor version v10.2.0

Retrieve a stream to the journald logs on device. This is equivalent to running journalctl --no-pager. Options supported are:

all: boolean Show all fields in full, equivalent to journalctl --all.
follow: boolean Continuously stream logs as they are generated, equivalent to journalctl --follow.
count: integer Show the most recent count events, equivalent to journalctl --line=<count>.
unit: String.t Show journal logs from unit only, equivalent to journalctl --unit=<unit>.
format: String.t Added in supervisor version v10.3.0 The format which will be streamed from journalctl, formats are described here: https://www.freedesktop.org/software/systemd/man/journalctl.html#-o

local_device_info()

local_device_info() :: {:ok, map()} | {:error, term()}

Get the architecture and device type of the device.

local_log_stream()

local_log_stream() :: {:ok, pid()} | {:error, term()}

Stream local mode application logs from the device.

This function starts a process which will send logs to the creating processes mailbox as they arrive.

local_target_state()

local_target_state() :: {:ok, map()} | {:error, term()}

Get the current target state. Note that if a local mode target state has not been set then the apps section of the response will always be empty.

Only works on devices which are running in local mode.

local_target_state(config)

local_target_state(map()) :: :ok | {:error, term()}

Set the current target state.

purge(app_id)

purge(BalenaDevice.app_id()) :: :ok | {:error, term()}

Use this endpoint to purge all user data for a given application id.

restart_service(app_id, arg2)

restart_service(
  BalenaDevice.app_id(),
  [{:service_name, String.t()}] | [{:image_id, String.t()}]
) :: :ok | {:error, term()}

Restart an application's service based on it's service name or image id.

restart_services(app_id)

restart_services(BalenaDevice.app_id()) :: :ok | {:error, term()}

Restart all services in an application.

start_service(app_id, arg2)

start_service(
  BalenaDevice.app_id(),
  [{:service_name, String.t()}] | [{:image_id, String.t()}]
) :: :ok | {:error, term()}

Start an application's service based on it's service name or image id.

status()

status() :: {:ok, map()} | {:error, term()}

This will return a list of images, containers, the overall download progress and the status of the state engine.

stop_service(app_id, arg2)

stop_service(
  BalenaDevice.app_id(),
  [{:service_name, String.t()}] | [{:image_id, String.t()}]
) :: :ok | {:error, term()}

Stop an application's service based on it's service name or image id.

supervisor_version()

supervisor_version() :: {:ok, String.t()} | {:error, term()}

This endpoint returns the supervisor version currently running the device api.