Deploy, Restore, and Manage Subclouds of Previous Release

Starting with StarlingX r8 and subsequent releases, you can now install, restore, and manage subclouds of the previous software release. This capability can be used to revert to the previous release when an unforeseen issue is encountered during a subcloud upgrade or deployment.

Note

This capability is not available for StarlingX r7. If the system controller is on StarlingX r8, subclouds can be deployed or restored to either StarlingX r8 or StarlingX r6.

About this task

This section describes the steps for deploying, restoring, and managing subclouds of the previous release.

Operations Supported for Subclouds of Previous Release

  • New subcloud deployment

  • Subcloud re-install

  • Subcloud backup removal

  • Subcloud restore from backup

  • Subcloud prestage (single subcloud)

  • Orchestrated subcloud prestage (multiple subclouds)

  • Subcloud rehome

  • Deploy files upload/show

Note

After deployment, subclouds running the previous release can be managed, unmanaged, audited, updated, upgraded, or deleted in the same way as subclouds running the current release.

Operations with Limited Support for Subclouds of Previous Release

  • Subcloud Backup

    Limitation: The option to exclude the /opt/patching directory from the backup, which helps to reduce the backup size, does not apply to subclouds operating on StarlingX r6. For additional details on the list of configurable system backup parameters and to identify the specific parameter(s) that do not apply to StarlingX r6 subclouds, see Run Ansible Backup Playbook Locally on the Controller.

Warning

Ensure that the RECONCILED state of each host is true before creating a subcloud backup.

You cannot create a backup for a subcloud in a failed state when running an upgrade from StarlingX r6 to StarlingX r8.

Use the following command to verify the RECONCILED state.

kubectl get hosts -n deployment

  • Subcloud Error Reporting

    Limitation: In the event of a failure during subcloud install, bootstrap, deployment, backup, restore, or upgrade, you can use the dcmanager subcloud errors command to obtain detailed information about the failure.

    The error reporting for backup and restore failures may vary depending on the release version. For example, in the case of a backup failure during a subcloud upgrade due to insufficient disk space, a StarlingX r8 subcloud will generate a generic error report stating, Failed to generate upgrade data. Please check sysinv.log on the subcloud for details. The same failure on StarlingX r8 subcloud would give a more detailed error report such as, Not enough free space in /opt/platform-backup. It has 2010876KiB. It needs at least 3558912KiB.

Operations Not Supported for Subclouds of Previous Release

  • Orchestrated subcloud kubernetes upgrade

  • Orchestrated subcloud firmware update

  • Orchestrated subcloud patching

  • Admin network configuration

Prerequisites

To support subcloud install or subcloud restore to either the current (N) or previous (N-1) release, ensure that the following prerequisites are met:

  • The N load (pre-patched ISO) containing this capability must be imported to the system controller using the --active option. The ISO imported via load-import --active should be at the same patch level as the system controller. This requirement ensures that the subcloud boot image is aligned with the patch level of the load to be installed on the subcloud.

    Note

    Each time a new patch is applied on the system controller, it is necessary to re-import the new pre-patched ISO containing the same patch(es).

  • The N-1 load (pre-patched ISO) must be imported to the system controller using the --inactive option. This load must be upgradable to the current active release.

    Warning

    A subcloud running the N-1 release cannot be patched using patch orchestration. To deploy a subcloud with the latest patch of N-1 release, the N-1 release ISO containing the latest patch must be imported using the following command:

    ~(keystone_admin)]$ sw-patch –os-region-name SystemController load-import --inactive <bootimage>.iso <bootimage>.sig

  • The central registry (or source registry configured for the subclouds) must contain platform and applications container images of both N and N-1 releases.

  • Subcloud install values, bootstrap values, and deploy config files must be compatible with the release the subcloud is being deployed to.

    Warning

    Since orchestrated Kubernetes upgrades are not supported for subclouds running the previous release, these subclouds must be deployed with the highest Kubernetes version for that release. Do not set the kubernetes_version value in subcloud bootstrap-values.yaml when deploying a new N-1 subcloud. If this value is not the highest Kubernetes version, the subcloud add request will be rejected.

    Warning

    If a subcloud was initially deployed in one release and re-deployed to a different release, ensure that persistent_size value in the subcloud install values is equal to or greater than persistent_size specified in the previous deployment. Failing to do so may result in a subcloud installation failure, as the persistent /opt/platform-backup partition cannot be reduced in size.

  • If the system controller was installed with default settings, it will use the latest Kubernetes version for the release it’s running. To support upgrading the subcloud, ensure that the system controller has locally stored copies (caches) of container images for all the previous versions of Kubernetes relevant to the platform release. For example, if the system controlle r is installed with Kubernetes 1.24, we need to ensure that all the system images related to Kubernetes 1.21, 1.22, and 1.23 are stored locally (cached) on the system controller for use when the subcloud tries to upgrade to those versions.

    To obtain more information about the list of images, see the corresponding pre-build ISO and docker images section for StarlingX r6 and r8.

