docs: Add man pages for 'nova-policy'

I don't actually grok what this does that 'oslopolicy-checker' couldn't
do, so perhaps we can deprecate this in the future. For now though,
simply document the thing. While we're here, we make some additional
related changes:

- Remove references to the 'policy.yaml' file for services that don't
  use policy (i.e. everything except the API services and, due to a bug,
  the nova-compute service).
- Update remaining references to the 'policy.yaml' file to include the
  'policy.d/' directory
- Update the help text for the '--api-name' and '--target' options of
  the 'nova-policy policy check' command to correct tense and better
  explain their purpose.

Also, yes, 'nova-policy policy check' is dumb. Don't blame me :)

Change-Id: I913b0de9ec40a615da7bf9981852edef4a88fecb
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
Related-bug: #1675486

doc/source/cli/index.rst

@@ -31,6 +31,7 @@ database.
    :maxdepth: 1
 
    nova-manage
+   nova-policy
    nova-status
 
 Service Daemons

doc/source/cli/nova-api-metadata.rst

@@ -36,6 +36,7 @@ Files
 * ``/etc/nova/nova.conf``
 * ``/etc/nova/api-paste.ini``
 * ``/etc/nova/policy.yaml``
+* ``/etc/nova/policy.d/``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-api-os-compute.rst

@@ -34,6 +34,7 @@ Files
 * ``/etc/nova/nova.conf``
 * ``/etc/nova/api-paste.ini``
 * ``/etc/nova/policy.yaml``
+* ``/etc/nova/policy.d/``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-api.rst

@@ -34,6 +34,7 @@ Files
 * ``/etc/nova/nova.conf``
 * ``/etc/nova/api-paste.ini``
 * ``/etc/nova/policy.yaml``
+* ``/etc/nova/policy.d/``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-compute.rst

@@ -33,8 +33,12 @@ Options
 Files
 =====
 
+.. todo: We shouldn't have policy configuration in this non-API service, but
+   bug #1675486 means we do have one
+
 * ``/etc/nova/nova.conf``
 * ``/etc/nova/policy.yaml``
+* ``/etc/nova/policy.d/``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-manage.rst

@@ -1508,6 +1508,7 @@ within an environment.
 See Also
 ========
 
+:doc:`nova-policy(1) <nova-policy>`,
 :doc:`nova-status(1) <nova-status>`
 
 Bugs

doc/source/cli/nova-novncproxy.rst

@@ -80,7 +80,6 @@ Files
 =====
 
 * ``/etc/nova/nova.conf``
-* ``/etc/nova/policy.yaml``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-policy.rst

