Add multicontainer (microservices) support for 'balena env rename'

Change-type: minor
Signed-off-by: Paulo Castro <paulo@balena.io>

doc/cli.markdown

@@ -790,34 +790,66 @@ service name
 
 ## env rename ID VALUE
 
-Change the value of an environment variable for an application or device,
-as selected by the '--device' option. The variable is identified by its
-database ID, rather than its name. The 'balena envs' command can be used
-to list the variable's ID.
+Change the value of a configuration or environment variable for an application,
+device or service, as selected by command-line options.
 
-Service-specific variables are not currently supported. The following
-examples modify variables that apply to all services in an app or device.
+Variables are selected by their database ID (as reported by the 'balena envs'
+command) and one of six database "resource types":
+
+- application (fleet) environment variable
+- application (fleet) configuration variable (--config)
+- application (fleet) service variable (--service)
+- device environment variable (--device)
+- device configuration variable (--device --config)
+- device service variable (--device --service)
+
+The --device option selects a device-specific variable instead of an application
+(fleet) variable.
+
+The --config option selects a configuration variable. Configuration variable
+names typically start with the 'BALENA_' or 'RESIN_' prefixes and are used to
+configure balena platform features.
+
+The --service option selects a service variable, which is an environment variable
+that applies to a specifc service (application container) in a microservices
+(multicontainer) application.
+
+The --service and --config options cannot be used together, but they can be
+used alongside the --device option to select a device-specific service or
+configuration variable.
 
 Examples:
 
-	$ balena env rename 376 emacs
-	$ balena env rename 376 emacs --device
+	$ balena env rename 123123 emacs
+	$ balena env rename 234234 emacs --service
+	$ balena env rename 345345 emacs --device
+	$ balena env rename 456456 emacs --device --service
+	$ balena env rename 567567 1 --config
+	$ balena env rename 678678 1 --device --config
 
 ### Arguments
 
 #### ID
 
-environment variable numeric database ID
+variable's numeric database ID
 
 #### VALUE
 
-variable value; if omitted, use value from CLI's environment
+variable value; if omitted, use value from this process' environment
 
 ### Options
 
+#### -c, --config
+
+select a configuration variable (may be used together with the --device option)
+
 #### -d, --device
 
-select a device variable instead of an application variable
+select a device-specific variable instead of an application (fleet) variable
+
+#### -s, --service
+
+select a service variable (may be used together with the --device option)
 
 # Tags
 

lib/actions-oclif/env/rename.ts

@@ -18,12 +18,15 @@ import { Command, flags } from '@oclif/command';
 import { stripIndent } from 'common-tags';
 
 import * as cf from '../../utils/common-flags';
+import * as ec from '../../utils/env-common';
 import { CommandHelp } from '../../utils/oclif-utils';
 
 type IArg<T> = import('@oclif/parser').args.IArg<T>;
 
 interface FlagsDef {
+	config: boolean;
 	device: boolean;
+	service: boolean;
 	help: void;
 }
 
@@ -34,51 +37,50 @@ interface ArgsDef {
 
 export default class EnvRenameCmd extends Command {
 	public static description = stripIndent`
-		Change the value of an environment variable for an app or device.
+		Change the value of a config or env var for an app, device or service.
 
-		Change the value of an environment variable for an application or device,
-		as selected by the '--device' option. The variable is identified by its
-		database ID, rather than its name. The 'balena envs' command can be used
-		to list the variable's ID.
+		Change the value of a configuration or environment variable for an application,
+		device or service, as selected by command-line options.
 
-		Service-specific variables are not currently supported. The following
-		examples modify variables that apply to all services in an app or device.
+		${ec.rmRenameHelp.split('\n').join('\n\t\t')}
 `;
 	public static examples = [
-		'$ balena env rename 376 emacs',
-		'$ balena env rename 376 emacs --device',
+		'$ balena env rename 123123 emacs',
+		'$ balena env rename 234234 emacs --service',
+		'$ balena env rename 345345 emacs --device',
+		'$ balena env rename 456456 emacs --device --service',
+		'$ balena env rename 567567 1 --config',
+		'$ balena env rename 678678 1 --device --config',
 	];
 
 	public static args: Array<IArg<any>> = [
 		{
 			name: 'id',
 			required: true,
-			description: 'environment variable numeric database ID',
-			parse: input => parseInt(input, 10),
+			description: "variable's numeric database ID",
+			parse: input => ec.parseDbId(input),
 		},
 		{
 			name: 'value',
 			required: true,
 			description:
-				"variable value; if omitted, use value from CLI's environment",
+				"variable value; if omitted, use value from this process' environment",
 		},
 	];
 
-	// hardcoded 'env add' to avoid oclif's 'env:add' topic syntax
+	// hardcoded 'env rename' to avoid oclif's 'env:rename' topic syntax
 	public static usage =
 		'env rename ' + new CommandHelp({ args: EnvRenameCmd.args }).defaultUsage();
 
 	public static flags: flags.Input<FlagsDef> = {
-		device: flags.boolean({
-			char: 'd',
-			description:
-				'select a device variable instead of an application variable',
-		}),
+		config: ec.booleanConfig,
+		device: ec.booleanDevice,
+		service: ec.booleanService,
 		help: cf.help,
 	};
 
 	public async run() {
-		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+		const { args: params, flags: opt } = this.parse<FlagsDef, ArgsDef>(
 			EnvRenameCmd,
 		);
 		const balena = (await import('balena-sdk')).fromSharedOptions();
@@ -87,9 +89,7 @@ export default class EnvRenameCmd extends Command {
 		await checkLoggedIn();
 
 		await balena.pine.patch({
-			resource: options.device
-				? 'device_environment_variable'
-				: 'application_environment_variable',
+			resource: ec.getVarResourceName(opt.config, opt.device, opt.service),
 			id: params.id,
 			body: {
 				value: params.value,

tests/commands/help.spec.ts

@@ -59,7 +59,7 @@ Additional commands:
     device shutdown <uuid>                shutdown a device
     devices supported                     list all supported devices
     env add <name> [value]                add an environment or config variable to an application, device or service
-    env rename <id> <value>               change the value of an environment variable for an app or device
+    env rename <id> <value>               change the value of a config or env var for an app, device or service
     env rm <id>                           remove a config or env var from an application, device or service
     envs                                  list the environment or config variables of an application, device or service
     key <id>                              list a single ssh key