Import an Inactive Load

An inactive load can be imported using the --inactive option with the load-import command to allow the import of the previous release load on the system controller.

Note

Ensure that the imported ISO is at the same patch level as the system controller. To check the system controller patch level of N and/or N-1 release, use the sw-patch query command.

Procedure

  1. Transfer the pre-patched ISO of the previous release and its signature file to the system controller.

  2. Run the following command.

    ~(keystone_admin)]$ system --os-region-name SystemController load-import --inactive --local <bootimage>.iso <bootimage>.sig

Note

load-import --inactive is not rejected when importing a non-upgradable load. The inactive load must be a pre-patched ISO with StarlingX r6 or above.

Upload Deploy/Prestage files

Use the dcmanager subcloud-deploy upload command with the --release option to upload deploy or prestage artifacts for a specific release version.

Procedure

  1. To upload deploy files use dcmanager subcloud-deploy upload command with --deploy-playbook, --deploy-chart and --deploy-overrides options. The following command uploads deploy files for StarlingX r8:

    ~(keystone_admin)]$ dcmanager subcloud-deploy upload
--deploy-playbook <deployment-manager-yaml-file>
--deploy-chart <deployment-manager-chart-tarball>
--deploy-overrides <deployment-manager-overrides-subcloud-yaml-file>
--release <xx.xx>

    Where, <xx.xx> is the StarlingX r8 version.

    Note

    The deploy files for N-1 release are automatically uploaded when running the system --os-region-name SystemController load-import --inactive command. It is not mandatory to upload deploy files for the N release. If the deploy files are not uploaded, the software will use the default deploy files included in the active load.

  2. To upload prestage images list use dcmanager subcloud-deploy upload command with --prestage-images option. The following command uploads the images list for StarlingX r6:

    ~(keystone_admin)]$ dcmanager subcloud-deploy upload --prestage-images <images-list-file> --release <xx.xx>

    Where, <xx.xx> is the StarlingX r6 version.

  3. View uploaded files for a particular release.

    ~(keystone_admin)]$ dcmanager subcloud-deploy show
--release <previous_or_current_release_number>

Note

If the --release option is not specified, the deploy/images list files are uploaded or shown for the current release.

Deploy a New Subcloud

Use the dcmanager subcloud add command with the --release option to deploy a subcloud with the specified release version.

To initiate the deployment of a subcloud running StarlingX release r6, ensure that the required StarlingX r6 deploy files are uploaded, and that the specific subcloud configurations for StarlingX r6 are properly prepared and run the following command:

Note

If controller-1 of the system controller is the active controller, make sure that /var/www/pages/feed/rel-<version> exists before deploying a StarlingX r6 subcloud. Use the scp command to copy the entire directory from controller-0 to controller-1.

~(keystone_admin)]$ dcmanager subcloud add --bootstrap-address
--bootstrap-address <oam_ip_address_of_subclouds_controller-0>
--bootstrap-values /home/sysadmin/subcloud1-bootstrap-values.yaml
--install-values /home/sysadmin/subcloud1-install-values.yaml
--bmc-password <bmc_password>
--deploy-config /home/sysadmin/subcloud1-deployment-config.yaml
--sysadmin-password <sysadmin_password>
--release <xx.xx>

