mirror of
https://github.com/balena-io/balena-cli.git
synced 2024-12-19 13:47:52 +00:00
586 lines
17 KiB
TypeScript
586 lines
17 KiB
TypeScript
/**
|
|
* @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 Command from '../command';
|
|
import { ExpectedError } from '../errors';
|
|
import * as cf from '../utils/common-flags';
|
|
import {
|
|
getBalenaSdk,
|
|
getCliForm,
|
|
getVisuals,
|
|
stripIndent,
|
|
} from '../utils/lazy';
|
|
import {
|
|
applicationIdInfo,
|
|
appToFleetFlagMsg,
|
|
warnify,
|
|
} from '../utils/messages';
|
|
import type { DockerConnectionCliFlags } from '../utils/docker';
|
|
import { dockerConnectionCliFlags } from '../utils/docker';
|
|
import { parseAsInteger } from '../utils/validation';
|
|
import { isV13 } from '../utils/version';
|
|
|
|
import { flags } from '@oclif/command';
|
|
import * as _ from 'lodash';
|
|
import type { Application, BalenaSDK, PineExpand, Release } from 'balena-sdk';
|
|
import type { Preloader } from 'balena-preload';
|
|
|
|
interface FlagsDef extends DockerConnectionCliFlags {
|
|
app?: string;
|
|
fleet?: string;
|
|
commit?: string;
|
|
'splash-image'?: string;
|
|
'dont-check-arch': boolean;
|
|
'pin-device-to-release': boolean;
|
|
'additional-space'?: number;
|
|
'add-certificate'?: string[];
|
|
help: void;
|
|
}
|
|
|
|
interface ArgsDef {
|
|
image: string;
|
|
}
|
|
|
|
export default class PreloadCmd extends Command {
|
|
public static description = stripIndent`
|
|
Preload a release on a disk image (or Edison zip archive).
|
|
|
|
Preload a release (service images/containers) from a balena fleet, and optionally
|
|
a balenaOS splash screen, in a previously downloaded '.img' balenaOS image file
|
|
in the local disk (a zip file is only accepted for the Intel Edison device type).
|
|
After preloading, the balenaOS image file can be flashed to a device's SD card.
|
|
When the device boots, it will not need to download the release, as it was
|
|
preloaded. This is usually combined with release pinning
|
|
(https://www.balena.io/docs/learn/deploy/release-strategy/release-policy/)
|
|
to avoid the device downloading a newer release straight away, if available.
|
|
Check also the Preloading and Preregistering section of the balena CLI's advanced
|
|
masterclass document:
|
|
https://www.balena.io/docs/learn/more/masterclasses/advanced-cli/#5-preloading-and-preregistering
|
|
|
|
${applicationIdInfo.split('\n').join('\n\t\t')}
|
|
|
|
Note that the this command requires Docker to be installed, as further detailed
|
|
in the balena CLI's installation instructions:
|
|
https://github.com/balena-io/balena-cli/blob/master/INSTALL.md
|
|
The \`--dockerHost\` and \`--dockerPort\` flags allow a remote Docker engine to
|
|
be used, however the image file must be accessible to the remote Docker engine
|
|
on the same path given on the command line. This is because Docker's bind mount
|
|
feature is used to "share" the image with a container that performs the preload.
|
|
`;
|
|
|
|
public static examples = [
|
|
'$ balena preload balena.img --fleet MyFleet --commit e1f2592fc6ee949e68756d4f4a48e49bff8d72a0',
|
|
'$ balena preload balena.img --fleet myorg/myfleet --splash-image image.png',
|
|
'$ balena preload balena.img',
|
|
];
|
|
|
|
public static args = [
|
|
{
|
|
name: 'image',
|
|
description: 'the image file path',
|
|
required: true,
|
|
},
|
|
];
|
|
|
|
public static usage = 'preload <image>';
|
|
|
|
public static flags: flags.Input<FlagsDef> = {
|
|
...(isV13() ? {} : { app: cf.application }),
|
|
fleet: cf.fleet,
|
|
commit: flags.string({
|
|
description: `\
|
|
The commit hash of the release to preload. Use "current" to specify the current
|
|
release (ignored if no appId is given). The current release is usually also the
|
|
latest, but can be pinned to a specific release. See:
|
|
https://www.balena.io/docs/learn/deploy/release-strategy/release-policy/
|
|
https://www.balena.io/docs/learn/more/masterclasses/fleet-management/#63-pin-using-the-api
|
|
https://github.com/balena-io-examples/staged-releases\
|
|
`,
|
|
char: 'c',
|
|
}),
|
|
'splash-image': flags.string({
|
|
description: 'path to a png image to replace the splash screen',
|
|
char: 's',
|
|
}),
|
|
'dont-check-arch': flags.boolean({
|
|
default: false,
|
|
description:
|
|
'disable architecture compatibility check between image and fleet',
|
|
}),
|
|
'pin-device-to-release': flags.boolean({
|
|
default: false,
|
|
description:
|
|
'pin the preloaded device to the preloaded release on provision',
|
|
char: 'p',
|
|
}),
|
|
'additional-space': flags.integer({
|
|
description:
|
|
'expand the image by this amount of bytes instead of automatically estimating the required amount',
|
|
parse: (x) => parseAsInteger(x, 'additional-space'),
|
|
}),
|
|
'add-certificate': flags.string({
|
|
description: `\
|
|
Add the given certificate (in PEM format) to /etc/ssl/certs in the preloading container.
|
|
The file name must end with '.crt' and must not be already contained in the preloader's
|
|
/etc/ssl/certs folder.
|
|
Can be repeated to add multiple certificates.\
|
|
`,
|
|
multiple: true,
|
|
}),
|
|
...dockerConnectionCliFlags,
|
|
// Redefining --dockerPort here (defined already in dockerConnectionCliFlags)
|
|
// without -p alias, to avoid clash with -p alias of pin-device-to-release
|
|
dockerPort: flags.integer({
|
|
description:
|
|
'Docker daemon TCP port number (hint: 2375 for balena devices)',
|
|
parse: (p) => parseAsInteger(p, 'dockerPort'),
|
|
}),
|
|
// Not supporting -h for help, because of clash with -h in DockerCliFlags
|
|
// Revisit this in future release.
|
|
help: flags.help({}),
|
|
};
|
|
|
|
public static authenticated = true;
|
|
|
|
public static primary = true;
|
|
|
|
public async run() {
|
|
const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
|
|
PreloadCmd,
|
|
);
|
|
|
|
if (options.app && process.stderr.isTTY) {
|
|
console.error(warnify(appToFleetFlagMsg));
|
|
}
|
|
options.app ||= options.fleet;
|
|
|
|
const balena = getBalenaSdk();
|
|
const balenaPreload = await import('balena-preload');
|
|
const visuals = getVisuals();
|
|
const nodeCleanup = await import('node-cleanup');
|
|
const { instanceOf } = await import('../errors');
|
|
|
|
// Check image file exists
|
|
try {
|
|
const fs = await import('fs');
|
|
await fs.promises.access(params.image);
|
|
const path = await import('path');
|
|
if (path.extname(params.image) === '.zip') {
|
|
console.warn(stripIndent`
|
|
------------------------------------------------------------------------------
|
|
Warning: A zip file is only accepted for the Intel Edison device type.
|
|
------------------------------------------------------------------------------
|
|
`);
|
|
}
|
|
} catch (error) {
|
|
throw new ExpectedError(
|
|
`The provided image path does not exist: ${params.image}`,
|
|
);
|
|
}
|
|
|
|
// balena-preload currently does not work with numerical app IDs
|
|
// Load app here, and use app slug from hereon
|
|
if (options.app && !options.app.includes('/')) {
|
|
// Disambiguate application (if is a number, it could either be an ID or a numerical name)
|
|
const { getApplication } = await import('../utils/sdk');
|
|
const application = await getApplication(balena, options.app);
|
|
if (!application) {
|
|
throw new ExpectedError(`Fleet not found: ${options.app}`);
|
|
}
|
|
options.app = application.slug;
|
|
}
|
|
|
|
const progressBars: {
|
|
[key: string]: ReturnType<typeof getVisuals>['Progress'];
|
|
} = {};
|
|
|
|
const progressHandler = function (event: {
|
|
name: string;
|
|
percentage: number;
|
|
}) {
|
|
const progressBar = (progressBars[event.name] ??= new visuals.Progress(
|
|
event.name,
|
|
));
|
|
return progressBar.update({ percentage: event.percentage });
|
|
};
|
|
|
|
const spinners: {
|
|
[key: string]: ReturnType<typeof getVisuals>['Spinner'];
|
|
} = {};
|
|
|
|
const spinnerHandler = function (event: { name: string; action: string }) {
|
|
const spinner = (spinners[event.name] ??= new visuals.Spinner(
|
|
event.name,
|
|
));
|
|
if (event.action === 'start') {
|
|
return spinner.start();
|
|
} else {
|
|
console.log();
|
|
return spinner.stop();
|
|
}
|
|
};
|
|
|
|
const commit = this.isCurrentCommit(options.commit || '')
|
|
? 'latest'
|
|
: options.commit;
|
|
const image = params.image;
|
|
const appId = options.app;
|
|
|
|
const splashImage = options['splash-image'];
|
|
const additionalSpace = options['additional-space'];
|
|
|
|
const dontCheckArch = options['dont-check-arch'] || false;
|
|
const pinDevice = options['pin-device-to-release'] || false;
|
|
|
|
if (dontCheckArch && !appId) {
|
|
throw new ExpectedError(
|
|
'You need to specify a fleet if you disable the architecture check.',
|
|
);
|
|
}
|
|
|
|
const certificates: string[] = options['add-certificate'] || [];
|
|
for (const certificate of certificates) {
|
|
if (!certificate.endsWith('.crt')) {
|
|
throw new ExpectedError('Certificate file name must end with ".crt"');
|
|
}
|
|
}
|
|
|
|
// Get a configured dockerode instance
|
|
const dockerUtils = await import('../utils/docker');
|
|
const docker = await dockerUtils.getDocker(options);
|
|
const preloader = new balenaPreload.Preloader(
|
|
null,
|
|
docker,
|
|
appId,
|
|
commit,
|
|
image,
|
|
splashImage,
|
|
undefined, // TODO: Currently always undefined, investigate approach in ssh command.
|
|
dontCheckArch,
|
|
pinDevice,
|
|
certificates,
|
|
additionalSpace,
|
|
);
|
|
|
|
let gotSignal = false;
|
|
|
|
nodeCleanup(function (_exitCode, signal) {
|
|
if (signal) {
|
|
gotSignal = true;
|
|
nodeCleanup.uninstall(); // don't call cleanup handler again
|
|
preloader
|
|
.cleanup()
|
|
.then(() => {
|
|
// calling process.exit() won't inform parent process of signal
|
|
process.kill(process.pid, signal);
|
|
})
|
|
.catch((e) => {
|
|
if (process.env.DEBUG) {
|
|
console.error(e);
|
|
}
|
|
});
|
|
return false;
|
|
}
|
|
});
|
|
|
|
if (process.env.DEBUG) {
|
|
preloader.stderr.pipe(process.stderr);
|
|
}
|
|
|
|
preloader.on('progress', progressHandler);
|
|
preloader.on('spinner', spinnerHandler);
|
|
|
|
try {
|
|
await new Promise((resolve, reject) => {
|
|
preloader.on('error', reject);
|
|
resolve(
|
|
this.prepareAndPreload(preloader, balena, {
|
|
appId,
|
|
commit,
|
|
pinDevice,
|
|
}),
|
|
);
|
|
});
|
|
} catch (err) {
|
|
if (instanceOf(err, balena.errors.BalenaError)) {
|
|
const code = err.code ? `(${err.code})` : '';
|
|
throw new ExpectedError(`${err.message} ${code}`);
|
|
} else {
|
|
throw err;
|
|
}
|
|
} finally {
|
|
if (!gotSignal) {
|
|
await preloader.cleanup();
|
|
}
|
|
}
|
|
}
|
|
|
|
readonly applicationExpandOptions: PineExpand<Application> = {
|
|
owns__release: {
|
|
$select: ['id', 'commit', 'end_timestamp', 'composition'],
|
|
$expand: {
|
|
contains__image: {
|
|
$select: ['image'],
|
|
$expand: {
|
|
image: {
|
|
$select: ['image_size', 'is_stored_at__image_location'],
|
|
},
|
|
},
|
|
},
|
|
},
|
|
$filter: {
|
|
status: 'success',
|
|
},
|
|
$orderby: [{ end_timestamp: 'desc' }, { id: 'desc' }],
|
|
},
|
|
should_be_running__release: {
|
|
$select: 'commit',
|
|
},
|
|
};
|
|
|
|
isCurrentCommit(commit: string) {
|
|
return commit === 'latest' || commit === 'current';
|
|
}
|
|
|
|
async getApplicationsWithSuccessfulBuilds(deviceTypeSlug: string) {
|
|
const balena = getBalenaSdk();
|
|
|
|
try {
|
|
await balena.models.deviceType.get(deviceTypeSlug);
|
|
} catch {
|
|
throw new Error(`Device type "${deviceTypeSlug}" not found in API query`);
|
|
}
|
|
return (await balena.models.application.getAll({
|
|
$select: ['id', 'app_name', 'should_track_latest_release'],
|
|
$expand: this.applicationExpandOptions,
|
|
$filter: {
|
|
// get the apps that are of the same arch as the device type of the image
|
|
is_for__device_type: {
|
|
$any: {
|
|
$alias: 'dt',
|
|
$expr: {
|
|
dt: {
|
|
is_of__cpu_architecture: {
|
|
$any: {
|
|
$alias: 'ioca',
|
|
$expr: {
|
|
ioca: {
|
|
is_supported_by__device_type: {
|
|
$any: {
|
|
$alias: 'isbdt',
|
|
$expr: {
|
|
isbdt: {
|
|
slug: deviceTypeSlug,
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
owns__release: {
|
|
$any: {
|
|
$alias: 'r',
|
|
$expr: {
|
|
r: {
|
|
status: 'success',
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
$orderby: 'app_name asc',
|
|
})) as Array<
|
|
ApplicationWithDeviceType & {
|
|
should_be_running__release: [Release?];
|
|
}
|
|
>;
|
|
}
|
|
|
|
async selectApplication(deviceTypeSlug: string) {
|
|
const visuals = getVisuals();
|
|
|
|
const applicationInfoSpinner = new visuals.Spinner(
|
|
'Downloading list of applications and releases.',
|
|
);
|
|
applicationInfoSpinner.start();
|
|
|
|
const applications = await this.getApplicationsWithSuccessfulBuilds(
|
|
deviceTypeSlug,
|
|
);
|
|
applicationInfoSpinner.stop();
|
|
if (applications.length === 0) {
|
|
throw new ExpectedError(
|
|
`No fleets found with successful releases for device type '${deviceTypeSlug}'`,
|
|
);
|
|
}
|
|
return getCliForm().ask({
|
|
message: 'Select a fleet',
|
|
type: 'list',
|
|
choices: applications.map((app) => ({
|
|
name: app.app_name,
|
|
value: app,
|
|
})),
|
|
});
|
|
}
|
|
|
|
selectApplicationCommit(releases: Release[]) {
|
|
if (releases.length === 0) {
|
|
throw new ExpectedError('This fleet has no successful releases.');
|
|
}
|
|
const DEFAULT_CHOICE = { name: 'current', value: 'current' };
|
|
const choices = [DEFAULT_CHOICE].concat(
|
|
releases.map((release) => ({
|
|
name: `${release.end_timestamp} - ${release.commit}`,
|
|
value: release.commit,
|
|
})),
|
|
);
|
|
return getCliForm().ask({
|
|
message: 'Select a release',
|
|
type: 'list',
|
|
default: 'current',
|
|
choices,
|
|
});
|
|
}
|
|
|
|
async offerToDisableAutomaticUpdates(
|
|
application: Application,
|
|
commit: string,
|
|
pinDevice: boolean,
|
|
) {
|
|
const balena = getBalenaSdk();
|
|
|
|
if (
|
|
this.isCurrentCommit(commit) ||
|
|
!application.should_track_latest_release ||
|
|
pinDevice
|
|
) {
|
|
return;
|
|
}
|
|
const message = `\
|
|
|
|
This fleet is set to track the latest release, and non-pinned devices
|
|
are automatically updated when a new release is available. This may lead to
|
|
unexpected behavior: The preloaded device will download and install the latest
|
|
release once it is online.
|
|
|
|
This prompt gives you the opportunity to disable automatic updates for
|
|
this fleet now. Note that this would result in the fleet being pinned to
|
|
the current latest release, rather than some other release that may have
|
|
been selected for preloading. The pinned released may be further managed
|
|
through the web dashboard or programatically through the balena API / SDK.
|
|
Documentation about release policies and pinning can be found at:
|
|
https://www.balena.io/docs/learn/deploy/release-strategy/release-policy/
|
|
|
|
Alternatively, the --pin-device-to-release flag may be used to pin only the
|
|
preloaded device to the selected release.
|
|
|
|
Would you like to disable automatic updates for this fleet now?\
|
|
`;
|
|
const update = await getCliForm().ask({
|
|
message,
|
|
type: 'confirm',
|
|
});
|
|
if (!update) {
|
|
return;
|
|
}
|
|
return await balena.pine.patch({
|
|
resource: 'application',
|
|
id: application.id,
|
|
body: {
|
|
should_track_latest_release: false,
|
|
},
|
|
});
|
|
}
|
|
|
|
async getAppWithReleases(balenaSdk: BalenaSDK, appId: string | number) {
|
|
const { getApplication } = await import('../utils/sdk');
|
|
|
|
return (await getApplication(balenaSdk, appId, {
|
|
$expand: this.applicationExpandOptions,
|
|
})) as Application & { should_be_running__release: [Release?] };
|
|
}
|
|
|
|
async prepareAndPreload(
|
|
preloader: Preloader,
|
|
balenaSdk: BalenaSDK,
|
|
options: {
|
|
appId?: string;
|
|
commit?: string;
|
|
pinDevice: boolean;
|
|
},
|
|
) {
|
|
await preloader.prepare();
|
|
|
|
const application = options.appId
|
|
? await this.getAppWithReleases(balenaSdk, options.appId)
|
|
: await this.selectApplication(preloader.config.deviceType);
|
|
|
|
let commit: string; // commit hash or the strings 'latest' or 'current'
|
|
|
|
const appCommit = application.should_be_running__release[0]?.commit;
|
|
|
|
// Use the commit given as --commit or show an interactive commit selection menu
|
|
if (options.commit) {
|
|
if (this.isCurrentCommit(options.commit)) {
|
|
if (!appCommit) {
|
|
throw new Error(
|
|
`Unexpected empty commit hash for fleet ID "${application.id}"`,
|
|
);
|
|
}
|
|
// handle `--commit current` (and its `--commit latest` synonym)
|
|
commit = 'latest';
|
|
} else {
|
|
const release = _.find(application.owns__release, (r) =>
|
|
r.commit.startsWith(options.commit!),
|
|
);
|
|
if (!release) {
|
|
throw new ExpectedError(
|
|
`There is no release matching commit "${options.commit}"`,
|
|
);
|
|
}
|
|
commit = release.commit;
|
|
}
|
|
} else {
|
|
// this could have the value 'current'
|
|
commit = await this.selectApplicationCommit(
|
|
application.owns__release as Release[],
|
|
);
|
|
}
|
|
|
|
await preloader.setAppIdAndCommit(
|
|
application.id,
|
|
this.isCurrentCommit(commit) ? appCommit! : commit,
|
|
);
|
|
|
|
// Propose to disable automatic app updates if the commit is not the current release
|
|
await this.offerToDisableAutomaticUpdates(
|
|
application,
|
|
commit,
|
|
options.pinDevice,
|
|
);
|
|
|
|
// All options are ready: preload the image.
|
|
await preloader.preload();
|
|
}
|
|
}
|