# 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())

this page last updated: 2026-07-15 01:26:11

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug