Auto-generate sample config file

This PS auto-generates the sample config file using
oslo-config-generator which is how every project should reliably
produce a config file.

In addition, the Patrole documentation was updated to link to the
generated config file, so that the documentation accurately
shows config options.

Change-Id: Ib3c39084b4c2b5a0078d1293d882cf9a9050b29b
Closes-Bug: #1709490

doc/source/conf.py

@@ -22,10 +22,15 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
-    'openstackdocstheme'
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'openstackdocstheme',
+    'oslo_config.sphinxconfiggen',
 ]
 
+config_generator_config_file = '../../etc/config-generator.patrole.conf'
+sample_config_basename = '_static/patrole'
+
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
@@ -55,7 +60,7 @@ pygments_style = 'sphinx'
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
 # html_theme_path = ["."]
-# html_static_path = ['static']
+html_static_path = ['_static']
 html_theme = 'openstackdocs'
 
 # openstackdocstheme options

doc/source/sampleconf.rst

@@ -3,49 +3,16 @@
 Sample Configuration File
 ==========================
 
-The following is a sample Patrole configuration for adaptation and use.
+The following is a sample Patrole configuration for adaptation and use. It is
+auto-generated from Patrole when this documentation is built, so
+if you are having issues with an option, please compare your version of
+Patrole with the version of this documentation.
 
-.. code-block:: ini
+Note that the Patrole configuration options actually live inside the Tempest
+configuration file; at runtime, Tempest populates its own configuration
+file with Patrole groups and options, assuming that Patrole is correctly
+installed and recognized as a plugin.
 
-    [patrole]
+The sample configuration can also be viewed in `file form <_static/patrole.conf.sample>`_.
 
-    # The role that you want the RBAC tests to use for RBAC testing
-    # This needs to be edited to run the test as a different role.
-    rbac_test_role = Member
-
-    # Enables RBAC Tempest tests if set to True. Otherwise, they are
-    # skipped.
-    enable_rbac = True
-
-    # If set to True, tests throw a RbacParsingException for policies
-    # not found in the policy file. Otherwise, they throw a skipException.
-    strict_policy_check = False
-
-    # List of the paths to search for policy files. Each policy path assumes that
-    # the service name is included in the path once. Also assumes Patrole is on the
-    # same host as the policy files. The paths should be ordered by precedence,
-    # with high-priority paths before low-priority paths. The first path that is
-    # found to contain the service's policy file will be used.
-    custom_policy_files = /etc/nova/policy.json,/etc/neutron/policy.json
-
-    # This option determines whether Patrole should run against a
-    # `custom_requirements_file` which defines RBAC requirements. The
-    # purpose of setting this flag to True is to verify that RBAC policy
-    # is in accordance to requirements. The idea is that the
-    # `custom_requirements_file` perfectly defines what the RBAC requirements
-    # are.
-    test_custom_requirements = False
-
-    # File path of the yaml file that defines your RBAC requirements. This
-    # file must be located on the same host that Patrole runs on. The yaml
-    # file should be written as follows:
-    custom_requirements_file = patrole/requirements.txt
-
-    # DEPRECATED: The following config options set the location of the service's
-    # policy file. For services that have their policy in code (e.g., Nova),
-    # this would be the location of a custom policy.json, if one exists.
-    cinder_policy_file = /etc/cinder/policy.json
-    glance_policy_file = /etc/glance/policy.json
-    keystone_policy_file = /etc/keystone/policy.json
-    neutron_policy_file = /etc/neutron/policy.json
-    nova_policy_file = /etc/nova/policy.json
+.. literalinclude:: _static/patrole.conf.sample

etc/config-generator.patrole.conf

@@ -0,0 +1,3 @@
+[DEFAULT]
+output_file = etc/patrole.conf.sample
+namespace = patrole.config

etc/patrole.conf.sample