Where, <xx.xx> is the StarlingX r6 version.

Note

If the --release option is not specified, the subcloud will be deployed to the current release of the system controller.

Warning

If the value of software_version specified in the subcloud install-values.yaml does not align with the --release value in the subcloud add command, the operation will fail. It is recommended to exclude software_version from the subcloud’s install-values.yaml configuration to prevent potential conflicts.

Restore a Subcloud

Note

If a subcloud needs to be reverted to the previous release after an upgrade failure, it is recommended to take a backup of the subcloud before the upgrade using the dcmanager subcloud-backup create command. For additional information, see Backup a Subcloud/Group of Subclouds using DCManager CLI.

To restore a subcloud from a backup of the previous release, ensure that the pre-patched ISO has been imported into the DC vault and use the dcmanager subcloud-backup restore command with the --release option.

~(keystone_admin)]$ dcmanager subcloud-backup restore --subcloud <subcloud> --with-install --sysadmin-password <sysadmin_password> --release <xx.xx>

Where, <xx.xx> is the StarlingX r6 version.

For additional information about the restore, refer to “Restore a single subcloud” section in Restore a Subcloud/Group of Subclouds from Backup Data Using DCManager CLI.

Note

If the --release option is not specified, the subcloud will be installed to the current release and restored from a backup of the current release.

Warning

The restore operation will fail if the backup is either non-existent or incompatible with the release version to which it is being restored.

Delete a Subcloud Backup

To delete a subcloud backup of a particular release, use the dcmanager subcloud-backup delete command with the release number specified. For more information, see Delete Subcloud Backup Data Using DCManager CLI.

  • To delete StarlingX r8 backup data from central storage, use the following command.

    ~(keystone_admin)]$ dcmanager subcloud-backup delete <xx.xx> --subcloud

    Where, <xx.xx> is the StarlingX r8 version.

  • To delete StarlingX r6 backup data from local storage, use the following command.

    ~(keystone_admin)]$ dcmanager subcloud-backup delete <xx.xx> --local-only --subcloud --sysadmin-password <sysadmin_password>

    Where, <xx.xx> is the StarlingX r6 version.

Prestage a Subcloud

Use the dcmanager subcloud prestage command with the --release option to prestage a subcloud for the specified software release. A subcloud can be prestaged with data from either the current or the previous release, irrespective of its current software release version.

The format of prestaged container images depends on the software release. For StarlingX r6 release (CentOS) in the production environment, images are created in the docker image archive format. However, starting from StarlingX r8 and beyond (Debian), images are uploaded to the local registry, and a snapshot of the local registry is captured. This format significantly enhances the speed and efficiency of restoration during subcloud upgrades, re-deployment, or restore processes.

Prestage a Subcloud with Current Release Data

Before prestaging the subcloud(s) with N release data, be sure to complete one or both of the following steps:

  1. Import the pre-patched ISO for the N release as an active load using the following command:

    ~(keystone_admin)]$ system –os-region-name SystemController load-import --active --local <bootimage.iso> <bootimage.sig>

  2. Optional step: Upload the N release images list by using the following command:

    ~(keystone_admin)]$ dcmanager subcloud-deploy upload --prestage-images <nn.nn_images.lst>
Table 1. Container Images Prestage Behavior for StarlingX r8 and higher

Subcloud Software Version

N Release Images List Available

N Release Images List Not Available

StarlingX r7

The container images specified in the list are downloaded from the configured source(s) and pushed to the subcloud local registry. A snapshot of the local registry is then taken and saved in the prestage directory. Finally, downloaded images are removed from the subcloud local registry.

Images prestage is skipped.

StarlingX r8

The container images specified in the list are downloaded from the configured source(s) and pushed to the subcloud local registry. A snapshot of the local registry is then taken and saved in the prestage directory.

A snapshot of the subcloud local registry is taken and saved in the prestage directory.

Note

It is recommended to repeat subcloud prestaging for the current release after a new patch of the current release has been applied on the system controller. This requirement ensures that the subcloud boot image is aligned with the patch level of the load to be installed on the subcloud using prestaged data.

