manpages

osloupgradecheck(1)

OSLOUPGRADECHECK(1) oslo.upgradecheck OSLOUPGRADECHECK(1)

NAME

osloupgradecheck - oslo.upgradecheck 2.5.0

Common code for writing OpenStack upgrade checks.

This project can be used to assist with the implementation of a $SERVICE-status command that responds to parameters of upgrade check by running upgrade check functions on the existing installation. For further details see Usage and the Nova documentation on upgrade checks.

CONTENTS

Installation

At the command line:

$ pip install oslo.upgradecheck


API

upgradecheck module

class oslo_upgradecheck.upgradecheck.Code(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)
Status codes for the upgrade check command

class oslo_upgradecheck.upgradecheck.Result(code, details=None)
Class used for 'nova-status upgrade check' results.

The 'code' attribute is a Code enum. The 'details' attribute is a translated message generally only used for checks that result in a warning or failure code. The details should provide information on what issue was discovered along with any remediation.


class oslo_upgradecheck.upgradecheck.UpgradeCommands
Base class for upgrade checks

This class should be inherited by a class in each project that provides the actual checks. Those checks should be added to the _upgrade_checks class member so that they are run when the check method is called.

The subcommands here must not rely on the service object model since they should be able to run on n-1 data. Any queries to the database should be done through the sqlalchemy query language directly like the database schema migrations.

check()
Performs checks to see if the deployment is ready for upgrade.

These checks are expected to be run BEFORE services are restarted with new code.

Returns
Code



oslo_upgradecheck.upgradecheck.main(conf, project, upgrade_command, argv=['-b', 'man', 'doc/source', 'man'], default_config_files=None)
Simple implementation of main for upgrade checks

This can be used in upgrade check commands to provide the minimum necessary parameter handling and logic.

Parameters
  • conf -- An oslo.confg ConfigOpts instance on which to register the upgrade check arguments.
  • project -- The name of the project, to be used as an argument to the oslo_config.ConfigOpts instance to find configuration files.
  • upgrade_command -- The UpgradeCommands instance.
  • argv -- The command line arguments to parse. Defaults to sys.argv[1:].
  • default_config_files -- The configuration files to load. For projects that use non-standard default locations for the configuration files, use this to override the search behavior in oslo.config.



oslo_upgradecheck.upgradecheck.register_cli_options(conf, upgrade_command)
Set up the command line options.

Adds a subcommand to support 'upgrade check' on the command line.

Parameters
  • conf -- An oslo.confg ConfigOpts instance on which to register the upgrade check arguments.
  • upgrade_command -- The UpgradeCommands instance.



oslo_upgradecheck.upgradecheck.run(conf)
Run the requested command.
Parameters
conf -- An oslo.confg ConfigOpts instance on which the upgrade commands have been previously registered.


Usage

See the module oslo_upgradecheck.__main__ for an example of how to use this project.

Each consuming project should create a class that inherits from oslo_upgradecheck.upgradecheck.UpgradeCommands and implement check methods on it. Those check methods should then be added to the _upgrade_checks tuple so they will be run when the oslo_upgradecheck.upgradecheck.UpgradeCommands.check() method is called. For example:

from oslo_upgradecheck import upgradecheck
class ProjectSpecificUpgradeCommands(upgradecheck.UpgradeCommands):


    def an_upgrade_check(self):


        if everything_is_awesome():


            return upgradecheck.Result(


                upgradecheck.Code.SUCCESS, 'Success details')


        else:


            return upgradecheck.Result(


                upgradecheck.Code.FAILURE, 'Failure details')


    _upgrade_checks = (('Awesome upgrade check', an_upgrade_check))


oslo.upgradecheck also includes a basic implementation of command line argument handling that can be used to provide the minimum processing needed to implement a $SERVICE-status upgrade check command. To make use of it, write a method that creates an instance of the class created above, then pass that class's check function into oslo_upgradecheck.upgradecheck.main(). The project's ConfigOpts instance must also be passed. In most projects this will just be cfg.CONF. For example:

from oslo_config import cfg
def main():


    return upgradecheck.main(


        conf=cfg.CONF,


        project='myprojectname',


        upgrade_command=ProjectSpecificUpgradeCommands(),


    )


The entry point for the $SERVICE-status command should then point at this function.

Alternatively, if a project has its own CLI code that it would prefer to reuse, it simply needs to ensure that the inst.check method is called when the upgrade check parameters are passed to the $SERVICE-status command.

Example

The following is a fully functional example of implementing a check command:

# Copyright 2018 Red Hat Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""Example CLI command for running upgrade checks"""
import sys
from oslo_config import cfg
from oslo_upgradecheck import upgradecheck
class Checks(upgradecheck.UpgradeCommands):


    def success(self):


        return upgradecheck.Result(upgradecheck.Code.SUCCESS,


                                   'Always succeeds')


    def failure(self):


        return upgradecheck.Result(upgradecheck.Code.FAILURE, 'Always fails')


    _upgrade_checks = (('always succeeds', success),


                       ('always fails', failure),


                       )
def main():


    return upgradecheck.main(


        conf=cfg.CONF,


        project='myprojectname',


        upgrade_command=Checks(),


    )
if __name__ == '__main__':


    sys.exit(main())


Contributing

If you would like to contribute to the development of oslo's libraries, first you must take a look to this page:

https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html


If you would like to contribute to the development of OpenStack, you must follow the steps in this page:

http://docs.openstack.org/infra/manual/developers.html


If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool:

http://docs.openstack.org/infra/manual/developers.html#development-workflow


Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub:

https://bugs.launchpad.net/oslo.upgradecheck


RELEASE NOTES

Read also the oslo.upgradecheck Release Notes.

INDICES AND TABLES

  • Index
  • Module Index
  • Search Page

AUTHOR

Author name not set

COPYRIGHT

2025, Oslo Contributors

April 2, 2025 2.5.0