From 098a8cd057a104499bdac26140fc25f8e08e6452 Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Wed, 20 Sep 2017 21:31:27 +0100 Subject: [PATCH] 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 | 11 +- doc/source/sampleconf.rst | 53 ++---- etc/config-generator.patrole.conf | 3 + etc/patrole.conf.sample | 276 ++++++++++++++++++++++++++++++ patrole_tempest_plugin/config.py | 15 ++ setup.cfg | 2 + tox.ini | 3 + 7 files changed, 317 insertions(+), 46 deletions(-) create mode 100644 etc/config-generator.patrole.conf create mode 100644 etc/patrole.conf.sample diff --git a/doc/source/conf.py b/doc/source/conf.py index ddb1d454..88c1bea3 100755 --- a/doc/source/conf.py +++ b/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 diff --git a/doc/source/sampleconf.rst b/doc/source/sampleconf.rst index 94ebc4dd..ee848b5c 100644 --- a/doc/source/sampleconf.rst +++ b/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 diff --git a/etc/config-generator.patrole.conf b/etc/config-generator.patrole.conf new file mode 100644 index 00000000..8988ae00 --- /dev/null +++ b/etc/config-generator.patrole.conf @@ -0,0 +1,3 @@ +[DEFAULT] +output_file = etc/patrole.conf.sample +namespace = patrole.config diff --git a/etc/patrole.conf.sample b/etc/patrole.conf.sample new file mode 100644 index 00000000..370ca8d4 --- /dev/null +++ b/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: +# +# ``` +# : +# : +# - +# - +# - +# : +# - +# - +# +# : +# - +# ``` +# 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 = + + +[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: +# +# ``` +# : +# : +# - +# - +# - +# : +# - +# - +# +# : +# - +# ``` +# 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 = diff --git a/patrole_tempest_plugin/config.py b/patrole_tempest_plugin/config.py index fcf29afe..200da851 100644 --- a/patrole_tempest_plugin/config.py +++ b/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 diff --git a/setup.cfg b/setup.cfg index b3f43120..d805f62b 100644 --- a/setup.cfg +++ b/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 diff --git a/tox.ini b/tox.ini index f1b5b86f..3f2cfcd5 100644 --- a/tox.ini +++ b/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