Upgrades¶

Upgrade planning¶

• Thoroughly review the release notes to learn about new, updated, and deprecated features. Find incompatibilities between versions.
• Consider the impact of an upgrade to users. The upgrade process interrupts management of your environment including the dashboard. If you properly prepare for the upgrade, existing instances, networking, and storage should continue to operate. However, instances might experience intermittent network interruptions.
• Consider the approach to upgrading your environment. You can perform an upgrade with operational instances, but this is a dangerous approach. You might consider using live migration to temporarily relocate instances to other compute nodes while performing upgrades. However, you must ensure database consistency throughout the process; otherwise your environment might become unstable. Also, don’t forget to provide sufficient notice to your users, including giving them plenty of time to perform their own backups.
• Consider adopting structure and options from the service configuration files and merging them with existing configuration files. The OpenStack Configuration Reference contains new, updated, and deprecated options for most services.
• Like all major system upgrades, your upgrade could fail for one or more reasons. You can prepare for this situation by having the ability to roll back your environment to the previous release, including databases, configuration files, and packages. We provide an example process for rolling back your environment in Rolling back a failed upgrade.
• Develop an upgrade procedure and assess it thoroughly by using a test environment similar to your production environment.

Pre-upgrade testing environment¶

The most important step is the pre-upgrade testing. If you are upgrading immediately after release of a new version, undiscovered bugs might hinder your progress. Some deployers prefer to wait until the first point release is announced. However, if you have a significant deployment, you might follow the development and testing of the release to ensure that bugs for your use cases are fixed.

Each OpenStack cloud is different even if you have a near-identical architecture as described in this guide. As a result, you must still test upgrades between versions in your environment using an approximate clone of your environment.

However, that is not to say that it needs to be the same size or use identical hardware as the production environment. It is important to consider the hardware and scale of the cloud that you are upgrading. The following tips can help you minimise the cost:

Use your own cloud

The simplest place to start testing the next version of OpenStack is by setting up a new environment inside your own cloud. This might seem odd, especially the double virtualization used in running compute nodes. But it is a sure way to very quickly test your configuration.

Use a public cloud

Consider using a public cloud to test the scalability limits of your cloud controller configuration. Most public clouds bill by the hour, which means it can be inexpensive to perform even a test with many nodes.

Make another storage endpoint on the same system

If you use an external storage plug-in or shared file system with your cloud, you can test whether it works by creating a second share or endpoint. This allows you to test the system before entrusting the new version on to your storage.

Watch the network

Even at smaller-scale testing, look for excess network packets to determine whether something is going horribly wrong in inter-component communication.

To set up the test environment, you can use one of several methods:

• Do a full manual install by using the Installation Tutorials and Guides for your platform. Review the final configuration files and installed packages.

• Create a clone of your automated configuration infrastructure with changed package repository URLs.

  Alter the configuration until it works.

Either approach is valid. Use the approach that matches your experience.

An upgrade pre-testing system is excellent for getting the configuration to work. However, it is important to note that the historical use of the system and differences in user interaction can affect the success of upgrades.

If possible, we highly recommend that you dump your production database tables and test the upgrade in your development environment using this data. Several MySQL bugs have been uncovered during database migrations because of slight table differences between a fresh installation and tables that migrated from one version to another. This will have impact on large real datasets, which you do not want to encounter during a production outage.

Artificial scale testing can go only so far. After your cloud is upgraded, you must pay careful attention to the performance aspects of your cloud.

Upgrade Levels¶

Upgrade levels are a feature added to OpenStack Compute since the Grizzly release to provide version locking on the RPC (Message Queue) communications between the various Compute services.

This functionality is an important piece of the puzzle when it comes to live upgrades and is conceptually similar to the existing API versioning that allows OpenStack services of different versions to communicate without issue.

Without upgrade levels, an X+1 version Compute service can receive and understand X version RPC messages, but it can only send out X+1 version RPC messages. For example, if a nova-conductor process has been upgraded to X+1 version, then the conductor service will be able to understand messages from X version nova-compute processes, but those compute services will not be able to understand messages sent by the conductor service.

During an upgrade, operators can add configuration options to nova.conf which lock the version of RPC messages and allow live upgrading of the services without interruption caused by version mismatch. The configuration options allow the specification of RPC version numbers if desired, but release name alias are also supported. For example:

[upgrade_levels]
compute=X+1
conductor=X+1
scheduler=X+1

