diff --git a/goals/stein/upgrade-checkers.rst b/goals/stein/upgrade-checkers.rst new file mode 100644 index 000000000..9c876e4dc --- /dev/null +++ b/goals/stein/upgrade-checkers.rst @@ -0,0 +1,113 @@ +========================== +Support Pre Upgrade Checks +========================== + +Providing assurances and useful feedback to deployers preparing to upgrade +services vastly improves the upgrade experience. One basic step that we can +make consistent across OpenStack projects is to provide "upgrade checks" that +can be run prior to upgrade that will help identify any known issues that would +result in that upgrade failing. + +Each project would provide their specific checks for things like missing or +changed configuration options, incompatible object states, or other conditions +that could lead to failures upgrading that project. In general, anything that +should be documented today in the upgrade release notes would be a good +candidate for an upgrade checker to validate. + +These checks should perform any upgrade validation that can be automated. There +may always be some things that need some subjective evalation, but for those +things that can be automated to determine if there is an issue that could +impact upgrade success, a validation check should be created to automate it. + +.. The following needs to be updated with actual links once we decide we are + going to go ahead with this. + +:Storyboard Board: <put the link to the tracking board here> +:Storyboard Story: <put the link to the story for this goal here> + +Champion +======== + +Matt Riedemann <mriedemos@gmail.com> has volunteered to drive this goal. + +Gerrit Topic +============ + +To facilitate tracking, commits related to this goal should use the +gerrit topic:: + + upgrade-checkers + +Completion Criteria +=================== + +In order for a project to call this goal complete it must provide a command in +the format:: + + $PROJECT-status upgrade check + +The command must: + +#. Iterate through all defined checks +#. Provide a :ref:`summary list output<summary_list>` showing: + + * Check name + * Result (Success or Failure) + * Details + +#. Return the following codes based on check results: + + * 0 - All checks passed + * 1 - Warning that one or issues were found that require investigation + * 2 - One or more checks found an issue that will cause upgrade to fail + + +.. _summary_list: + +Summary List Output +------------------- + +The ``$PROJECT-status upgrade check`` command output should be similar to the +following format:: + + +----------------------------------------------------+ + | Upgrade Check Results | + +----------------------------------------------------+ + | Check: Cells v2 | + | Result: Success | + | Details: None | + +----------------------------------------------------+ + | Check: Placement API | + | Result: Failure | + | Details: There is no placement-api endpoint in the | + | service catalog. | + +----------------------------------------------------+ + +References +========== + +The Nova project has already implemented a ``nova-status upgrade check`` +command along with several checkers. The `command source +<http://git.openstack.org/cgit/openstack/nova/tree/nova/cmd/status.py?id=a1f3a5946ab703225a74f8e85a068cb4fb20e2ff>`__ +may be useful as a reference. + +The `original commit +<http://git.openstack.org/cgit/openstack/nova/commit/?id=a1f3a5946ab703225a74f8e85a068cb4fb20e2ff>`__ +adding the checker framework may also be useful. + +The `Command Line Reference +<https://docs.openstack.org/nova/latest/cli/nova-status.html>`__ for the +``nova-status`` command provides a good good description with some details on +the checks that are performed. + +The command line is also used in the `grenade upgrade checks +<https://github.com/openstack-dev/grenade/blob/dc7f4a4ba5697d5a73a1e656d4a1717964324eab/projects/60_nova/upgrade.sh#L96>`__ +for Nova. + +Current State / Anticipated Impact +================================== + +Most projects today either have their own checklists or tools for checking for +upgrade issues, or more commonly, nothing at all. By providing a consistent +mechanism to discover known issues we can improve the upgrade process and the +deployers confidence and allow for further upgrade tooling to be created.