Implement scaffolding for upgrade checks

One of the community goals for Stein is to implement a command-line
tool for operators that runs programmable checks that might impact
upgradability.

This commit lays down the basic structure for the upgrade checks and
ties it up to `keystone-status` command.

Story: 2003657
Task: 26135
Change-Id: I6586827104156ac549217967a1b9171f1a3b32e4

doc/source/cli/index.rst

@@ -18,4 +18,8 @@
 CLI Documentation
 =================
 
-.. include:: keystone-manage.rst
+.. toctree::
+   :maxdepth: 1
+
+   keystone-manage
+   keystone-status

doc/source/cli/keystone-status.rst

@@ -0,0 +1,114 @@
+keystone-status
+~~~~~~~~~~~~~~~
+
+-----------------------
+Keystone Status Utility
+-----------------------
+
+:Author: openstack@lists.openstack.org
+:Date: 2018-10-15
+:Copyright: OpenStack Foundation
+:Version: 15.0.0
+:Manual section: 1
+:Manual group: cloud computing
+
+SYNOPSIS
+========
+
+.. code-block:: console
+
+   keystone-status [options]
+
+DESCRIPTION
+===========
+
+``keystone-status`` is a command line tool that helps operators upgrade their
+deployment.
+
+USAGE
+=====
+
+.. code-block:: console
+
+   keystone-status [options] action [additional args]
+
+Categories are:
+
+* ``upgrade``
+
+Detailed descriptions are below.
+
+You can also run with a category argument such as ``upgrade`` to see a list of
+all commands in that category::
+
+    keystone-status upgrade
+
+These sections describe the available categories and arguments for
+:command:`keystone-status`.
+
+Categories and commands
+-----------------------
+
+``keystone-status upgrade check``
+  Performs a release-specific readiness check before restarting services with
+  new code, or upgrading. This command expects to have complete configuration
+  and access to the database.
+
+  **Return Codes**
+
+  .. list-table::
+     :widths: 20 80
+     :header-rows: 1
+
+     * - Return code
+       - Description
+     * - 0
+       - All upgrade readiness checks passed successfully and there is nothing
+         to do.
+     * - 1
+       - At least one check encountered an issue and requires further
+         investigation. This is considered a warning but the upgrade may be OK.
+     * - 2
+       - There was an upgrade status check failure that needs to be
+         investigated. This should be considered something that stops an
+         upgrade.
+     * - 255
+       - An unexpected error occurred.
+
+  **History of Checks**
+
+  **15.0.0 (Stein)**
+
+  * Placeholder to be filled in with checks as they are added in Stein.
+
+OPTIONS
+=======
+
+.. code-block:: console
+
+    -h, --help            show this help message and exit
+    --config-dir DIR      Path to a config directory to pull \*.conf files from.
+                          This file set is sorted, so as to provide a
+                          predictable parse order if individual options are
+                          over-ridden. The set is parsed after the file(s)
+                          specified via previous --config-file, arguments hence
+                          over-ridden options in the directory take precedence.
+    --config-file PATH    Path to a config file to use. Multiple config files
+                          can be specified, with values in later files taking
+                          precedence. Defaults to None.
+
+FILES
+=====
+
+None
+
+SEE ALSO
+========
+
+* `OpenStack Keystone <https://docs.openstack.org/keystone/latest>`__
+
+SOURCE
+======
+
+* Keystone is sourced on `git.openstack.org <https://git.openstack.org/cgit/openstack/keystone>`__
+* Keystone bugs are managed at Launchpad `Keystone <https://bugs.launchpad.net/keystone>`__

doc/source/index.rst

@@ -100,7 +100,7 @@ This section contains the documentation for end-users of keystone.
 CLI Documentation
 ~~~~~~~~~~~~~~~~~
 
-This section details information related to ``keystone-manage``.
+This section details information related to keystone management commands.
 
 .. toctree::
     :maxdepth: 2

keystone/cmd/status.py

@@ -0,0 +1,33 @@
+# 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.
+
+from oslo_upgradecheck import upgradecheck
+
+import keystone.conf
+
+CONF = keystone.conf.CONF
+
+
+class Checks(upgradecheck.UpgradeCommands):
+    """Programmable upgrade checks.
+
+    Each method here should be a programmable check that helps check for things
+    that might cause issues for deployers in the upgrade process. A good
+    example of an upgrade check would be to ensure all roles defined in
+    policies actually exist within the roles backend.
+    """
+
+    pass
+
+
+def main():
+    return upgradecheck.main(CONF, 'keystone', Checks())

lower-constraints.txt

@@ -72,6 +72,7 @@ oslo.middleware==3.31.0
 oslo.policy==1.33.0
 oslo.serialization==2.18.0
 oslo.service==1.30.0
+oslo.upgradecheck==0.1.0
 oslo.utils==3.33.0
 oslotest==3.2.0
 osprofiler==1.4.0

releasenotes/notes/bp-upgrade-checks-0dc692a392a96879.yaml

@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    [`Community Goal <https://governance.openstack.org/tc/goals/stein/upgrade-checkers.html>`_]
+    Support has been added for developers to write pre-upgrade checks.
+    Operators can run these checks using ``keystone-status upgrade check``.
+    This allows operators to be more confident when upgrading their deployments
+    by having a tool that automates programmable checks against the deployment
+    configuration or dataset.

requirements.txt

@@ -32,6 +32,7 @@ oslo.log>=3.38.0 # Apache-2.0
 oslo.middleware>=3.31.0 # Apache-2.0
 oslo.policy>=1.33.0 # Apache-2.0
 oslo.serialization!=2.19.1,>=2.18.0 # Apache-2.0
+oslo.upgradecheck>=0.1.0 # Apache-2.0
 oslo.utils>=3.33.0 # Apache-2.0
 oauthlib>=0.6.2 # BSD
 pysaml2>=4.5.0

setup.cfg

@@ -66,6 +66,7 @@ msgid_bugs_address = https://bugs.launchpad.net/keystone
 [entry_points]
 console_scripts =
     keystone-manage = keystone.cmd.manage:main
+    keystone-status = keystone.cmd.status:main
 
 wsgi_scripts =
     keystone-wsgi-admin = keystone.server.wsgi:initialize_admin_application