Chapter 6. Upgrading the overcloud

This section upgrades the overcloud. This includes the following workflow:

Running the fast forward upgrade preparation command

Running the fast forward upgrade command

Upgrading the Controller nodes

Upgrading the Compute nodes

Upgrading the Ceph Storage nodes

Finalizing the fast forward upgrade.

Once you begin this workflow, you should not expect full control over the overcloud’s OpenStack services until completing all steps. This means workloads are unmanageable until all nodes have been successfully upgraded to OpenStack Platform 13. The workloads themselves will remain unaffected and continue to run. Changes or additions to any overcloud workloads need to wait until the fast forward upgrade is completed.

6.1. Fast forward upgrade commands

Fast forward upgrade process involves different commands that you run at certain stages of process. The following list contains some basic information about each command.

Important

This list only contains information about each command. You must run these commands in a specific order and provide options specific to your overcloud. Wait until you receive instructions to run these commands at the appropriate step.

openstack overcloud ffwd-upgrade prepare

This command performs the initial preparation steps for the overcloud upgrade, which includes replacing the current overcloud plan on the undercloud with the new OpenStack Platform 13 overcloud plan and your updated environment files. This command functions similar to the openstack overcloud deploy command and uses many of the same options.

openstack overcloud ffwd-upgrade run

This command performs the fast forward upgrade process. The director creates a set of Ansible playbooks based on the new OpenStack Platform 13 overcloud plan and runs the fast forward tasks on the entire overcloud. This includes running the upgrade process through each OpenStack Platform version from 10 to 13.

openstack overcloud upgrade run

This command performs the node-specific upgrade configuration against either single nodes or multiple nodes in a role. The director creates a set of Ansible playbooks based on the overcloud plan and runs tasks against selected nodes, which configures the nodes with the appropriate OpenStack Platform 13 configuration. This command also provides a method to stage updates on a per-role basis. For example, you run this command to upgrade the Controller nodes first, then run the command again to upgrade Compute nodes and Ceph Storage nodes.

openstack overcloud ceph-upgrade run

This command performs the Ceph Storage version upgrade. You run this command after running openstack overcloud upgrade run against the Ceph Storage nodes. The director uses ceph-ansible to perform the Ceph Storage version upgrade.

openstack overcloud ffwd-upgrade converge

This command performs the final step in the overcloud upgrade. This final step synchronizes the overcloud Heat stack with the OpenStack Platform 13 overcloud plan and your updated environment files. This ensures that the resulting overcloud matches the configuration of a new OpenStack Platform 13 overcloud. This command functions similar to the openstack overcloud deploy command and uses many of the same options.

You must run these commands in a specific order. Follow the remaining sections in this chapter to accomplish the fast forward upgrade using these commands.

Note

If you use a custom name for your overcloud, set the custom name with the --stack option for each command.

6.2. Performing the fast forward upgrade of the overcloud

The fast forward upgrade requires running two commands that perform the following tasks:

Updates the overcloud plan to OpenStack Platform 13.

Prepares the nodes for the fast forward upgrade.

Runs through upgrade steps of each subsequent version within the fast forward upgrade, including:

Version-specific tasks for each OpenStack Platform service.

Changing the repository to each sequential OpenStack Platform version within the fast forward upgrade.

Updates certain packages required for upgrading the database.

Performing database upgrades for each subsequent version.

Prepares the overcloud for the final upgrade to OpenStack Platform 13.

Procedure

Source the stackrc file:

$ source ~/stackrc

Run the fast forward upgrade preparation command with all relevant options and environment files appropriate to your deployment:

The environment file with your container image locations (overcloud_images.yaml). Note that the upgrade command might display a warning about using the --container-registry-file. You can ignore this warning as this option is deprecated in favor of using -e for the container image environment file.

If applicable, an environment file that maps deprecated CLI options to Heat parameters using deprecated_cli_options.yaml.

If applicable, an environment file with your custom repository script using custom_repositories_script.yaml.

Create a snapshot or backup of the overcloud before proceding with the upgrade.

Run the fast forward upgrade command:

$ openstack overcloud ffwd-upgrade run

If using a custom stack name, pass the name with the --stack option.

Important

A prompt will ask if you are sure you want to perform the ffwd-upgrade command. Enter yes.

Note

You can run the openstack ffwd-upgrade run command multiple times. If the command fails, you can fix an issue in your templates and then rerun the command.

Wait until the fast forward upgrade completes.

At this stage:

Workloads are still running

The overcloud database has been upgraded to the OpenStack Platform 12 version

All overcloud services are disabled

Ceph Storage nodes are still at version 2

