From 47fcffe36813dfdbe59986ed6ae0e4a1a441ea63 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Wed, 14 Oct 2020 11:13:47 +0200 Subject: [PATCH] Add command device purge Change-type: minor Resolves: #1547 Signed-off-by: Scott Lowe --- automation/capitanodoc/capitanodoc.ts | 13 +- doc/cli.markdown | 532 ++++++++++++++------------ lib/commands/device/purge.ts | 80 ++++ 3 files changed, 364 insertions(+), 261 deletions(-) create mode 100644 lib/commands/device/purge.ts diff --git a/automation/capitanodoc/capitanodoc.ts b/automation/capitanodoc/capitanodoc.ts index 131fa945..fb7273c8 100644 --- a/automation/capitanodoc/capitanodoc.ts +++ b/automation/capitanodoc/capitanodoc.ts @@ -55,20 +55,21 @@ const capitanoDoc = { { title: 'Device', files: [ + 'build/commands/devices/index.js', + 'build/commands/devices/supported.js', + 'build/commands/device/index.js', 'build/commands/device/identify.js', 'build/commands/device/init.js', - 'build/commands/device/index.js', 'build/commands/device/move.js', + 'build/commands/device/os-update.js', + 'build/commands/device/public-url.js', + 'build/commands/device/purge.js', 'build/commands/device/reboot.js', 'build/commands/device/register.js', 'build/commands/device/rename.js', - 'build/commands/device/rm.js', 'build/commands/device/restart.js', + 'build/commands/device/rm.js', 'build/commands/device/shutdown.js', - 'build/commands/devices/index.js', - 'build/commands/devices/supported.js', - 'build/commands/device/os-update.js', - 'build/commands/device/public-url.js', ], }, { diff --git a/doc/cli.markdown b/doc/cli.markdown index 60c3fe9c..6baa4940 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -174,20 +174,21 @@ Users are encouraged to regularly update the balena CLI to the latest version. - Device + - [devices](#devices) + - [devices supported](#devices-supported) + - [device <uuid>](#device-uuid) - [device identify <uuid>](#device-identify-uuid) - [device init](#device-init) - - [device <uuid>](#device-uuid) - [device move <uuid(s)>](#device-move-uuid-s) + - [device os-update <uuid>](#device-os-update-uuid) + - [device public-url <uuid>](#device-public-url-uuid) + - [device purge <uuid>](#device-purge-uuid) - [device reboot <uuid>](#device-reboot-uuid) - [device register <application>](#device-register-application) - [device rename <uuid> [newname]](#device-rename-uuid-newname) - - [device rm <uuid(s)>](#device-rm-uuid-s) - [device restart <uuid>](#device-restart-uuid) + - [device rm <uuid(s)>](#device-rm-uuid-s) - [device shutdown <uuid>](#device-shutdown-uuid) - - [devices](#devices) - - [devices supported](#devices-supported) - - [device os-update <uuid>](#device-os-update-uuid) - - [device public-url <uuid>](#device-public-url-uuid) - Environment Variables @@ -504,255 +505,6 @@ Examples: # Device -## device identify <uuid> - -Identify a device by making the ACT LED blink (Raspberry Pi). - -Examples: - - $ balena device identify 23c73a1 - -### Arguments - -#### UUID - -the uuid of the device to identify - -### Options - -## device init - -Initialise a device by downloading the OS image of a certain application -and writing it to an SD Card. - -Note, if the application option is omitted it will be prompted -for interactively. - -Examples: - - $ balena device init - $ balena device init --application MyApp - -### Options - -#### -a, --application APPLICATION - -application name - -#### --app APP - -same as '--application' - -#### -y, --yes - -answer "yes" to all questions (non interactive use) - -#### -v, --advanced - -show advanced configuration options - -#### --os-version OS-VERSION - -exact version number, or a valid semver range, -or 'latest' (includes pre-releases), -or 'default' (excludes pre-releases if at least one stable version is available), -or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available), -or 'menu' (will show the interactive menu) - -#### -d, --drive DRIVE - -the drive to write the image to, eg. `/dev/sdb` or `/dev/mmcblk0`. -Careful with this as you can erase your hard drive. -Check `balena util available-drives` for available options. - -#### --config CONFIG - -path to the config JSON file, see `balena os build-config` - -## device <uuid> - -Show information about a single device. - -Examples: - - $ balena device 7cf02a6 - -### Arguments - -#### UUID - -the device uuid - -### Options - -## device move <uuid(s)> - -Move one or more devices to another application. - -Note, if the application option is omitted it will be prompted -for interactively. - -Examples: - - $ balena device move 7cf02a6 - $ balena device move 7cf02a6,dc39e52 - $ balena device move 7cf02a6 --application MyNewApp - -### Arguments - -#### UUID - -comma-separated list (no blank spaces) of device UUIDs to be moved - -### Options - -#### -a, --application APPLICATION - -application name - -#### --app APP - -same as '--application' - -## device reboot <uuid> - -Remotely reboot a device. - -Examples: - - $ balena device reboot 23c73a1 - -### Arguments - -#### UUID - -the uuid of the device to reboot - -### Options - -#### -f, --force - -force action if the update lock is set - -## device register <application> - -Register a device to an application. - -Examples: - - $ balena device register MyApp - $ balena device register MyApp --uuid - -### Arguments - -#### APPLICATION - -the name or id of application to register device with - -### Options - -#### -u, --uuid UUID - -custom uuid - -## device rename <uuid> [newName] - -Rename a device. - -Note, if the name is omitted, it will be prompted for interactively. - -Examples: - - $ balena device rename 7cf02a6 - $ balena device rename 7cf02a6 MyPi - -### Arguments - -#### UUID - -the uuid of the device to rename - -#### NEWNAME - -the new name for the device - -### Options - -## device rm <uuid(s)> - -Remove one or more devices from balena. - -Note this command asks for confirmation interactively. -You can avoid this by passing the `--yes` option. - -Examples: - - $ balena device rm 7cf02a6 - $ balena device rm 7cf02a6,dc39e52 - $ balena device rm 7cf02a6 --yes - -### Arguments - -#### UUID - -comma-separated list (no blank spaces) of device UUIDs to be removed - -### Options - -#### -y, --yes - -answer "yes" to all questions (non interactive use) - -## device restart <uuid> - -Restart containers on a device. -If the --service flag is provided, then only those services' containers -will be restarted, otherwise all containers on the device will be restarted. - -Multiple devices and services may be specified with a comma-separated list -of values (no spaces). - -Note this does not reboot the device, to do so use instead `balena device reboot`. - -Examples: - - $ balena device restart 23c73a1 - $ balena device restart 55d43b3,23c73a1 - $ balena device restart 23c73a1 --service myService - $ balena device restart 23c73a1 -s myService1,myService2 - -### Arguments - -#### UUID - -comma-separated list (no blank spaces) of device UUIDs to restart - -### Options - -#### -s, --service SERVICE - -comma-separated list (no blank spaces) of service names to restart - -## device shutdown <uuid> - -Remotely shutdown a device. - -Examples: - - $ balena device shutdown 23c73a1 - -### Arguments - -#### UUID - -the uuid of the device to shutdown - -### Options - -#### -f, --force - -force action if the update lock is set - ## devices list all devices that belong to you. @@ -820,6 +572,116 @@ produce JSON output instead of tabular output add extra columns in the tabular output (ALIASES, ARCH, STATE) +## device <uuid> + +Show information about a single device. + +Examples: + + $ balena device 7cf02a6 + +### Arguments + +#### UUID + +the device uuid + +### Options + +## device identify <uuid> + +Identify a device by making the ACT LED blink (Raspberry Pi). + +Examples: + + $ balena device identify 23c73a1 + +### Arguments + +#### UUID + +the uuid of the device to identify + +### Options + +## device init + +Initialise a device by downloading the OS image of a certain application +and writing it to an SD Card. + +Note, if the application option is omitted it will be prompted +for interactively. + +Examples: + + $ balena device init + $ balena device init --application MyApp + +### Options + +#### -a, --application APPLICATION + +application name + +#### --app APP + +same as '--application' + +#### -y, --yes + +answer "yes" to all questions (non interactive use) + +#### -v, --advanced + +show advanced configuration options + +#### --os-version OS-VERSION + +exact version number, or a valid semver range, +or 'latest' (includes pre-releases), +or 'default' (excludes pre-releases if at least one stable version is available), +or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available), +or 'menu' (will show the interactive menu) + +#### -d, --drive DRIVE + +the drive to write the image to, eg. `/dev/sdb` or `/dev/mmcblk0`. +Careful with this as you can erase your hard drive. +Check `balena util available-drives` for available options. + +#### --config CONFIG + +path to the config JSON file, see `balena os build-config` + +## device move <uuid(s)> + +Move one or more devices to another application. + +Note, if the application option is omitted it will be prompted +for interactively. + +Examples: + + $ balena device move 7cf02a6 + $ balena device move 7cf02a6,dc39e52 + $ balena device move 7cf02a6 --application MyNewApp + +### Arguments + +#### UUID + +comma-separated list (no blank spaces) of device UUIDs to be moved + +### Options + +#### -a, --application APPLICATION + +application name + +#### --app APP + +same as '--application' + ## device os-update <uuid> Start a Host OS update for a device. @@ -890,6 +752,166 @@ disable the public URL determine if public URL is enabled +## device purge <uuid> + +Purge application data from a device. +This will clear the application's /data directory. + +Multiple devices may be specified with a comma-separated list +of values (no spaces). + +Examples: + + $ balena device purge 23c73a1 + $ balena device purge 55d43b3,23c73a1 + +### Arguments + +#### UUID + +comma-separated list (no blank spaces) of device UUIDs + +### Options + +## device reboot <uuid> + +Remotely reboot a device. + +Examples: + + $ balena device reboot 23c73a1 + +### Arguments + +#### UUID + +the uuid of the device to reboot + +### Options + +#### -f, --force + +force action if the update lock is set + +## device register <application> + +Register a device to an application. + +Examples: + + $ balena device register MyApp + $ balena device register MyApp --uuid + +### Arguments + +#### APPLICATION + +the name or id of application to register device with + +### Options + +#### -u, --uuid UUID + +custom uuid + +## device rename <uuid> [newName] + +Rename a device. + +Note, if the name is omitted, it will be prompted for interactively. + +Examples: + + $ balena device rename 7cf02a6 + $ balena device rename 7cf02a6 MyPi + +### Arguments + +#### UUID + +the uuid of the device to rename + +#### NEWNAME + +the new name for the device + +### Options + +## device restart <uuid> + +Restart containers on a device. +If the --service flag is provided, then only those services' containers +will be restarted, otherwise all containers on the device will be restarted. + +Multiple devices and services may be specified with a comma-separated list +of values (no spaces). + +Note this does not reboot the device, to do so use instead `balena device reboot`. + +Examples: + + $ balena device restart 23c73a1 + $ balena device restart 55d43b3,23c73a1 + $ balena device restart 23c73a1 --service myService + $ balena device restart 23c73a1 -s myService1,myService2 + +### Arguments + +#### UUID + +comma-separated list (no blank spaces) of device UUIDs to restart + +### Options + +#### -s, --service SERVICE + +comma-separated list (no blank spaces) of service names to restart + +## device rm <uuid(s)> + +Remove one or more devices from balena. + +Note this command asks for confirmation interactively. +You can avoid this by passing the `--yes` option. + +Examples: + + $ balena device rm 7cf02a6 + $ balena device rm 7cf02a6,dc39e52 + $ balena device rm 7cf02a6 --yes + +### Arguments + +#### UUID + +comma-separated list (no blank spaces) of device UUIDs to be removed + +### Options + +#### -y, --yes + +answer "yes" to all questions (non interactive use) + +## device shutdown <uuid> + +Remotely shutdown a device. + +Examples: + + $ balena device shutdown 23c73a1 + +### Arguments + +#### UUID + +the uuid of the device to shutdown + +### Options + +#### -f, --force + +force action if the update lock is set + # Environment Variables ## envs diff --git a/lib/commands/device/purge.ts b/lib/commands/device/purge.ts new file mode 100644 index 00000000..a3c979ac --- /dev/null +++ b/lib/commands/device/purge.ts @@ -0,0 +1,80 @@ +/** + * @license + * Copyright 2016-2020 Balena Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { flags } from '@oclif/command'; +import type { IArg } from '@oclif/parser/lib/args'; +import Command from '../../command'; +import * as cf from '../../utils/common-flags'; +import { getBalenaSdk, getCliUx, stripIndent } from '../../utils/lazy'; + +interface FlagsDef { + help: void; +} + +interface ArgsDef { + uuid: string; +} + +export default class DevicePurgeCmd extends Command { + public static description = stripIndent` + Purge application data from a device. + + Purge application data from a device. + This will clear the application's /data directory. + + Multiple devices may be specified with a comma-separated list + of values (no spaces). + `; + public static examples = [ + '$ balena device purge 23c73a1', + '$ balena device purge 55d43b3,23c73a1', + ]; + + public static usage = 'device purge '; + + public static args: Array> = [ + { + name: 'uuid', + description: 'comma-separated list (no blank spaces) of device UUIDs', + required: true, + }, + ]; + + public static flags: flags.Input = { + help: cf.help, + }; + + public static authenticated = true; + + public async run() { + const { args: params } = this.parse(DevicePurgeCmd); + + const { tryAsInteger } = await import('../../utils/validation'); + const balena = getBalenaSdk(); + const ux = getCliUx(); + + const deviceIds = params.uuid.split(',').map((id) => { + return tryAsInteger(id); + }); + + for (const deviceId of deviceIds) { + ux.action.start(`Purging data from device ${deviceId}`); + await balena.models.device.purge(deviceId); + ux.action.stop(); + } + } +}