Software Deploy Prestage of Metapackage Deployments on Subclouds¶

The software deploy prestage command is introduced in StarlingX r13 for future support of dcmanager orchestration of prestaging metapackage-type deployments. Future dcmanager prestaging of subclouds will use the software upload command for product-level deployments and software deploy prestage for metapackage-level deployments.

Warning

The software deploy prestage command is for internal use only and must NOT be executed manually. Although the command is accessible from the CLI, this command should NOT be issued directly. To prestage subclouds, use the dcmanager subcloud prestage command or the prestage orchestration strategy instead. See Prestage a Subcloud and Orchestrate Subcloud Prestage Using the CLI.

Prerequisites

The product-level releases (patches or ISOs) that contain the metapackage releases must be uploaded to the subcloud using the software upload process.

Overview

The software deploy prestage command pre-builds a software image containing a specified subset of metapackages from a product release, on top of a specified earlier product release. This prepares the system for the subsequent software deployment (i.e., sw-manager sw-deploy-strategy create/apply) of this metapackage-specific deployment.

The pre-building of the software image is a non-service-affecting lengthy command (several minutes), so using the software deploy prestage allows you to perform this command before the time-constrained main software deployment maintenance window.

The software image build process is a lengthy, non-service-affecting operation that can take several minutes to complete. Using the software deploy prestage command allows this process to be performed in advance, reducing the time required during the main software deployment maintenance window.

This command supports three modes of operation:

Metapackage overrides (--metapackage-overrides): Installs the specified metapackages from a patch release on top of the target product release. This is used to selectively apply specific patch release metapackages to the subcloud before the patch apply workflow.
Pre-upgrade deploy (--pre-upgrade-deploy): Installs metapackages from a major release on top of the target product release, preparing the subcloud for a major software upgrade.
Restore (--restore): Removes the prestaging metapackages added to a specific release based on previous software deploy prestage executions.

Run the software deploy prestage command on the subcloud.

Note

Only one of the following parameters can be specified in a single execution: –metapackage-overrides, –pre-upgrade-deploy, or –restore. These parameters are mutually exclusive and cannot be used together.

Install Metapackages with –metapackage-overrides

To install specific metapackages from a patch release on top of the target product release, use the --metapackage-overrides parameter followed by the target release and one or more metapackage names:

~(keystone_admin)]$ software deploy prestage <release-id> --metapackage-overrides <metapackage> [<metapackage> ...]

For example, to install a single metapackage from a patch release on top of the base release:

~(keystone_admin)]$ software deploy prestage StarlingX-nn.nn.0 --metapackage-overrides infra_nn.nn.nnn

Where nn.nn.nnn represents the target future release version.

To install multiple metapackages from a same patch release:

~(keystone_admin)]$ software deploy prestage StarlingX-nn.nn.0 --metapackage-overrides infra_nn.nn.nnn swmgmt_nn.nn.nnn

Note

The target product release specified in the command must be in deployed or available state. Verify using the software list command.

For --metapackage-overrides:

The command can only be executed between patch releases that are immediately consecutive (e.g., from StarlingX r13 to a future patch release).
All metapackages passed must belong to the same product release.
The product release associated with the metapackages must have its requires field set to either the target product release or the currently deployed release.

Install Metapackages with –pre-upgrade-deploy

To install the internally-defined pre-upgrade-deploy metapackages from a major release on top of the target product release in preparation for a major software upgrade, use the following command:

~(keystone_admin)]$ software deploy prestage <release-id> --pre-upgrade-deploy

For example:

~(keystone_admin)]$ software deploy prestage StarlingX-nn.nn --pre-upgrade-deploy

Note

For --pre-upgrade-deploy, the <release-id> must be the ‘new’ major product release that you are preparing to upgrade to.

Remove Prestaged Metapackages with –restore

To remove the metapackage prestaged for a specified release by a previous software deploy prestage execution, use the --restore parameter with the target release:

~(keystone_admin)]$ software deploy prestage <release-id> --restore

For example:

~(keystone_admin)]$ software deploy prestage StarlingX-nn.nn.0 --restore

Postrequisites

After the software deploy prestage command completes successfully, the applicable prestaged deployment can be done in the upcoming software deployment maintenance window. For example:

~(keystone_admin)]$ sw-manager sw-deploy-strategy create infra_nn.nn.nnn swmgmt_nn.nn.nnn

~(keystone_admin)]$ sw-manager sw-deploy-strategy create StarlingX-nn.nn --pre-upgrade-deploy

Command Behavior and Usage Semantics¶

The software deploy prestage command has the following properties:

Absolute, idempotent, and atomic: The command is absolute, idempotent, and atomic. If executed for the first time, a new set of metapackages is installed on top of the specified product release. If executed a second time, the metapackages installed by the first execution are removed and replaced by the metapackages from the second execution. This ensures the system always reflects the latest invocation.
Mutually exclusive parameters: The --metapackage-overrides, --pre-upgrade-deploy and --restore parameters are mutually exclusive. One parameter must be specified for each execution.
Patch release constraints for –metapackage-overrides: When using --metapackage-overrides, the command can only be executed between immediately consecutive patch releases. All metapackages specified must belong to the same product release. Skipping releases is not allowed.
Cross-release support for –pre-upgrade-deploy: The --pre-upgrade-deploy parameter allows execution across different product releases, enabling preparation for a major software upgrade.

Troubleshoot Deploy Prestage¶

If the software deploy prestage command fails:

Check /var/log/software.log on the subcloud for failure details.
Verify that the target release is in deployed or available state using the software list command.
Ensure the metapackages specified are valid and belong to the same product release (for --metapackage-overrides).
After resolving the issue, re-execute the command. Since the command is idempotent, it will replace any partial state from the previous execution.