Improve this doc

Actions

Actions allow you to control the status of your applications and devices during runtime. Most actions can be applied in one of three ways:

  1. Accessing the Actions menu from the left side of the application summary page allows you to make changes to the application in general, and to all the devices in that application.
  2. The Actions menu on the device summary page lets you apply changes that only affect that one device.
  3. Group Actions, found at the top-right of the application summary page, are applied to a subset of the devices in your fleet. You can specify which devices will be affected by clicking the check boxes on the left of the device list. If you apply any filters or a saved view, clicking the check box at the top of the device list will select only the devices that appear in the list. If no filters are applied, this check box will select all devices in the application.

General actions

Application members with the Operator role and above can perform any of the actions listed below.

Enable Public Device URL

Balena currently exposes port 80 for web forwarding. This setting enables web forwarding and generates a web accessible url for any applicable devices. The URLs will be of the form <BALENA_DEVICE_UUID>.balena-devices.com, where <BALENA_DEVICE_UUID> is the unique ID of the device which you can see on your dashboard. Currently only HTTP traffic (level 7 OSI traffic) is supported via the device URLs.

Enable public device URL

To see what your device is serving on port 80, just click on the URL. If your application is not serving anything on port 80 or your webserver on the device crashes, you should see something like this:

Public URL error

You may also enable or disable public device URLs by clicking the Public device URL toggle button on the device summary page.

Public URL toggle

Restart Application

The Restart Application action restarts the currently running application containers. Your application's running containers will be removed and recreated from scratch. This behavior is intended, and is different from running balena restart [OPTIONS] CONTAINER [CONTAINER...] in a host OS terminal instance from your dashboard, which will not remove your containers. If you are trying to persist data between container removals, see persistent storage for strategies.

By removing containers and recreating them from scratch, we see benefits like the following:

  • Containers are meant to be ephemeral, meaning that a new container should be a drop-in replacement for an old container with minimal to no impact. Removing and recreating containers adheres to this philosophy.

  • Because containers are removed and recreated with the restart action, you're encouraged to follow best practices in Docker data persistence. For more information, see our persistent storage documentation or Docker's data persistence strategies. These strategies also offer a performance boost over storing files in the container's writable layer.

  • Removing and recreating containers may allow recovery from application bugs where the application is stuck in an invalid state. For example, a process ID file that is no longer valid but is persisted to the container filesystem would be cleaned up when recreating the container.

When the containers are stopped, the application is politely asked to stop by sending a SIGTERM. If the application hasn't stopped after 10 seconds, a SIGKILL is sent.

Note: During a restart any data that is not stored in /data will be lost.

It should be noted that currently these action notifications are not queued up, so if a device is offline when the action is triggered, it will never be notified of it.

Warning: Restart device container is not equivalent to a reboot of the device!

Purge Data

This action clears persistent storage on any applicable devices. For devices running balenaOS versions before 2.12.0, this means clearing the /data folder in the container (and the associated volume at /mnt/data/resin-data). On newer balenaOS versions, this action deletes all named volumes and recreates them as empty.

It should be noted that currently these action notifications are not queued up, so if a device is offline when the action is triggered, it will never be notified of it.

Warning: This action is only supported on devices with an Agent version >= 1.1.0

Reboot

This action allows you to perform a reboot on your devices This is different from the Restart Application action mentioned above—with this action, the entire device, including the kernel, will be rebooted as if there was a power cycle. It should be noted that currently these action notifications are not queued up, so if a device is offline when the action is triggered, it will never be notified of the action it missed.

Warning: This action is only supported on devices with an Agent version >= 1.1.0

Shutdown

The Shutdown action allows you to safely shut down your devices. It should be noted that once you trigger this action, there is no way for balena to start your device back up, so you will need to physically restart your device. Obviously this action is not a wise choice if your device is somewhere remote and inaccessible

Warning: This action is only supported on devices with an Agent version >= 1.1.0

Device-specific actions

Application members with the Operator role and above can perform any of the actions listed below.

Update Locking

In many uses cases devices are performing sensitive or critical functionality and are not able to pause to receive an update or restart the container. For this reason we added the update lock functionality in the balena device supervisor. This allows your application to pick and choose when and where it would like to allow updates to happen.

Added to this functionality we provided a convenient button to override the lock on the device and essentially force an update. This is a precautionary measure for those times when your application crashes and hasn't released the update lock. This gives you a nice safety net to ensure you can always push new updates.

Warning: This action is only supported on devices with an Agent version >= 1.1.0

Move to Another Application

With the Move Device action it is possible to transfer a device from one application to another. This allows you incrementally rollout devices or move certain devices to specific branches of functionality. To move a device from one application to another, simply click the Move to another application… button and you will be presented with a list of applications that you can move your device to.

Note that you are only able to move devices between applications with device types that share the same architecture. For example, a Raspberry Pi 3 device could be moved to a BeagleBone Black application, but not to an Intel NUC application.

