From 90e184ea1fff3940dad3236115fb6a7f8a671e7e Mon Sep 17 00:00:00 2001 From: Paulo Castro Date: Tue, 10 Dec 2019 00:07:16 +0000 Subject: [PATCH] Add multicontainer (microservices) support for 'balena env add' Change-type: minor Signed-off-by: Paulo Castro --- doc/cli.markdown | 29 ++++++-- lib/actions-oclif/env/add.ts | 131 ++++++++++++++++++++++++++++++----- tests/commands/help.spec.ts | 2 +- 3 files changed, 140 insertions(+), 22 deletions(-) diff --git a/doc/cli.markdown b/doc/cli.markdown index a35eae86..bc9f416a 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -704,21 +704,36 @@ Run in non-interactive mode ## env add NAME [VALUE] -Add an environment or config variable to an application or device, as selected -by the respective command-line options. +Add an environment or config variable to an application, device or service, +as selected by the respective command-line options. Either the --application +or the --device option must be provided, and either may be be used alongside +the --service option to define a service-specific variable. (A service is an +application container in a "microservices" application.) When the --service +option is used in conjunction with the --device option, the service variable +applies to the selected device only. Otherwise, it applies to all devices of +the selected application (i.e., the application's fleet). If the --service +option is omitted, the variable applies to all services. If VALUE is omitted, the CLI will attempt to use the value of the environment variable of same name in the CLI process' environment. In this case, a warning message will be printed. Use `--quiet` to suppress it. -Service-specific variables are not currently supported. The given command line -examples variables that apply to all services in an app or device. +'BALENA_' or 'RESIN_' are reserved variable name prefixes used to identify +"configuration variables". Configuration variables control balena platform +features and are treated specially by balenaOS and the balena supervisor +running on devices. They are also stored differently in the balenaCloud API +database. Configuration variables cannot be set for specific services, +therefore the --service option cannot be used when the variable name starts +with a reserved prefix. When defining custom application variables, please +avoid the reserved prefixes. Examples: $ balena env add TERM --application MyApp $ balena env add EDITOR vim --application MyApp + $ balena env add EDITOR vim --application MyApp --service MyService $ balena env add EDITOR vim --device 7cf02a6 + $ balena env add EDITOR vim --device 7cf02a6 --service MyService ### Arguments @@ -728,7 +743,7 @@ environment or config variable name #### VALUE -variable value; if omitted, use value from CLI's environment +variable value; if omitted, use value from this process' environment ### Options @@ -744,6 +759,10 @@ device UUID suppress warning messages +#### -s, --service SERVICE + +service name + ## env rename ID VALUE Change the value of an environment variable for an application or device, diff --git a/lib/actions-oclif/env/add.ts b/lib/actions-oclif/env/add.ts index 155d6f02..c42b2f11 100644 --- a/lib/actions-oclif/env/add.ts +++ b/lib/actions-oclif/env/add.ts @@ -16,6 +16,7 @@ */ import { Command, flags } from '@oclif/command'; +import * as BalenaSdk from 'balena-sdk'; import { stripIndent } from 'common-tags'; import * as _ from 'lodash'; @@ -24,10 +25,11 @@ import * as cf from '../../utils/common-flags'; import { CommandHelp } from '../../utils/oclif-utils'; interface FlagsDef { - application?: string; - device?: string; + application?: string; // application name + device?: string; // device UUID help: void; quiet: boolean; + service?: string; // service name } interface ArgsDef { @@ -37,22 +39,37 @@ interface ArgsDef { export default class EnvAddCmd extends Command { public static description = stripIndent` - Add an environment or config variable to an application or device. + Add an environment or config variable to an application, device or service. - Add an environment or config variable to an application or device, as selected - by the respective command-line options. + Add an environment or config variable to an application, device or service, + as selected by the respective command-line options. Either the --application + or the --device option must be provided, and either may be be used alongside + the --service option to define a service-specific variable. (A service is an + application container in a "microservices" application.) When the --service + option is used in conjunction with the --device option, the service variable + applies to the selected device only. Otherwise, it applies to all devices of + the selected application (i.e., the application's fleet). If the --service + option is omitted, the variable applies to all services. If VALUE is omitted, the CLI will attempt to use the value of the environment variable of same name in the CLI process' environment. In this case, a warning message will be printed. Use \`--quiet\` to suppress it. - Service-specific variables are not currently supported. The given command line - examples variables that apply to all services in an app or device. + 'BALENA_' or 'RESIN_' are reserved variable name prefixes used to identify + "configuration variables". Configuration variables control balena platform + features and are treated specially by balenaOS and the balena supervisor + running on devices. They are also stored differently in the balenaCloud API + database. Configuration variables cannot be set for specific services, + therefore the --service option cannot be used when the variable name starts + with a reserved prefix. When defining custom application variables, please + avoid the reserved prefixes. `; public static examples = [ '$ balena env add TERM --application MyApp', '$ balena env add EDITOR vim --application MyApp', + '$ balena env add EDITOR vim --application MyApp --service MyService', '$ balena env add EDITOR vim --device 7cf02a6', + '$ balena env add EDITOR vim --device 7cf02a6 --service MyService', ]; public static args = [ @@ -65,7 +82,7 @@ export default class EnvAddCmd extends Command { name: 'value', required: false, description: - "variable value; if omitted, use value from CLI's environment", + "variable value; if omitted, use value from this process' environment", }, ]; @@ -78,6 +95,7 @@ export default class EnvAddCmd extends Command { device: _.assign({ exclusive: ['application'] }, cf.device), help: cf.help, quiet: cf.quiet, + service: cf.service, }; public async run() { @@ -88,6 +106,12 @@ export default class EnvAddCmd extends Command { const balena = (await import('balena-sdk')).fromSharedOptions(); const { checkLoggedIn } = await import('../../utils/patterns'); + if (!options.application && !options.device) { + throw new ExpectedError( + 'Either the --application or the --device option must always be used', + ); + } + await checkLoggedIn(); if (params.value == null) { @@ -95,7 +119,7 @@ export default class EnvAddCmd extends Command { if (params.value == null) { throw new Error( - `Environment value not found for variable: ${params.name}`, + `Value not found for environment variable: ${params.name}`, ); } else if (!options.quiet) { cmd.warn( @@ -104,12 +128,25 @@ export default class EnvAddCmd extends Command { } } - const reservedPrefixes = await getReservedPrefixes(); + const reservedPrefixes = await getReservedPrefixes(balena); const isConfigVar = _.some(reservedPrefixes, prefix => _.startsWith(params.name, prefix), ); - const varType = isConfigVar ? 'configVar' : 'envVar'; + if (options.service) { + if (isConfigVar) { + throw new ExpectedError(stripIndent` + Configuration variables prefixed with "${reservedPrefixes.join( + '" or "', + )}" cannot be set per service. + Hint: remove the --service option or rename the variable. + `); + } + await setServiceVars(balena, params, options); + return; + } + + const varType = isConfigVar ? 'configVar' : 'envVar'; if (options.application) { await balena.models.application[varType].set( options.application, @@ -122,16 +159,78 @@ export default class EnvAddCmd extends Command { params.name, params.value, ); - } else { - throw new ExpectedError('You must specify an application or device'); } } } -async function getReservedPrefixes(): Promise { - const balena = (await import('balena-sdk')).fromSharedOptions(); - const settings = await balena.settings.getAll(); +/** + * Add service variables for a device or application. + */ +async function setServiceVars( + sdk: BalenaSdk.BalenaSDK, + params: ArgsDef, + options: FlagsDef, +) { + if (options.application) { + const serviceId = await getServiceIdForApp( + sdk, + options.application, + options.service!, + ); + await sdk.models.service.var.set(serviceId, params.name, params.value!); + } else { + const { getDeviceAndAppFromUUID } = await import('../../utils/cloud'); + const [device, app] = await getDeviceAndAppFromUUID( + sdk, + options.device!, + ['id'], + ['app_name'], + ); + const serviceId = await getServiceIdForApp( + sdk, + app.app_name, + options.service!, + ); + await sdk.models.device.serviceVar.set( + device.id, + serviceId, + params.name, + params.value!, + ); + } +} +/** + * Return a sevice ID for the given app name and service name. + */ +async function getServiceIdForApp( + sdk: BalenaSdk.BalenaSDK, + appName: string, + serviceName: string, +): Promise { + let serviceId: number | undefined; + const services = await sdk.models.service.getAllByApplication(appName, { + $filter: { service_name: serviceName }, + }); + if (!_.isEmpty(services)) { + serviceId = services[0].id; + } + if (serviceId === undefined) { + throw new ExpectedError( + `Cannot find service ${serviceName} for application ${appName}`, + ); + } + return serviceId; +} + +/** + * Return an array of variable name prefixes like: [ 'RESIN_', 'BALENA_' ]. + * These prefixes can be used to identify "configuration variables". + */ +async function getReservedPrefixes( + balena: BalenaSdk.BalenaSDK, +): Promise { + const settings = await balena.settings.getAll(); const response = await balena.request.send({ baseUrl: settings.apiUrl, url: '/config/vars', diff --git a/tests/commands/help.spec.ts b/tests/commands/help.spec.ts index b01fb061..aca380a6 100644 --- a/tests/commands/help.spec.ts +++ b/tests/commands/help.spec.ts @@ -58,7 +58,7 @@ Additional commands: device rm remove a device device shutdown shutdown a device devices supported list all supported devices - env add [value] add an environment or config variable to an application or device + env add [value] add an environment or config variable to an application, device or service env rename change the value of an environment variable for an app or device env rm remove an environment variable from an application or device envs list the environment or config variables of an application, device or service