Prestage a Subcloud with N-1 Release Data

Before prestaging the subcloud(s) with N-1 release data, be sure to complete one or both of the following steps:

  1. Import the pre-patched ISO for the N-1 release as an inactive load using the following command:

    ~(keystone_admin)]$ system --os-region-name SystemController load-import --inactive --local <bootimage.iso> <bootimage.sig>

  2. Optional step: Upload the N-1 release images list by using the following command:

    ~(keystone_admin)]$ dcmanager subcloud-deploy upload --prestage-images --release <N-1-software-version>  <nn.nn_images.lst>
Table 2. Container Images Prestage Behavior for StarlingX r6

Subcloud Software Version

N-1 Release Images List Available

N-1 Release Images List Not Available

StarlingX r6

The container images specified in the list are downloaded from the configured source(s). Subsequently, Docker image bundles are generated and saved in the prestage directory.

Image bundles are generated from local registry content and saved in the Prestage directory.

StarlingX r8

The container images specified in the list are downloaded from the configured source(s). Subsequently, Docker image bundles are generated and saved in the prestage directory.

Images prestage is skipped.

  • To prestage a single subcloud, use dcmanager subcloud prestage command. The following command prestages a single subcloud with StarlingX r6 data:

    ~(keystone_admin)]$ dcmanager subcloud prestage --release <xx.xx> --sysadmin-password <sysadmin_password> <subcloud-name-or-id>

    Where, <xx.xx> is the StarlingX r6 version.

  • To prestage a group of subclouds use dcmanager prestage-strategy related commands. The following commands prestages a group of subclouds with StarlingX r8 data:

    ~(keystone_admin)]$ dcmanager prestage-strategy create --release <xx.xx> --sysadmin-password <sysadmin_password> --group <group_name>

~(keystone_admin)]$ dcmanager prestage-strategy apply

    Where, <xx.xx> is the StarlingX r8 version.

Rehome a Subcloud

N-1 subclouds can be migrated to another system controller running N software release. Use the dcmanager subcloud add --migrate command with the --release option to rehome a subcloud. It is not possible to migrate a subcloud running N software release to a system controller running N-1 software release.

Note

A backup of the subcloud should be taken prior to the rehoming procedure in the event that a subcloud restore is required to recover from a failed migration.

See: Backup a Subcloud/Group of Subclouds using DCManager CLI

Rehome StarlingX r6 Subcloud to StarlingX r8 System Controller

To migrate StarlingX r6 subcloud from system controller A to system controller B running StarlingX r8, ensure that the StarlingX r6 pre-patched ISO has been imported to System Controller B as an inactive load, and follow the StarlingX r6 subcloud rehome procedure as follows:

  1. Unmanage the subcloud from the previous system controller.

  2. Update the admin password on the subcloud to match the new system controller, if required.

  3. Run the dcmanager subcloud add command on the new System Controller with the --migrate and --release options to initiate the migration:

    ~(keystone_admin)]$ dcmanager subcloud add --migrate
--bootstrap-address <oam_ip_address_of_subclouds_controller-0>
--bootstrap-values /home/sysadmin/subcloud1-bootstrap-values.yaml
--release <xx.xx>

    Where, <xx.xx> is the StarlingX r6 version.

  4. On the subcloud, lock/unlock the subcloud controller(s) to enable the new configuration.

  5. Use the dcmanager subcloud list command to check the subcloud’s status. Ensure that the subcloud is online and fully operational before proceeding to manage the subcloud.

  6. On the new system controller, set the subcloud to managed and wait for it to sync.

  7. Delete the subcloud from the previous system controller.

For more detailed information, refer to the Rehome-a-Subcloud topic in the StarlingX r6 documentation.

Rehome StarlingX r8 Subcloud to StarlingX r8 System Controller

For more detailed information, see Rehome a Subcloud.

Note

You can add the --release <xx.xx> option to the dcmanager subcloud add --migrate command but it is not mandatory.

Where, <xx.xx> is the StarlingX r8 version.