@@ -0,0 +1,276 @@
+[DEFAULT]
+
+
+[patrole]
+
+#
+# From patrole.config
+#
+
+# The current RBAC role against which to run Patrole
+# tests. (string value)
+#rbac_test_role = admin
+
+# Enables RBAC tests. (boolean value)
+#enable_rbac = true
+
+# If true, throws RbacParsingException for policies which
+# don't exist or are not included in the service's policy file. If
+# false, throws
+# skipException. (boolean value)
+#strict_policy_check = false
+
+# List of the paths to search for policy files. Each
+# policy path assumes that the service name is included in the path
+# once. Also
+# assumes Patrole is on the same host as the policy files. The paths
+# should be
+# ordered by precedence, with high-priority paths before low-priority
+# paths. The
+# first path that is found to contain the service's policy file will
+# be used.
+#  (list value)
+#custom_policy_files = /etc/%s/policy.json
+
+# DEPRECATED: Location of the Cinder policy file. Assumed to be on
+# the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#cinder_policy_file = /etc/cinder/policy.json
+
+# DEPRECATED: Location of the Glance policy file. Assumed to be on
+# the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#glance_policy_file = /etc/glance/policy.json
+
+# DEPRECATED: Location of the custom Keystone policy file. Assumed to
+# be on the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#keystone_policy_file = /etc/keystone/policy.json
+
+# DEPRECATED: Location of the Neutron policy file. Assumed to be on
+# the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#neutron_policy_file = /etc/neutron/policy.json
+
+# DEPRECATED: Location of the custom Nova policy file. Assumed to be
+# on the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#nova_policy_file = /etc/nova/policy.json
+
+#
+# This option determines whether Patrole should run against a
+# `custom_requirements_file` which defines RBAC requirements. The
+# purpose of setting this flag to True is to verify that RBAC policy
+# is in accordance to requirements. The idea is that the
+# `custom_requirements_file` perfectly defines what the RBAC
+# requirements are.
+#
+# Here are the possible outcomes when running the Patrole tests
+# against
+# a `custom_requirements_file`:
+#
+# YAML definition: allowed
+# test run: allowed
+# test result: pass
+#
+# YAML definition: allowed
+# test run: not allowed
+# test result: fail (under-permission)
+#
+# YAML definition: not allowed
+# test run: allowed
+# test result: fail (over-permission)
+#  (boolean value)
+#test_custom_requirements = false
+
+#
+# File path of the yaml file that defines your RBAC requirements. This
+# file must be located on the same host that Patrole runs on. The yaml
+# file should be written as follows:
+#
+# ```
+# <service>:
+#   <api_action>:
+#     - <allowed_role>
+#     - <allowed_role>
+#     - <allowed_role>
+#   <api_action>:
+#     - <allowed_role>
+#     - <allowed_role>
+# <service>
+#   <api_action>:
+#     - <allowed_role>
+# ```
+# Where:
+# service = the service that is being tested (cinder, nova, etc)
+# api_action = the policy action that is being tested. Examples:
+#              - volume:create
+#              - os_compute_api:servers:start
+#              - add_image
+# allowed_role = the Keystone role that is allowed to perform the API
+#  (string value)
+#custom_requirements_file = <None>
+
+
+[patrole_log]
+
+#
+# From patrole.config
+#
+
+# Enables reporting on RBAC expected and actual test results for each
+# Patrole test (boolean value)
+#enable_reporting = false
+
+# Name of file where output from 'enable_reporting' is logged. Note
+# that this file is recreated on each invocation of patrole (string
+# value)
+#report_log_name = patrole.log
+
+# Path (relative or absolute) where the output from 'enable_reporting'
+# is logged. This is combined withreport_log_name to generate the full
+# path. (string value)
+#report_log_path = .
+
+
+[rbac]
+# This group is deprecated and will be removed in the next release.
+# Use the [patrole] group instead.
+
+#
+# From patrole.config
+#
+
+# The current RBAC role against which to run Patrole
+# tests. (string value)
+#rbac_test_role = admin
+
+# Enables RBAC tests. (boolean value)
+#enable_rbac = true
+
+# If true, throws RbacParsingException for policies which
+# don't exist or are not included in the service's policy file. If
+# false, throws
+# skipException. (boolean value)
+#strict_policy_check = false
+
+# List of the paths to search for policy files. Each
+# policy path assumes that the service name is included in the path
+# once. Also
+# assumes Patrole is on the same host as the policy files. The paths
+# should be
+# ordered by precedence, with high-priority paths before low-priority
+# paths. The
+# first path that is found to contain the service's policy file will
+# be used.
+#  (list value)
+#custom_policy_files = /etc/%s/policy.json
+
+# DEPRECATED: Location of the Cinder policy file. Assumed to be on
+# the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#cinder_policy_file = /etc/cinder/policy.json
+
+# DEPRECATED: Location of the Glance policy file. Assumed to be on
+# the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#glance_policy_file = /etc/glance/policy.json
+
+# DEPRECATED: Location of the custom Keystone policy file. Assumed to
+# be on the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#keystone_policy_file = /etc/keystone/policy.json
+
+# DEPRECATED: Location of the Neutron policy file. Assumed to be on
+# the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#neutron_policy_file = /etc/neutron/policy.json
+
+# DEPRECATED: Location of the custom Nova policy file. Assumed to be
+# on the same host as Patrole. (string value)
+# This option is deprecated for removal.
+# Its value may be silently ignored in the future.
+# Reason: It is better to use `custom_policy_files` which supports any
+# OpenStack service.
+#nova_policy_file = /etc/nova/policy.json
+
+#
+# This option determines whether Patrole should run against a
+# `custom_requirements_file` which defines RBAC requirements. The
+# purpose of setting this flag to True is to verify that RBAC policy
+# is in accordance to requirements. The idea is that the
+# `custom_requirements_file` perfectly defines what the RBAC
+# requirements are.
+#
+# Here are the possible outcomes when running the Patrole tests
+# against
+# a `custom_requirements_file`:
+#
+# YAML definition: allowed
+# test run: allowed
+# test result: pass
+#
+# YAML definition: allowed
+# test run: not allowed
+# test result: fail (under-permission)
+#
+# YAML definition: not allowed
+# test run: allowed
+# test result: fail (over-permission)
+#  (boolean value)
+#test_custom_requirements = false
+
+#
+# File path of the yaml file that defines your RBAC requirements. This
+# file must be located on the same host that Patrole runs on. The yaml
+# file should be written as follows:
+#
+# ```
+# <service>:
+#   <api_action>:
+#     - <allowed_role>
+#     - <allowed_role>
+#     - <allowed_role>
+#   <api_action>:
+#     - <allowed_role>
+#     - <allowed_role>
+# <service>
+#   <api_action>:
+#     - <allowed_role>
+# ```
+# Where:
+# service = the service that is being tested (cinder, nova, etc)
+# api_action = the policy action that is being tested. Examples:
+#              - volume:create
+#              - os_compute_api:servers:start
+#              - add_image
+# allowed_role = the Keystone role that is allowed to perform the API
+#  (string value)
+#custom_requirements_file = <None>

