Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Understand the Upgrade Plan

This section provides information regarding the upgrade_plan, how it works, and how to configure the upgrade plan. A sample upgrade plan is provided to show a general example for how you might configure the upgrade_plan.

The upgrade plan controls the overcloud upgrade sequencing, and allows you to define node batches to upgrade when you run the script. The upgrade_plan is defined in your config/site.yml configuration file.

The overcloud upgrade ( will:

  • Compare lock files to the user defined batch list to find the next user defined batch which has not already been completed.
  • Upgrade all nodes per batch as defined in the upgrade plan nodes list, and is configured in the config/site.yml file.
  • Upgrade packages and containers for each node defined in the current batch.
  • Upgrade one batch per script run, as configured in the upgrade_plan.
  • Automatically create a lock file when the batch has been processed. This is how the script knows to move on to the next batch.
  • You rerun the script until there are no longer any batches left to upgrade.

Configure Your Upgrade Plan

The sample below shows the upgrade configuration options and is configured in the config/site.yml file. Use this upgrade configuration sample to determine accurate empty-space and indentations within the configuration hierarchy. Come back and reference this sample as needed to assist you through the upgrade process:

The procedure below allows you to target specific nodes during the upgrade. This approach allows for control and predictability of the upgrade. This method is desirable so you can target specific resources to be upgraded as workloads are migrated.

To complete a targeted upgrade, edit the sample plan to match your deployment for each targeted batch. Later in the procedure you will run the script for each batch defined within the upgrade plan. Add the upgrade_plan: configuration to your config/site.yml configuration file.

Name Your Unique Batch

The upgrade will be performed in the batch order you configure in your upgrade_plan. The unique batch name is used to identify each unique batch, and for lock file naming.

When the script is run, the script will identify the first unique named batch which has not already been executed and upgraded. A lockfile is created after each successful batch upgrade to identify it as being completed. To start, you might configure it to look like this:

Define the Upgrade Type for the Named Node Role

The upgrade type determines the order in which the nodes are upgraded in the named batch run. You have the option of running the upgrade in sequence and will upgrade one node at a time, per batch run. You also have the option to run the upgrade in parallel and will upgrade all nodes together, per batch run.

The sample below is configured to upgrade the nodes in the named batch in sequence:

Define the nodes in the Named Batch

Define the nodes in the nodes_list that you would like to upgrade in the named batch run. These nodes are the specific node names from your environment.

ControlPlane is a special keyword understood by the upgrade plan. The ControlPlane represents the OpenStack control plane role (Controller), and the Contrail control plane roles (ContrailController, ContrailAnalytics, and ContrailAnalyticsDatabase). The ControlPlane will upgrade as one batch as part of the upgrade plan. One instance of each role will be upgraded in parallel, and then the next instances will be run in parallel, until all roles are upgraded. Within each role, only one instance of the role will be upgraded at a time.

The first batch in your upgrade_plan should always be the ControlPlane role:

Finish Defining Your Remaining Batches

Define the rest of your batches and ensure all nodes have been targeted for upgrade. The ControlPlane (as a set of control plane nodes) should always be the first batch to upgrade. The next batches should include the compute nodes. The last batches should consist of the storage nodes.