OpenStack Oslo Upgrade Check

Common errors

• oslo_config.cfg.NotInitializedError: call expression on parser has not been invoked.

  cause `oslo.config`'s configuration parser was not properly initialized or loaded before an `oslo-upgradecheck` function attempted to access a configuration option.
  fix Ensure that `oslo_config.cfg.CONF()` is called at the application's entry point, and that relevant configuration files are loaded using `cfg.CONF(args=[])` or `cfg.CONF.register_opts()` as appropriate for your service. This often happens in a `main()` function or similar setup block.

• ImportError: No module named oslo_upgradecheck

  cause The `oslo-upgradecheck` library is not installed in the current Python environment.
  fix Run `pip install oslo-upgradecheck` to install the package.

Warnings

• breaking As part of the wider OpenStack project, oslo-upgradecheck and other oslo libraries have dropped support for Python 2.7. Users must use Python 3.10 or newer, as specified in PyPI metadata.
  Fix: Ensure your environment uses Python >=3.10. Upgrade your Python interpreter if necessary.
• gotcha When integrating `oslo-upgradecheck` into an OpenStack service, it's crucial to properly initialize `oslo.config` before running checks. Failure to do so can lead to `oslo_config.cfg.NotInitializedError` when checks attempt to access configuration options.
  Fix: Ensure `oslo_config.cfg.CONF()` (or a similar initialization) is called and configuration files are loaded before invoking `UpgradeCommands.run_checks()`.
• deprecated Older versions of `oslo-upgradecheck` (prior to 0.3.0, Train series) only output human-readable tables. Newer versions support a `--json` flag for machine-readable output.
  Fix: For machine-readable output, upgrade to `oslo-upgradecheck` version 0.3.0 or later and use the `--json` command-line flag.

Install

• pip install oslo-upgradecheck Install latest version

Imports

• UpgradeCommands
  wrong:

  from oslo.upgradecheck import UpgradeCommands

  correct:

  from oslo_upgradecheck.upgradecheck import UpgradeCommands

  The official import uses `oslo_upgradecheck` as the top-level package, not `oslo.upgradecheck` (which is a common pattern for older OpenStack 'oslo' projects that were not PEP 420 namespace packages).
• check_func

  from oslo_upgradecheck.upgradecheck import check_func

Quickstart

This quickstart demonstrates how to define custom upgrade checks using the `oslo_upgradecheck.check_func` decorator and run them using `UpgradeCommands`. Each check function should return a tuple of `(status, details)`, where `status` is a boolean indicating success/failure and `details` is a string message. The `group` argument in `check_func` allows organizing checks into different phases (e.g., pre-upgrade, post-upgrade).

import sys
from oslo_upgradecheck.upgradecheck import UpgradeCommands, check_func


@check_func(group='required_pre_upgrade')
def my_first_check():
    """This is my first upgrade check.

    :returns: a tuple of (status, details).
    """
    # Simulate a successful check
    return (True, "My service is ready for upgrade.")


@check_func(group='required_pre_upgrade')
def my_second_check():
    """This is my second, more complex check.

    :returns: a tuple of (status, details).
    ""
    # Simulate a failed check based on some condition
    is_database_migrated = False # In a real scenario, check DB status
    if not is_database_migrated:
        return (False, "Database migration is incomplete. Please run 'db sync'.")
    return (True, "Database is migrated.")


def main():
    # In a real OpenStack project, oslo_config would be initialized here
    # to handle command-line arguments and configuration.
    # For this quickstart, we'll manually invoke the checks.

    commands = UpgradeCommands()

    # You can specify which group of checks to run
    # e.g., 'required_pre_upgrade', 'pre_upgrade', 'post_upgrade'
    print("\n--- Running required_pre_upgrade checks ---")
    results = commands.run_checks(group='required_pre_upgrade')
    for check, status, details in results:
        print(f"Check: {check.__name__}, Status: {status}, Details: {details}")

    if any(not s for _, s, _ in results):
        print("\nSome required checks failed. Upgrade is not recommended.")
        sys.exit(1)
    else:
        print("\nAll required checks passed. Proceed with upgrade.")
        sys.exit(0)


if __name__ == '__main__':
    main()