Chapter 17. Upgrade command overview

download PDF

The upgrade process involves different commands that you run at certain stages of process.


This section 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.

17.1. openstack overcloud 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 16.1 overcloud plan and your updated environment files. This command functions similar to the openstack overcloud deploy command and uses many of the same options.

17.2. openstack overcloud upgrade run

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

In addition to the standard upgrade process, this command can perform a Leapp upgrade of the operating system on overcloud nodes. Run these tasks using the --tags option.

Upgrade task tags for Leapp

Task that combines tasks from system_upgrade_prepare, system_upgrade_run, and system_upgrade_reboot.
Tasks to prepare for the operating system upgrade with Leapp.
Tasks to run Leapp and upgrade the operating system.
Tasks to reboot a system and complete the operating system upgrade.

Upgrade task tags for workload migration

Task that sets up temporary OpenStack Platform 16.1 containers on Compute nodes to facilitate workload migration during the upgrade.

17.3. openstack overcloud external-upgrade run

This command performs upgrade tasks outside the standard upgrade process. Director creates a set of Ansible playbooks based on the new OpenStack Platform 16.1 overcloud plan and you run specific tasks using the --tags option.

External task tags for container management

Tasks for pulling container images to the undercloud registry and preparing the images for the overcloud to use.

External task tags for Ceph Storage upgrades

  • If your deployment uses a Red Hat Ceph Storage cluster that was deployed using director, you can use the following tags:

    Tasks to install Red Hat Ceph Storage using ceph-ansible playbooks.
    Tasks to convert Red Hat Ceph Storage systemd unit files to use podman management.
  • If you are upgrading with external Ceph deployments, you can skip the tasks that use the ceph and ceph_systemd tags.

External task tags for database transfer

Tasks to clean storage directories related to system_upgrade_transfer_data tasks.
Tasks to shut down all services.
Tasks to shut down all services and perform a database transfer to the bootstrap node.

17.4. openstack overcloud upgrade converge

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

17.5. Overcloud node upgrade workflow

When you perform an upgrade on each overcloud node, you must consider the following aspects to determine the correct commands to run at the relevant stage in the upgrade:

Controller Services

  • Does the node contain Pacemaker services? You must first upgrade the bootstrap node in order to start a database transfer and launch temporary containers that facilitate migration during the transition from Red Hat OpenStack 13 to 16.1. During the bootstrap Controller node upgrade process, a new Pacemaker cluster is created and new Red Hat OpenStack 16.1 containers are started on the node, while the remaining Controller nodes are still running on Red Hat OpenStack 13. After upgrading the bootstrap node, you must upgrade each additional node with Pacemaker services and ensure that each node joins the new Pacemaker cluster started with the bootstrap node. The process for upgrading split-service Controller nodes without Pacemaker does not require these additional steps.

Compute Services

  • Is the node a Compute node? If the node does contain Compute services, you must migrate virtual machines from the node to ensure maximum availability. A Compute node in this situation includes any node designed to host virtual machines. This definition includes the follow Compute nodes types:

    • Regular Compute nodes
    • Compute nodes with Hyper-Converged Infrastructure (HCI)
    • Compute nodes with Network Function Virtualization technologies such as Data Plane Development Kit (DPDK) or Single Root Input/Output Virtualization (SR-IOV)
    • Real Time Compute nodes

Ceph Storage Services

  • Does the node contain any Ceph Storage services? You must convert the systemd unit files for any containerized Ceph Storage services on the node to use podman instead of docker. This applies to the following node types:

    • Ceph Storage OSD nodes
    • Controller nodes with Ceph MON services
    • Split-Controller Ceph MON nodes
    • Compute nodes with Hyper-Converged Infrastructure (HCI)


Use the following workflow diagram to identify the correct update path for specific nodes:

Overcloud node upgrade workflow

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.