{"id":8390,"library":"oslo-upgradecheck","title":"OpenStack Oslo Upgrade Check","description":"oslo-upgradecheck is a Python library providing common code for writing upgrade checks within OpenStack projects. It assists with implementing `$SERVICE-status upgrade check` commands by offering a framework to define and execute various pre-upgrade validation functions. Currently at version 2.7.1, its release cadence is generally aligned with the OpenStack coordinated release cycle, typically every six months, though individual Oslo libraries may have more frequent patch releases.","status":"active","version":"2.7.1","language":"en","source_language":"en","source_url":"https://github.com/openstack/oslo.upgradecheck","tags":["OpenStack","upgrade","health check","utility","oslo","devops"],"install":[{"cmd":"pip install oslo-upgradecheck","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for configuration management within OpenStack projects, often used by upgrade checks.","package":"oslo.config","optional":false},{"reason":"Provides various utility functions commonly used across Oslo libraries and OpenStack projects.","package":"oslo.utils","optional":false},{"reason":"Used for internationalization and localization support.","package":"oslo.i18n","optional":true},{"reason":"For RBAC policy enforcement, which may be part of some upgrade checks.","package":"oslo.policy","optional":true}],"imports":[{"note":"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).","wrong":"from oslo.upgradecheck import UpgradeCommands","symbol":"UpgradeCommands","correct":"from oslo_upgradecheck.upgradecheck import UpgradeCommands"},{"symbol":"check_func","correct":"from oslo_upgradecheck.upgradecheck import check_func"}],"quickstart":{"code":"import sys\nfrom oslo_upgradecheck.upgradecheck import UpgradeCommands, check_func\n\n\n@check_func(group='required_pre_upgrade')\ndef my_first_check():\n    \"\"\"This is my first upgrade check.\n\n    :returns: a tuple of (status, details).\n    \"\"\"\n    # Simulate a successful check\n    return (True, \"My service is ready for upgrade.\")\n\n\n@check_func(group='required_pre_upgrade')\ndef my_second_check():\n    \"\"\"This is my second, more complex check.\n\n    :returns: a tuple of (status, details).\n    \"\"\n    # Simulate a failed check based on some condition\n    is_database_migrated = False # In a real scenario, check DB status\n    if not is_database_migrated:\n        return (False, \"Database migration is incomplete. Please run 'db sync'.\")\n    return (True, \"Database is migrated.\")\n\n\ndef main():\n    # In a real OpenStack project, oslo_config would be initialized here\n    # to handle command-line arguments and configuration.\n    # For this quickstart, we'll manually invoke the checks.\n\n    commands = UpgradeCommands()\n\n    # You can specify which group of checks to run\n    # e.g., 'required_pre_upgrade', 'pre_upgrade', 'post_upgrade'\n    print(\"\\n--- Running required_pre_upgrade checks ---\")\n    results = commands.run_checks(group='required_pre_upgrade')\n    for check, status, details in results:\n        print(f\"Check: {check.__name__}, Status: {status}, Details: {details}\")\n\n    if any(not s for _, s, _ in results):\n        print(\"\\nSome required checks failed. Upgrade is not recommended.\")\n        sys.exit(1)\n    else:\n        print(\"\\nAll required checks passed. Proceed with upgrade.\")\n        sys.exit(0)\n\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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)."},"warnings":[{"fix":"Ensure your environment uses Python >=3.10. Upgrade your Python interpreter if necessary.","message":"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.","severity":"breaking","affected_versions":"<=2.x (pre-Python 3.10 requirement)"},{"fix":"Ensure `oslo_config.cfg.CONF()` (or a similar initialization) is called and configuration files are loaded before invoking `UpgradeCommands.run_checks()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For machine-readable output, upgrade to `oslo-upgradecheck` version 0.3.0 or later and use the `--json` command-line flag.","message":"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.","severity":"deprecated","affected_versions":"<0.3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"`oslo.config`'s configuration parser was not properly initialized or loaded before an `oslo-upgradecheck` function attempted to access a configuration option.","error":"oslo_config.cfg.NotInitializedError: call expression on parser has not been invoked."},{"fix":"Run `pip install oslo-upgradecheck` to install the package.","cause":"The `oslo-upgradecheck` library is not installed in the current Python environment.","error":"ImportError: No module named oslo_upgradecheck"}]}