will keep the RPC version locked across the specified services to the RPC version used in X+1. As all instances of a particular service are upgraded to the newer version, the corresponding line can be removed from nova.conf.

Using this functionality, ideally one would lock the RPC version to the OpenStack version being upgraded from on nova-compute nodes, to ensure that, for example X+1 version nova-compute processes will continue to work with X version nova-conductor processes while the upgrade completes. Once the upgrade of nova-compute processes is complete, the operator can move onto upgrading nova-conductor and remove the version locking for nova-compute in nova.conf.

Service specific upgrade instructions¶

Refer to the following upgrade notes for information on upgrading specific OpenStack services:

• Networking service (neutron) upgrades
• Compute service (nova) upgrades
• Identity service (keystone) upgrades
• Block Storage service (cinder) upgrades
• Image service (glance) zero downtime database upgrades
• Image service (glance) rolling upgrades
• Bare Metal service (ironic) upgrades
• Object Storage service (swift) upgrades
• Telemetry service (ceilometer) upgrades

Prerequisites¶

• Perform some cleaning of the environment prior to starting the upgrade process to ensure a consistent state. For example, instances not fully purged from the system after deletion might cause indeterminate behavior.

• For environments using the OpenStack Networking service (neutron), verify the release version of the database. For example:

  # su -s /bin/sh -c "neutron-db-manage --config-file /etc/neutron/neutron.conf \
    --config-file /etc/neutron/plugins/ml2/ml2_conf.ini current" neutron
  

Perform a backup¶

1. Save the configuration files on all nodes. For example:

   # for i in keystone glance nova neutron openstack-dashboard cinder heat ceilometer; \
     do mkdir $i-RELEASE_NAME; \
     done
   # for i in keystone glance nova neutron openstack-dashboard cinder heat ceilometer; \
     do cp -r /etc/$i/* $i-RELEASE_NAME/; \
     done
   

   Note

   You can modify this example script on each node to handle different services.

2. Make a full database backup of your production data. Since the Kilo release, database downgrades are not supported, and restoring from backup is the only method available to retrieve a previous database version.

   # mysqldump -u root -p --opt --add-drop-database --all-databases > RELEASE_NAME-db-backup.sql
   

   Note

   Consider updating your SQL server configuration as described in the Installation Tutorials and Guides.

Manage repositories¶

On all nodes:

1. Remove the repository for the previous release packages.
2. Add the repository for the new release packages.
3. Update the repository database.

Upgrade packages on each node¶

Depending on your specific configuration, upgrading all packages might restart or break services supplemental to your OpenStack environment. For example, if you use the TGT iSCSI framework for Block Storage volumes and the upgrade includes new packages for it, the package manager might restart the TGT iSCSI services and impact connectivity to volumes.

If the package manager prompts you to update configuration files, reject the changes. The package manager appends a suffix to newer versions of configuration files. Consider reviewing and adopting content from these files.

Update services¶

To update a service on each node, you generally modify one or more configuration files, stop the service, synchronize the database schema, and start the service. Some services require different steps. We recommend verifying operation of each service before proceeding to the next service.

The order you should upgrade services, and any changes from the general upgrade process is described below:

Controller node

1. Identity service - Clear any expired tokens before synchronizing the database.
2. Image service
3. Compute service, including networking components.
4. Networking service
5. Block Storage service
6. Dashboard - In typical environments, updating Dashboard only requires restarting the Apache HTTP service.
7. Orchestration service
8. Telemetry service - In typical environments, updating the Telemetry service only requires restarting the service.
9. Compute service - Edit the configuration file and restart the service.
10. Networking service - Edit the configuration file and restart the service.

Storage nodes

• Block Storage service - Updating the Block Storage service only requires restarting the service.

Compute nodes

• Networking service - Edit the configuration file and restart the service.

Final steps¶

On all distributions, you must perform some final tasks to complete the upgrade process.

1. Decrease DHCP timeouts by modifying the /etc/nova/nova.conf file on the compute nodes back to the original value for your environment.
2. Update all .ini files to match passwords and pipelines as required for the OpenStack release in your environment.
3. After migration, users see different results from openstack image list and glance image-list. To ensure users see the same images in the list commands, edit the /etc/glance/policy.json file and /etc/nova/policy.json file to contain "context_is_admin": "role:admin", which limits access to private images for projects.
4. Verify proper operation of your environment. Then, notify your users that their cloud is operating normally again.