From 8a5f69a335d5affd437563d7e0fa5c4b8f6d3f8a Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Fri, 14 Jul 2017 20:12:33 +0100 Subject: [PATCH] docs: Update configuration docs This commit updates configuration docs. It also refactors the index doc page to make it look more like Tempest's. The "readme" file was removed from the docs as it's just a high-level project overview. The Developer's Guide section will be updated with contents included in the "readme" in far greater detail in a follow-up commit. Change-Id: I4d468b7f1bb6a000fde42d656635159176d5ef7f --- doc/source/configuration.rst | 73 ++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 26 ++++++++----- doc/source/installation.rst | 54 ++++---------------------- doc/source/readme.rst | 1 - doc/source/sampleconf.rst | 51 +++++++++++++++++++++++++ doc/source/usage.rst | 2 +- 6 files changed, 148 insertions(+), 59 deletions(-) create mode 100644 doc/source/configuration.rst delete mode 100644 doc/source/readme.rst create mode 100644 doc/source/sampleconf.rst diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 00000000..550d2ce9 --- /dev/null +++ b/doc/source/configuration.rst @@ -0,0 +1,73 @@ +.. _patrole-configuration: + +Patrole Configuration Guide +=========================== + +Patrole can be customized by updating Tempest's ``tempest.conf`` configuration +file. All Patrole-specific configuration options should be included under +the ``rbac`` group. + +RBAC Test Role +-------------- + +The RBAC test role governs which role is used when running Patrole tests. For +example, setting ``rbac_test_role`` to "admin" will execute all RBAC tests +using admin credentials. Changing the ``rbac_test_role`` value will `override` +Tempest's primary credentials to use that role. + +This implies that, if ``rbac_test_role`` is "admin", regardless of the Tempest +credentials used by a client, the client will be calling APIs using the admin +role. That is, ``self.os_primary.servers_client`` will run as though it were +``self.os_admin.servers_client``. + +Similarly, setting ``rbac_test_role`` to a non-admin role results in Tempest's +primary credentials being overriden by the role specified by +``rbac_test_role``. + +.. note:: + + Only the role of the primary Tempest credentials ("os_primary") is + modified. The ``user_id`` and ``project_id`` remain unchanged. + +Enable RBAC +----------- + +Given the value of ``enable_rbac``, enables or disables Patrole tests. If +``enable_rbac`` is ``False``, then Patrole tests are skipped. + +Strict Policy Check +------------------- + +Currently, many services define their "default" rule to be "anyone allowed". +If a policy action is not explicitly defined in a policy file, then +``oslo.policy`` will fall back to the "default" rule. This implies that if +there's a typo in a policy action specified in a Patrole test, ``oslo.policy`` +can report that the ``rbac_test_role`` will be able to perform the +non-existent policy action. For a testing framework, this is undesirable +behavior. + +Hence, ``strict_policy_check``, if ``True``, will throw an error in the event +that a non-existent or bogus policy action is passed to a Patrole test. If +``False``, however, a ``self.skipException`` will be raised. + +Custom Policy Files +------------------- + +Patrole supports testing custom policy file definitions, along with default +policy definitions. Default policy definitions are used if custom file +definitions are not specified. If both are specified, the custom policy +definition takes precedence (that is, replaces the default definition, +as this is the default behavior in OpenStack). + +The ``custom_policy_files`` option allows a user to specify a comma-separated +list of custom policy file locations that are on the same host as Patrole. +Each policy file must include the name of the service that is being tested: +for example, if "compute" tests are executed, then Patrole will use the first +policy file contained in ``custom_policy_files`` that contains the "nova" +keyword. + +.. note:: + + Patrole currently does not support policy files located on a host different + than the one on which it is running. +.. diff --git a/doc/source/index.rst b/doc/source/index.rst index 35e84399..f58ee7f7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,24 +1,30 @@ -.. patrole documentation master file, created by - sphinx-quickstart on Tue Jul 9 22:26:36 2013. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +======================================== +Patrole: Tempest Plugin for RBAC Testing +======================================== -Patrole - an OpenStack Tempest Plugin for RBAC Testing -======================================================== +User's Guide +============ -Contents: +Patrole Configuration Guide +--------------------------- .. toctree:: :maxdepth: 2 - readme installation + configuration usage + sampleconf + +Developer's Guide +================= + +.. toctree:: + :maxdepth: 2 + contributing Indices and tables ================== -* :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 31f94f44..c2441529 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,9 +1,11 @@ -============ -Installation -============ +.. _patrole-installation: -Installation Information -======================== +========================== +Patrole Installation Guide +========================== + +Manual Installation Information +=============================== At the command line:: @@ -30,45 +32,3 @@ Patrole can be installed like any other DevStack plugin by including the ... enable_plugin patrole git://git.openstack.org/openstack/patrole - -Configuration Information -========================= - -tempest.conf -++++++++++++ - -To run the RBAC tempest api test, you have to make the following changes to -the tempest.conf file. - -#. ``auth`` section updates :: - - # Allows test cases to create/destroy projects and users. This option - # requires that OpenStack Identity API admin credentials are known. If - # false, isolated test cases and parallel execution, can still be - # achieved configuring a list of test accounts (boolean value) - use_dynamic_credentials = True - -#. ``rbac`` section updates :: - - # 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.json. Otherwise, they throw a - # skipException. - strict_policy_check = False - - # 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 diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3d..00000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/sampleconf.rst b/doc/source/sampleconf.rst new file mode 100644 index 00000000..c262f2d9 --- /dev/null +++ b/doc/source/sampleconf.rst @@ -0,0 +1,51 @@ +.. _patrole-sampleconf: + +Sample Configuration File +========================== + +The following is a sample Patrole configuration for adaptation and use. + +.. code-block:: ini + + [rbac] + + # 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 diff --git a/doc/source/usage.rst b/doc/source/usage.rst index d2570bcb..7470e9ec 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,4 +1,4 @@ -.. +.. _patrole-usage: ======== Usage