patrole_tempest_plugin/config.py

@@ -167,3 +167,18 @@ PatroleLogGroup = [
                     "'enable_reporting' is logged. This is combined with"
                     "report_log_name to generate the full path."),
 ]
+
+
+def list_opts():
+    """Return a list of oslo.config options available.
+
+    The purpose of this is to allow tools like the Oslo sample config file
+    generator to discover the options exposed to users.
+    """
+    opt_list = [
+        (patrole_group, PatroleGroup),
+        (patrole_log_group, PatroleLogGroup),
+        (rbac_group, PatroleGroup)
+    ]
+
+    return opt_list

setup.cfg

@@ -54,3 +54,5 @@ source-dir = releasenotes/source
 [entry_points]
 tempest.test_plugins =
     patrole_tempest_plugin = patrole_tempest_plugin.plugin:PatroleTempestPlugin
+oslo.config.opts =
+    patrole.config = patrole_tempest_plugin.config:list_opts

tox.ini

@@ -55,6 +55,9 @@ commands =
 [testenv:debug]
 commands = oslo_debug_helper -t patrole_tempest_plugin/tests {posargs}
 
+[testenv:genconfig]
+commands = oslo-config-generator --config-file etc/config-generator.patrole.conf
+
 [flake8]
 enable-extensions = H106,H203,H904
 show-source = True