Red Hat Training
A Red Hat training course is available for Red Hat OpenStack Platform
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.
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 usesceph-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.
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:
$ openstack overcloud ffwd-upgrade prepare \ --templates \ -e /home/stack/templates/overcloud_images.yaml \ -e /home/stack/templates/deprecated_cli_options.yaml \ -e /home/stack/templates/custom_repositories_script.yaml \ -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml \ -e /home/stack/templates/ceph-customization.yaml \ -e <ENVIRONMENT FILE>
Include the following options relevant to your environment:
Custom configuration environment files (
-e
). For example:-
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
. - If using Ceph Storage nodes, the relevant environment files.
- Any additional environment files relevant to your environment.
-
The environment file with your container image locations (
-
If using a custom stack name, pass the name with the
--stack
option. -
If applicable, your custom roles (
roles_data
) file using--roles-file
.
ImportantA prompt will ask if you are sure you want to perform the
ffwd-upgrade
command. Enteryes
.NoteYou can run the
openstack ffwd-upgrade prepare
command multiple times. If the command fails, you can fix an issue in your templates and then rerun the command.- The overcloud plan updates to the OpenStack Platform 13 version. Wait until the fast forward upgrade preparation completes.
- 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.
ImportantA prompt will ask if you are sure you want to perform the
ffwd-upgrade
command. Enteryes
.NoteYou 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.-
If using a custom stack name, pass the name with the
- 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
, andTelemetry
. -
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.
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:$ openstack overcloud upgrade run --nodes Controller --skip-tags validation
-
If you use a custom stack name, pass the name with the
--stack
option.
-
If you use a custom stack name, pass the name with the
If you use Controller services split across multiple roles:
Run the upgrade command for roles with Pacemaker services:
$ openstack overcloud upgrade run --nodes ControllerOpenStack --skip-tags validation $ openstack overcloud upgrade run --nodes Database --skip-tags validation $ openstack overcloud upgrade run --nodes Messaging --skip-tags validation $ openstack overcloud upgrade run --nodes Telemetry --skip-tags validation
-
If you use a custom stack name, pass the name with the
--stack
option.
-
If you use a custom stack name, pass the name with the
Run the upgrade command for the
Networker
role:$ openstack overcloud upgrade run --nodes Networker --skip-tags validation
-
If you use a custom stack name, pass the name with the
--stack
option.
-
If you use a custom stack name, pass the name with the
Run the upgrade command for any remaining custom roles, except for
Compute
orCephStorage
roles:$ openstack overcloud upgrade run --nodes ObjectStorage --skip-tags validation
-
If you use a custom stack name, pass the name with the
--stack
option.
-
If you use a custom stack name, pass the name with the
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
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.
Procedure
Source the
stackrc
file:$ source ~/stackrc
Run the upgrade command:
$ openstack overcloud upgrade run --nodes compute-0 --skip-tags validation
NoteThe command uses
--skip-tags validation
because OpenStack Platform services are inactive on the overcloud and cannot be validated.-
If using a custom stack name, pass the name with the
--stack
option.
-
If using a custom stack name, pass the name with the
- Wait until the test node upgrade completes.
6.5. Upgrading all Compute nodes
- Important
- If you are using a hyperconverged deployment, see Section 6.7, “Upgrading hyperconverged nodes” for how to upgrade.
- If you are using a mixed hyperconverged deployment, see Section 6.8, “Upgrading mixed hyperconverged nodes” for how to upgrade.
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.
Procedure
Source the
stackrc
file:$ source ~/stackrc
Run the upgrade command:
$ openstack overcloud upgrade run --nodes Compute --skip-tags validation
NoteThe command uses
--skip-tags validation
because OpenStack Platform services are inactive on the overcloud and cannot be validated.-
If you are using a custom stack name, pass the name with the
--stack
option. -
If you are using custom Compute roles, ensure that you include the role names with the
--nodes
option.
-
If you are using a custom stack name, pass the name with the
- Wait until the Compute node upgrade completes.
At this stage:
- Workloads are still running
- The Controller nodes and Compute nodes have been upgraded to OpenStack Platform 13
- Ceph Storage nodes are still at version 2 and require an upgrade
6.6. Upgrading all Ceph Storage nodes
- Important
- If you are using a hyperconverged deployment, see Section 6.7, “Upgrading hyperconverged nodes” for how to upgrade.
- If you are using a mixed hyperconverged deployment, see Section 6.8, “Upgrading mixed hyperconverged nodes” for how to upgrade.
This process upgrades the Ceph Storage nodes. The process involves:
-
Running the
openstack overcloud upgrade run
command and including the--nodes CephStorage
option to restrict operations to the Ceph Storage nodes only. -
Running the
openstack overcloud ceph-upgrade run
command to perform an upgrade to a containerized Red Hat Ceph Storage 3 cluster.
Procedure
Source the
stackrc
file:$ source ~/stackrc
Run the upgrade command:
$ openstack overcloud upgrade run --nodes CephStorage --skip-tags validation
NoteThe command uses
--skip-tags validation
because OpenStack Platform services are inactive on the overcloud and cannot be validated.-
If using a custom stack name, pass the name with the
--stack
option.
-
If using a custom stack name, pass the name with the
- Wait until the node upgrade completes.
Run the Ceph Storage upgrade command. For example:
$ openstack overcloud ceph-upgrade run \ --templates \ -e <ENVIRONMENT FILE> \ -e /home/stack/templates/overcloud_images.yaml \ -e /home/stack/templates/deprecated_cli_options.yaml \ -e /home/stack/templates/custom_repositories_script.yaml -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml \ -e /home/stack/templates/ceph-customization.yaml \ --ceph-ansible-playbook '/usr/share/ceph-ansible/infrastructure-playbooks/switch-from-non-containerized-to-containerized-ceph-daemons.yml,/usr/share/ceph-ansible/infrastructure-playbooks/rolling_update.yml'
Include the following options relevant to your environment:
Custom configuration environment files (
-e
). For example:-
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 relevant environment files for your Ceph Storage nodes.
- Any additional environment files relevant to your environment.
-
The environment file with your container image locations (
-
If using a custom stack name, pass the name with the
--stack
option. -
If applicable, your custom roles (
roles_data
) file using--roles-file
. - The following ansible playbooks:
-
/usr/share/ceph-ansible/infrastructure-playbooks/switch-from-non-containerized-to-containerized-ceph-daemons.yml
-
/usr/share/ceph-ansible/infrastructure-playbooks/rolling_update.yml
- Wait until the Ceph Storage node upgrade completes.
6.7. Upgrading hyperconverged nodes
If you are using only hyperconverged nodes from the ComputeHCI role, and are not using dedicated compute nodes or dedicated Ceph nodes, complete the following procedure to upgrade your nodes:
Procedure
Source the stackrc file:
$ source ~/stackrc
Run the upgrade command:
$ openstack overcloud upgrade run --roles ComputeHCI
If you are using a custom stack name, pass the name to the upgrade command with the
--stack
option.Run the Ceph Storage upgrade command. For example:
$ openstack overcloud ceph-upgrade run \ --templates \ -e /home/stack/templates/overcloud_images.yaml \ -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml \ -e /home/stack/templates/ceph-customization.yaml \ -e <ENVIRONMENT FILE>
Include the following options relevant to your environment:
Custom configuration environment files (
-e
). For example:-
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 relevant environment files for your Ceph Storage nodes.
-
The environment file with your container image locations (
-
If using a custom stack name, pass the name with the
--stack
option. -
If applicable, your custom roles (
roles_data
) file using--roles-file
. - The following ansible playbooks:
-
/usr/share/ceph-ansible/infrastructure-playbooks/switch-from-non-containerized-to-containerized-ceph-daemons.yml
-
/usr/share/ceph-ansible/infrastructure-playbooks/rolling_update.yml
- Wait until the Ceph Storage node upgrade completes.
6.8. Upgrading mixed hyperconverged nodes
If you are using dedicated compute nodes or dedicated ceph nodes in addition to hyperconverged nodes like the ComputeHCI role, complete the following procedure to upgrade your nodes:
Procedure
Source the stackrc file:
$ source ~/stackrc
Run the upgrade command for the Compute node:
$ openstack overcloud upgrade run --roles Compute If using a custom stack name, pass the name with the --stack option.
- Wait until the node upgrade completes.
Run the upgrade command for the ComputeHCI node:
$ openstack overcloud upgrade run --roles ComputeHCI If using a custom stack name, pass the name with the --stack option.
- Wait until the node upgrade completes.
Run the upgrade command for the Ceph Storage node:
$ openstack overcloud upgrade run --roles CephStorage
- Wait until the Ceph Storage node upgrade completes.
Run the Ceph Storage upgrade command. For example:
$ openstack overcloud ceph-upgrade run \ --templates \ -e /home/stack/templates/overcloud_images.yaml \ -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml \ -e /home/stack/templates/ceph-customization.yaml \ -e <ENVIRONMENT FILE>
Include the following options relevant to your environment:
Custom configuration environment files (
-e
). For example:-
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 relevant environment files for your Ceph Storage nodes.
- Any additional environment files relevant to your environment.
-
The environment file with your container image locations (
-
If using a custom stack name, pass the name with the
--stack
option. -
If applicable, your custom roles (
roles_data
) file using--roles-file
. - The following ansible playbooks:
-
/usr/share/ceph-ansible/infrastructure-playbooks/switch-from-non-containerized-to-containerized-ceph-daemons.yml
-
/usr/share/ceph-ansible/infrastructure-playbooks/rolling_update.yml
- Wait until the Ceph Storage node upgrade completes.
At this stage:
- 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.
Procedure
Source the
stackrc
file:$ source ~/stackrc
Run the fast forward upgrade finalization command:
$ openstack overcloud ffwd-upgrade converge \ --templates \ -e /home/stack/templates/overcloud_images.yaml \ -e /home/stack/templates/deprecated_cli_options.yaml \ -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml \ -e /home/stack/templates/ceph-customization.yaml \ -e <OTHER ENVIRONMENT FILES>
Include the following options relevant to your environment:
Custom configuration environment files (
-e
). For example:-
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 using Ceph Storage nodes, the relevant environment files.
- Any additional environment files relevant to your environment.
-
The environment file with your container image locations (
-
If using a custom stack name, pass the name with the
--stack
option. -
If applicable, your custom roles (
roles_data
) file using--roles-file
.
ImportantA prompt will ask if you are sure you want to perform the
ffwd-upgrade
command. Enteryes
.- 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 8, 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.