Obviously you may only select one application to transfer your device to. Once you select the appropriate radio button, your device will immediately appear in the selected application's device list. Note that it will take a while for the device to start the update process as it does not receive a push notification of a new code update from the API, so it has to wait for the update poll, which happens every couple of minutes.

Warning: For devices running balenaOS version 2.12.0 and above, data in persistent storage (named volumes) is automatically purged when a device is moved to a new application. On older host OS versions, the /data folder in the new application will not contain any of the old application data, but it can still be accessed via the host OS and if the device is switched back to the original application. Unless you plan to revert back to the original application, be sure to purge the /data folder.

To see a demonstration of moving devices between applications and a little more on the motivation behind the feature have a look at our blog post: Canary Rollouts with balena

BalenaOS Update

This action allows you to remotely update the host OS running on your device. For more details on supported devices and the update process, check out our balenaOS update documentation.

Local Mode

Turning on local mode is useful when you are prototyping your application, as it allows you to push changes to your device over the local network without relying on the balena build pipeline. You can find more information in our development guide.

Deactivate Device

This action will deactivate the device and charge a one-time deactivation fee. To deactivate, the device must be offline, not be part of a Starter application, and be attached to a valid billing account.

Delete Device

The Delete Device action is an extremely dangerous action and results in disassociating the device from the application and remote endpoint. Once you have deleted a device from the application it is not possible to reconnect to it unless you set it back up again. The device itself will continue to run the container and code you pushed most recently, but will never be able to receive new updates or commands from the balena dashboard or API.

Grant Support Access

This action allows you to enable support access to an individual devices for a set time period.

Change device type

If one or more devices has been added to an application with the wrong device type, one can change the device-type for their devices through the dashboard. There are 2 ways to go about this,

Option 1: On the application’s device list, select one or more devices and click the Actions drop-down menu on the top right corner. Select Change device type option from the list and follow the instructions on the modal.

Change the device type from the device list

Option 2: On the device page, click Actions tab on the left sidebar menu. Scroll down to the Dangerous actions section and click Change device type after which follow the instructions on the modal to change your device-type.

Change the device type from the device page

Warning: Only change the device type if a device was incorrectly provisioned. This does not make any changes to the OS running on the device.

Application-specific actions

These actions can be found on the "Actions" menu for each application and apply to the application and all the devices in the fleet. Application members with the adminstrator role can perform any of the actions listed below.

Change Application Type

This option allows you to convert your application to another type, as long as the devices in the application meet the balenaOS version requirements and your account has the appropriate privileges.

Rename Application

This action allows you to rename your application. This action is only available for new applications types such as Starter, Microservices or Essentials. It's not currently possible to rename Legacy or Classic applications, you will first need to upgrade your app type.

Enable/Disable All Public Device URLs

This action allows you to enable or disable all the device URLs for the devices in your application. Note that this will only apply to already provisioned devices in the app, any devices added after you enable this fleet wide will need to have their device URL manually enabled.

You may also enable or disable public URLs for a subset of devices by selecting them on the application summary page and clicking Enable public device URL in the Actions menu.

Enable public device URLs for an application

Transfer Application Ownership

Applications with all their associated devices, releases and members can be transferred to any other balenaCloud organization. Application transfers are between a source and a target organization.

Only organization administrators can initiate and complete application transfers. You must coordinate with one of the receiving organization's administrators to perform the following actions:

  1. Take note of the application name in the source organization and your balenaCloud username (in the top-right drop-down menu).
  2. Ask an administrator of the target balenaCloud organization to create a new empty application using the same application name (the application type doesn't need to match).
  3. Ask the administrator of the target balenaCloud organization to add you as a member of the newly created application with a Developer role, using your username. If you are an administrator of the target organization, you already have access to the new application & this step can be skipped.
  4. In the source organization, select --> Actions --> Transfer This Application and pick the target organization from the list to complete the transfer.

Note: If the Transfer This Application button is grayed out, ensure that you have created an empty application in the target organization with the same name as the source application, and that user that is transferring ownership of the application from the source organization has been added as a Developer to the target application.

Once the transfer of ownership has been completed, the source application owner will no longer be a member of the target application. If required, you will need to invite them to become a member of the application again. All other members of the source application will retain their membership of the target application once the transfer is complete.

During and after the transfer process, the devices state will remain unchanged from before the transfer process was started. For example, devices that were online before the process was started will remain online throughout.

Grant Support Access

This action allows you to enable support access to the entire application fleet for a set time period.

Delete Application

This option permanently deletes your application.

Warning: It is a good idea to move your devices to another application before deleting your current application. If you do not, all devices attached to the application will become orphaned and you will need to reconfigure them from scratch. The most recent code deployment will continue to function as before, but the devices will not be able to receive code updates or device actions from balena.