diff --git a/automation/capitanodoc/capitanodoc.ts b/automation/capitanodoc/capitanodoc.ts index 3013e4e2..0b04b218 100644 --- a/automation/capitanodoc/capitanodoc.ts +++ b/automation/capitanodoc/capitanodoc.ts @@ -116,7 +116,7 @@ const capitanoDoc = { }, { title: 'Platform', - files: ['build/actions/join.js', 'build/actions/leave.js'], + files: ['build/actions-oclif/join.js', 'build/actions-oclif/leave.js'], }, { title: 'Utilities', diff --git a/doc/cli.markdown b/doc/cli.markdown index 10c8c3ca..130e8de8 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -247,8 +247,8 @@ If you come across any problems or would like to get in touch: - Platform - - [join [deviceIp]](#join-deviceip) - - [leave [deviceIp]](#leave-deviceip) + - [join [deviceiporhostname]](#join-deviceiporhostname) + - [leave [deviceiporhostname]](#leave-deviceiporhostname) - Utilities @@ -2146,9 +2146,10 @@ Squash newly built layers into a single new layer # Platform -## join [deviceIp] +## join [deviceIpOrHostname] -Use this command to move a local device to an application on another balena server. +Move a local device to an application on another balena server, causing +the device to "join" the new server. The device must be running balenaOS. For example, you could provision a device against an openBalena installation where you perform end-to-end tests and then move it to balenaCloud when it's @@ -2159,7 +2160,8 @@ To move a device between applications on the same server, use the If you don't specify a device hostname or IP, this command will automatically scan the local network for balenaOS devices and prompt you to select one -from an interactive picker. This usually requires root privileges. +from an interactive picker. This requires root privileges. Likewise, if +the application flag is not provided then a picker will be shown. Examples: @@ -2169,16 +2171,23 @@ Examples: $ balena join 192.168.1.25 $ balena join 192.168.1.25 --application MyApp +### Arguments + +#### DEVICEIPORHOSTNAME + +the IP or hostname of device + ### Options -#### --application, -a <application> +#### -a, --application APPLICATION -The name of the application the device should join +application name -## leave [deviceIp] +## leave [deviceIpOrHostname] -Use this command to make a local device leave the balena server it is -provisioned on. This effectively makes the device "unmanaged". +Remove a local device from its balena application, causing the device to +"leave" the server it is provisioned on. This effectively makes the device +"unmanaged". The device must be running balenaOS. The device entry on the server is preserved after running this command, so the device can subsequently re-join the server if needed. @@ -2193,6 +2202,14 @@ Examples: $ balena leave balena.local $ balena leave 192.168.1.25 +### Arguments + +#### DEVICEIPORHOSTNAME + +the device IP or hostname + +### Options + # Utilities ## util available-drives diff --git a/lib/actions-oclif/join.ts b/lib/actions-oclif/join.ts new file mode 100644 index 00000000..ef8785cc --- /dev/null +++ b/lib/actions-oclif/join.ts @@ -0,0 +1,98 @@ +/** + * @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 { stripIndent } from 'common-tags'; +import Command from '../command'; +import * as cf from '../utils/common-flags'; +import { getBalenaSdk } from '../utils/lazy'; + +interface FlagsDef { + application?: string; + help?: void; +} + +interface ArgsDef { + deviceIpOrHostname?: string; +} + +export default class JoinCmd extends Command { + public static description = stripIndent` + Move a local device to an application on another balena server. + + Move a local device to an application on another balena server, causing + the device to "join" the new server. The device must be running balenaOS. + + For example, you could provision a device against an openBalena installation + where you perform end-to-end tests and then move it to balenaCloud when it's + ready for production. + + To move a device between applications on the same server, use the + \`balena device move\` command instead of \`balena join\`. + + If you don't specify a device hostname or IP, this command will automatically + scan the local network for balenaOS devices and prompt you to select one + from an interactive picker. This requires root privileges. Likewise, if + the application flag is not provided then a picker will be shown. + `; + + public static examples = [ + '$ balena join', + '$ balena join balena.local', + '$ balena join balena.local --application MyApp', + '$ balena join 192.168.1.25', + '$ balena join 192.168.1.25 --application MyApp', + ]; + + public static args = [ + { + name: 'deviceIpOrHostname', + description: 'the IP or hostname of device', + }, + ]; + + // Hardcoded to preserve camelcase + public static usage = 'join [deviceIpOrHostname]'; + + public static flags: flags.Input = { + application: { + description: 'the name of the application the device should join', + ...cf.application, + }, + help: cf.help, + }; + + public static authenticated = true; + public static primary = true; + + public async run() { + const { args: params, flags: options } = this.parse( + JoinCmd, + ); + + const Logger = await import('../utils/logger'); + const promote = await import('../utils/promote'); + const sdk = getBalenaSdk(); + const logger = Logger.getLogger(); + return promote.join( + logger, + sdk, + params.deviceIpOrHostname, + options.application, + ); + } +} diff --git a/lib/actions-oclif/leave.ts b/lib/actions-oclif/leave.ts new file mode 100644 index 00000000..80f3d955 --- /dev/null +++ b/lib/actions-oclif/leave.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 { stripIndent } from 'common-tags'; +import Command from '../command'; +import * as cf from '../utils/common-flags'; +import { getBalenaSdk } from '../utils/lazy'; + +interface FlagsDef { + help?: void; +} + +interface ArgsDef { + deviceIpOrHostname?: string; +} + +export default class LeaveCmd extends Command { + public static description = stripIndent` + Remove a local device from its balena application. + + Remove a local device from its balena application, causing the device to + "leave" the server it is provisioned on. This effectively makes the device + "unmanaged". The device must be running balenaOS. + + The device entry on the server is preserved after running this command, + so the device can subsequently re-join the server if needed. + + If you don't specify a device hostname or IP, this command will automatically + scan the local network for balenaOS devices and prompt you to select one + from an interactive picker. This usually requires root privileges. + `; + + public static examples = [ + '$ balena leave', + '$ balena leave balena.local', + '$ balena leave 192.168.1.25', + ]; + + public static args = [ + { + name: 'deviceIpOrHostname', + description: 'the device IP or hostname', + }, + ]; + + // Hardcoded to preserve camelcase + public static usage = 'leave [deviceIpOrHostname]'; + + public static flags: flags.Input = { + help: cf.help, + }; + + public static authenticated = true; + public static primary = true; + + public async run() { + const { args: params } = this.parse(LeaveCmd); + + const Logger = await import('../utils/logger'); + const promote = await import('../utils/promote'); + const sdk = getBalenaSdk(); + const logger = Logger.getLogger(); + return promote.leave(logger, sdk, params.deviceIpOrHostname); + } +} diff --git a/lib/actions/index.coffee b/lib/actions/index.coffee index 5d885d61..e6bd00cd 100644 --- a/lib/actions/index.coffee +++ b/lib/actions/index.coffee @@ -33,6 +33,4 @@ module.exports = util: require('./util') preload: require('./preload') push: require('./push') - join: require('./join') - leave: require('./leave') tunnel: require('./tunnel') diff --git a/lib/actions/join.ts b/lib/actions/join.ts deleted file mode 100644 index 6df9bdf3..00000000 --- a/lib/actions/join.ts +++ /dev/null @@ -1,73 +0,0 @@ -/* -Copyright 2016-2017 Balena - -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 { CommandDefinition } from 'capitano'; -import { stripIndent } from 'common-tags'; -import { getBalenaSdk } from '../utils/lazy'; - -interface Args { - deviceIp?: string; -} - -interface Options { - application?: string; -} - -export const join: CommandDefinition = { - signature: 'join [deviceIp]', - description: - 'Promote a local device running balenaOS to join an application on a balena server', - help: stripIndent` - Use this command to move a local device to an application on another balena server. - - For example, you could provision a device against an openBalena installation - where you perform end-to-end tests and then move it to balenaCloud when it's - ready for production. - - To move a device between applications on the same server, use the - \`balena device move\` command instead of \`balena join\`. - - If you don't specify a device hostname or IP, this command will automatically - scan the local network for balenaOS devices and prompt you to select one - from an interactive picker. This usually requires root privileges. - - Examples: - - $ balena join - $ balena join balena.local - $ balena join balena.local --application MyApp - $ balena join 192.168.1.25 - $ balena join 192.168.1.25 --application MyApp - `, - options: [ - { - signature: 'application', - parameter: 'application', - alias: 'a', - description: 'The name of the application the device should join', - }, - ], - - permission: 'user', - primary: true, - - async action(params, options) { - const Logger = await import('../utils/logger'); - const promote = await import('../utils/promote'); - const sdk = getBalenaSdk(); - const logger = Logger.getLogger(); - return promote.join(logger, sdk, params.deviceIp, options.application); - }, -}; diff --git a/lib/actions/leave.ts b/lib/actions/leave.ts deleted file mode 100644 index 7a7770fb..00000000 --- a/lib/actions/leave.ts +++ /dev/null @@ -1,56 +0,0 @@ -/* -Copyright 2016-2017 Balena - -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 { CommandDefinition } from 'capitano'; -import { stripIndent } from 'common-tags'; -import { getBalenaSdk } from '../utils/lazy'; - -interface Args { - deviceIp?: string; -} - -export const leave: CommandDefinition = { - signature: 'leave [deviceIp]', - description: 'Detach a local device from its balena application', - help: stripIndent` - Use this command to make a local device leave the balena server it is - provisioned on. This effectively makes the device "unmanaged". - - The device entry on the server is preserved after running this command, - so the device can subsequently re-join the server if needed. - - If you don't specify a device hostname or IP, this command will automatically - scan the local network for balenaOS devices and prompt you to select one - from an interactive picker. This usually requires root privileges. - - Examples: - - $ balena leave - $ balena leave balena.local - $ balena leave 192.168.1.25 - `, - options: [], - - permission: 'user', - primary: true, - - async action(params) { - const Logger = await import('../utils/logger'); - const promote = await import('../utils/promote'); - const sdk = getBalenaSdk(); - const logger = Logger.getLogger(); - return promote.leave(logger, sdk, params.deviceIp); - }, -}; diff --git a/lib/app-capitano.coffee b/lib/app-capitano.coffee index 4bf8b290..b5eb7409 100644 --- a/lib/app-capitano.coffee +++ b/lib/app-capitano.coffee @@ -125,10 +125,6 @@ capitano.command(actions.deploy) #------------ Push/remote builds ------- capitano.command(actions.push.push) -#------------ Join/Leave ------- -capitano.command(actions.join.join) -capitano.command(actions.leave.leave) - exports.run = (argv) -> cli = capitano.parse(argv.slice(2)) runCommand = -> diff --git a/lib/preparser.ts b/lib/preparser.ts index 79c4c034..e8a0bf1b 100644 --- a/lib/preparser.ts +++ b/lib/preparser.ts @@ -133,6 +133,8 @@ export const convertedCommands = [ 'env:rm', 'internal:scandevices', 'internal:osinit', + 'join', + 'leave', 'note', 'os:configure', 'settings', diff --git a/tests/commands/help.spec.ts b/tests/commands/help.spec.ts index d455860c..3c578e78 100644 --- a/tests/commands/help.spec.ts +++ b/tests/commands/help.spec.ts @@ -25,8 +25,8 @@ Primary commands: preload preload an app on a disk image (or Edison zip archive) build [source] Build a single image or a multicontainer project locally deploy [image] Deploy a single image or a multicontainer project to a balena application - join [deviceIp] Promote a local device running balenaOS to join an application on a balena server - leave [deviceIp] Detach a local device from its balena application + join [deviceiporhostname] move a local device to an application on another balena server + leave [deviceiporhostname] remove a local device from its balena application scan Scan for balenaOS devices in your local network `;