This means the overcloud is now at a state to perform the standard upgrade steps to reach OpenStack Platform 13.

6.3. Upgrading Controller and custom role nodes

Use the following process to upgrade all the Controller nodes, split Controller services, and other custom nodes to OpenStack Platform 13. The process involves running the openstack overcloud upgrade run command and including the --nodes option to restrict operations to only the selected nodes:

$ openstack overcloud upgrade run --nodes [ROLE]

Substitute [ROLE] for the name of a role or a comma-separated list of roles.

If your overcloud uses monolithic Controller nodes, run this command against the Controller role.

If your overcloud uses split Controller services, use the following guide to upgrade the node role in the following order:

All roles that use Pacemaker. For example: ControllerOpenStack, Database, Messaging, and Telemetry.

Networker nodes

Any other custom roles

Do not upgrade the following nodes yet:

Compute nodes of any type such as DPDK based or Hyper-Converged Infratructure (HCI) Compute nodes

CephStorage nodes

You will upgrade these nodes at a later stage.

Note

The commands in this procedure use the --skip-tags validation option because OpenStack Platform services are inactive on the overcloud and cannot be validated.

Procedure

Source the stackrc file:

$ source ~/stackrc

If you use monolithic Controller nodes, run the upgrade command against the Controller role:

If you use a custom stack name, pass the name with the --stack option.

At this stage:

Workloads are still running

The overcloud database has been upgraded to the OpenStack Platform 13 version

The Controller nodes have been upgraded to OpenStack Platform 13

All Controller services are enabled

The Compute nodes still require an upgrade

Ceph Storage nodes are still at version 2 and require an upgrade

Warning

Although Controller services are enabled, do not perform any workload operations while Compute node and Ceph Storage services are disabled. This can cause orphaned virtual machines. Wait until the entire environment is upgraded.

6.4. Upgrading test Compute nodes

This process upgrades Compute nodes selected for testing. The process involves running the openstack overcloud upgrade run command and including the --nodes option to restrict operations to the test nodes only. This procedure uses --nodes compute-0 as an example in commands.

This process upgrades all remaining Compute nodes to OpenStack Platform 13. The process involves running the openstack overcloud upgrade run command and including the --nodes Compute option to restrict operations to the Compute nodes only.

The environment file with your container image locations (overcloud_images.yaml). Note that the upgrade command might display a warning about using the --container-registry-file. You can ignore this warning as this option is deprecated in favor of using -e for the container image environment file.

If applicable, an environment file that maps deprecated CLI options to Heat parameters using deprecated_cli_options.yaml.

If applicable, an environment file with your custom repository script using custom_repositories_script.yaml.

The environment file with your container image locations (overcloud_images.yaml). Note that the upgrade command might display a warning about using the --container-registry-file. You can ignore this warning as this option is deprecated in favor of using -e for the container image environment file.

If applicable, an environment file that maps deprecated CLI options to Heat parameters using deprecated_cli_options.yaml.

If applicable, an environment file with your custom repository script using custom_repositories_script.yaml.

The environment file with your container image locations (overcloud_images.yaml). Note that the upgrade command might display a warning about using the --container-registry-file. You can ignore this warning as this option is deprecated in favor of using -e for the container image environment file.

If applicable, an environment file that maps deprecated CLI options to Heat parameters using deprecated_cli_options.yaml.

If applicable, an environment file with your custom repository script using custom_repositories_script.yaml.

All nodes have been upgraded to OpenStack Platform 13 and workloads are still running

Although the environment is now upgraded, you must perform one last step to finalize the upgrade.

6.9. Finalizing the fast forward upgrade

The fast forward upgrade requires a final step to update the overcloud stack. This ensures the stack’s resource structure aligns with a regular deployment of OpenStack Platform 13 and allows you to perform standard openstack overcloud deploy functions in the future.

The environment file with your container image locations (overcloud_images.yaml). Note that the upgrade command might display a warning about using the --container-registry-file. You can ignore this warning as this option is deprecated in favor of using -e for the container image environment file.

If applicable, an environment file that maps deprecated CLI options to Heat parameters using deprecated_cli_options.yaml.

A prompt will ask if you are sure you want to perform the ffwd-upgrade command. Enter yes.

Wait until the fast forward upgrade finalization completes.

6.10. Next Steps

The overcloud upgrade is complete. You can now perform any relevant post-upgrade overcloud configuration using the steps in Chapter 7, Executing Post Upgrade Steps. For future deployment operations, make sure to include all environment files relevant to your OpenStack Platform 13 environment, including new environment files created or converted during the upgrade.