Skip to content

Renaming of Applications to Fleets

Paulo Castro edited this page Aug 9, 2021 · 1 revision

Balena 'Applications' are being renamed to 'Fleets' in order to better match the concept of a set of devices -- a fleet -- running a user's application. Read more in our blog post.

This wiki page focuses on how the renaming affects the balena CLI, and what you need to do to adapt any scripts written around it.

TL;DR - What you need to do

If you don't have scripts that invoke the balena CLI, just be generally aware that balena "applications" are now known as "fleets", and browse the list of affected CLI commands in the Scope section.

If you have scripts that invoke the balena CLI, for example in CI/CD environments, then, typically:

  • balena CLI upgrades from earlier v12 versions to v12.45.0 or later (within v12) will not normally break scripted usage, except possibly in the rare cases where a fake terminal (tty) is attached to stderr, or specific error messages containing the words 'app' or 'application' are parsed by scripts.

  • If your scripts make use of the affected commands or options listed in this document, or if they parse balena CLI output containing the words 'app' or 'application', then:

    • Changes will be required before upgrading the CLI to v13.
    • Consider updating the scripts to make use of the 'fleet' variants and renamed CLI output sooner than later, including adding the --v13 flag where applicable, as explained in this document, to reduce the amount of work required later on when updating the balena CLI to v13.
    • Some users will however prefer to wait until CLI v13 is released and the full v13 release notes are published, in order to make all required script adaptations in one go.

Scope

The renaming will affect balena CLI command names, flags/options, and output such as column/row headers and JSON object properties. To aid in the transition, there will be a backwards-compatible stage where both old and new names are accepted interchangeably, ahead of a breaking-change stage. Overall, the renaming endgame is provided in the following tables.

Before renaming After renaming
balena apps balena fleets
balena app balena fleet
balena app create balena fleet create
balena app rm balena fleet rm
balena app rename balena fleet rename
balena app restart balena fleet restart
balena app purge balena fleet purge
Before renaming After renaming
balena build --application balena build --fleet
balena config generate --application balena config generate --fleet
balena devices --application balena devices --fleet
balena device init --application balena device init --fleet
balena device move --application balena device move --fleet
balena envs --application balena envs --fleet
balena env add --application balena env add --fleet
balena join --application balena join --fleet
balena os configure --application balena os configure --fleet
balena preload --app balena preload --fleet
balena support --application balena support --fleet
balena tags --application balena tags --fleet
balena tag set --application balena tag set --fleet
balena tag rm --application balena tag rm --fleet

Similarly, the '-a' single-character option will be renamed to '-f'.

Regarding the output printed by some commands:

Command Output column/row header Output JSON property
balena appsfleets APP NAMENAME N/A
balena envs APPLICATIONFLEET appNamefleetName
balena devices APPLICATION NAMEFLEET application_namefleet_name
balena device APPLICATION NAMEFLEET N/A

⚠ Note
(1) References to 'app' or 'application' (and capitalized variants) will be renamed to 'fleet' in error messages as well, and this will affect more commands than the ones listed in these tables.
(2) Apart from error messages, the lists of commands and options in the tables above are believed to be exhaustive on a best effort basis, but this is not guaranteed. Please report an issue or submit a PR if you come across omissions or mistakes.

Renaming stages

The renaming will happen in two stages. The balena CLI is currently at major semver version 12, and the first stage will take place in version 12.45.0. The second stage will take place in version 13.0.0.

First stage - balena CLI version 12.45.0

This stage is substantially backwards compatible. Upgrading the CLI from earlier v12 versions to version 12.45.0 should not normally break scripts written around the balena CLI, except possibly in circumstances where a fake interactive terminal is attached to stderr or specific error messages are parsed, and depending on script logic. In this stage:

  • New commands such as 'balena fleets' or 'balena fleet <name>' become available, with the same syntax and functionality as the respective 'app(s)' commands.
  • The '--fleet' option is added alongside the '--application' option for the relevant commands, and either option may be used.
  • If stderr is attached to an interactive terminal (process.stderr.isTTY is true) and the 'app(s)' or '--application' commands/options are used, a warning message is printed to stderr to warn and advise users of the changes. Scripts parsing CLI output should not see this message, and therefore not break, because isTTY is normally false when the CLI output is piped in shell scripts, or consumed from a child process. However, if an interactive TTY is programmatically attached to stderr, scripts may require adjustment, depending on script logic.
  • The name of column/row headers and JSON object properties in the balena CLI output (as per tables above) will not change, unless:
    • 'balena fleets' is used instead of 'balena apps'; or
    • '--fleet' is used instead of '--application', where applicable; or
    • In the case of 'balena envs', 'balena device' or 'balena devices', a newly added '--v13' flag is used.
  • Again subject to stderr being an interactive terminal, the 'balena envs' and 'balena device(s)' commands may print a warning message to stderr regarding the rename of column/row headers or JSON object properties. This message can be avoided by replacing '--application' with '--fleet' where applicable, or by using a newly added '--v13' option that brings forward the renaming behavior of CLI v13. (The '--v13' option will be quietly ignored by CLI v13.)
  • References to 'application' in some, but not all, error messages will be replaced with 'fleet'. Scripts that parse the text of such error messages may require adjustment.

Second stage - balena CLI version 13.0.0

balena CLI version 13.0.0 is still under development and a separate 'release notes' document will be published in due course. With regard to the renaming from applications to fleets, CLI v13 will introduce the following breaking changes:

  • The 'app(s)' and '--application' commands and options will be removed, being replaced by the respective 'fleet(s)' and '--fleet' variants.
  • Column/row headers and JSON object properties will be renamed as described in the Scope section, without exceptions.
  • The advisory warning messages regarding the renaming will be removed.
  • Most (ideally all) references to 'application' in error messages will be replaced with 'fleet'. (We aim at renaming all references, the difficulty being that several dependency npm packages / other GitHub repositories contain error messages as well.)

FAQ

  • Breaking changes have a cost. Why are these changes needed?
    These breaking changes are necessary in order to unify the terminology we use across the entire balena product surface, to create a more cohesive experience where the same objects are referred to using identical terms no matter where you interact with them. Read more in our blog post.