openstack/nova
Code Issues Proposed changes

docs: Add man pages for 'nova-policy'

Browse Source 
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
This commit is contained in:
Stephen Finucane 2020-05-21 12:08:59 +01:00
parent 9e5feb051c
commit b5edc294a1
14 changed files with 129 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/cli/index.rst
View File

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

1
doc/source/cli/nova-api-metadata.rst
View File

@ -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/``

1
doc/source/cli/nova-api-os-compute.rst
View File

@ -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/``

1
doc/source/cli/nova-api.rst
View File

@ -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/``

4
doc/source/cli/nova-compute.rst
View File

@ -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/``

1
doc/source/cli/nova-manage.rst
View File

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

1
doc/source/cli/nova-novncproxy.rst
View File

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

94
doc/source/cli/nova-policy.rst Normal file
View File

@ -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>`__

1
doc/source/cli/nova-scheduler.rst
View File

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

1
doc/source/cli/nova-serialproxy.rst
View File

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

1
doc/source/cli/nova-spicehtml5proxy.rst
View File

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

3
doc/source/cli/nova-status.rst
View File

@ -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
====

4
doc/source/conf.py
View File

@ -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.',

38
nova/cmd/policy.py
View File

@ -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>',
help='Will return only passing policy rules containing '
'the given API name.')
@cmd_common.args('--target', nargs='+', dest='target', metavar='<Target>',
help='Will return only passing policy rules for the '
'given target. The available targets are %s. When '
'"instance_id" is used, the other targets will be '
'overwritten.' % ','.join(_ACCEPTABLE_TARGETS))
@cmd_common.args(
'--api-name', dest='api_name', metavar='<name>',
help=(
'Return only the passing policy rules containing the given API '
'name. If unspecified, all passing policy rules will be returned.'
),
)
@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.
: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.
"""
"""Prints all passing policy rules for the given user."""
context = self._get_context()
api_name = api_name or ''
target = self._get_target(context, target)
@ -104,7 +106,7 @@ class PolicyCommands(object):
policy authorization.
:returns: None if the given target is None, otherwise returns a proper
authorization target.
authorization target.
:raises nova.exception.InvalidAttribute: if a key in the given target
is not an acceptable.
:raises nova.exception.InstanceNotFound: if 'instance_id' is given, and