@@ -0,0 +1,94 @@
+===========
+nova-policy
+===========
+
+.. program:: nova-policy
+
+Synopsis
+========
+
+::
+
+  nova-policy [<options>...]
+
+Description
+===========
+
+:program:`nova-policy` is a tool that allows for inspection of policy file
+configuration. It provides a way to identify the actions available for a user.
+It does not require a running deployment: validation runs against the policy
+files typically located at ``/etc/nova/policy.yaml`` and in the
+``/etc/nova/policy.d`` directory. These paths are configurable via the
+``[oslo_config] policy_file`` and ``[oslo_config] policy_dirs`` configuration
+options, respectively.
+
+Options
+=======
+
+.. rubric:: General options
+
+.. include:: opts/common.rst
+
+.. rubric:: User options
+
+.. option:: --os-roles <auth-roles>
+
+    Defaults to ``$OS_ROLES``.
+
+.. option:: --os-tenant-id <auth-tenant-id>
+
+    Defaults to ``$OS_TENANT_ID``.
+
+.. option:: --os-user-id <auth-user-id>
+
+    Defaults to ``$OS_USER_ID``.
+
+.. rubric:: Debugger options
+
+.. include:: opts/debugger.rst
+
+Commands
+========
+
+policy check
+------------
+
+::
+
+    nova-policy policy check [-h] [--api-name <name>]
+                             [--target <target> [<target>...]
+
+Prints all passing policy rules for the given user.
+
+.. rubric:: Options
+
+.. option:: --api-name <name>
+
+    Return only the passing policy rules containing the given API name.
+    If unspecified, all passing policy rules will be returned.
+
+.. option:: --target <target> [<target>...]
+
+    The target(s) against which the policy rule authorization will be tested.
+    The available targets are: ``project_id``, ``user_id``, ``quota_class``,
+    ``availability_zone``, ``instance_id``.
+    When ``instance_id`` is used, the other targets will be overwritten.
+    If unspecified, the given user will be considered as the target.
+
+Files
+=====
+
+* ``/etc/nova/nova.conf``
+* ``/etc/nova/policy.yaml``
+* ``/etc/nova/policy.d/``
+
+See Also
+========
+
+:doc:`nova-manage(1) <nova-manage>`,
+:doc:`nova-status(1) <nova-status>`
+
+Bugs
+====
+
+* Nova bugs are managed at `Launchpad <https://bugs.launchpad.net/nova>`__

doc/source/cli/nova-scheduler.rst

@@ -33,7 +33,6 @@ Files
 =====
 
 * ``/etc/nova/nova.conf``
-* ``/etc/nova/policy.yaml``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-serialproxy.rst

@@ -53,7 +53,6 @@ Files
 =====
 
 * ``/etc/nova/nova.conf``
-* ``/etc/nova/policy.yaml``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-spicehtml5proxy.rst

@@ -54,7 +54,6 @@ Files
 =====
 
 * ``/etc/nova/nova.conf``
-* ``/etc/nova/policy.yaml``
 * ``/etc/nova/rootwrap.conf``
 * ``/etc/nova/rootwrap.d/``
 

doc/source/cli/nova-status.rst

@@ -151,7 +151,8 @@ Upgrade
 See Also
 ========
 
-:doc:`nova-manage(1) <nova-manage>`
+:doc:`nova-manage(1) <nova-manage>`,
+:doc:`nova-policy(1) <nova-policy>`
 
 Bugs
 ====

doc/source/conf.py

@@ -98,6 +98,10 @@ _man_pages = [
         'nova-rootwrap',
         'Root wrapper daemon for the OpenStack Compute service.',
     ),
+    (
+        'nova-policy',
+        'Inspect policy configuration for the OpenStack Compute services.',
+    ),
     (
         'nova-scheduler',
         'Server for the OpenStack Compute scheduler service.',

nova/cmd/policy.py

@@ -62,24 +62,26 @@ class PolicyCommands(object):
         'project_id', 'user_id', 'quota_class', 'availability_zone',
         'instance_id']
 
-    @cmd_common.args('--api-name', dest='api_name', metavar='<API name>',
+    @cmd_common.args(
-                     help='Will return only passing policy rules containing '
+        '--api-name', dest='api_name', metavar='<name>',
-                          'the given API name.')
+        help=(
-    @cmd_common.args('--target', nargs='+', dest='target', metavar='<Target>',
+            'Return only the passing policy rules containing the given API '
-                     help='Will return only passing policy rules for the '
+            'name. If unspecified, all passing policy rules will be returned.'
-                          'given target. The available targets are %s. When '
+        ),
-                          '"instance_id" is used, the other targets will be '
+    )
-                          'overwritten.' % ','.join(_ACCEPTABLE_TARGETS))
+    @cmd_common.args(
+        '--target', nargs='+', dest='target', metavar='<target>',
+        help=(
+            "The target(s) against which the policy rule authorization will "
+            "be tested. The available targets are: %s. When 'instance_id' is "
+            "used, the other targets will be overwritten. If unspecified, the "
+            "given user will be considered the target." % ', '.join(
+                _ACCEPTABLE_TARGETS
+            )
+        ),
+    )
     def check(self, api_name=None, target=None):
-        """Prints all passing policy rules for the given user.
+        """Prints all passing policy rules for the given user."""
-
-        :param api_name: If None, all passing policy rules will be printed,
-                         otherwise, only passing policies that contain the
-                         given api_name in their names.
-        :param target: The target against which the policy rule authorization
-                       will be tested. If None, the given user will be
-                       considered as the target.
-        """
         context = self._get_context()
         api_name = api_name or ''
         target = self._get_target(context, target)