Update documentation with rbac_utils details
This PS re-organizes the Patrole documentation for the framework.
It also adds documentation for rbac_utils.
Change-Id: I7a512694e8173129a290dbfc99c1ad983c4addd9
diff --git a/doc/source/framework/overview.rst b/doc/source/framework/overview.rst
new file mode 100644
index 0000000..1c9bf3b
--- /dev/null
+++ b/doc/source/framework/overview.rst
@@ -0,0 +1,67 @@
+RBAC Testing Validation
+=======================
+
+--------
+Overview
+--------
+
+RBAC testing validation is broken up into 3 stages:
+
+ #. "Expected" stage. Determine whether the test should be able to succeed
+ or fail based on the test role defined by ``[patrole] rbac_test_role``)
+ and the policy action that the test enforces.
+ #. "Actual" stage. Run the test by calling the API endpoint that enforces
+ the expected policy action using the test role.
+ #. Comparing the outputs from both stages for consistency. A "consistent"
+ result is treated as a pass and an "inconsistent" result is treated
+ as a failure. "Consistent" (or successful) cases include:
+
+ * Expected result is ``True`` and the test passes.
+ * Expected result is ``False`` and the test fails.
+
+ For example, a 200 from the API call and a ``True`` result from
+ ``oslo.policy`` or a 403 from the API call and a ``False`` result from
+ ``oslo.policy`` are successful results.
+
+ "Inconsistent" (or failing) cases include:
+
+ * Expected result is ``False`` and the test passes. This results in an
+ ``RbacOverPermission`` exception getting thrown.
+ * Expected result is ``True`` and the test fails. This results in a
+ ``Forbidden`` exception getting thrown.
+
+ For example, a 200 from the API call and a ``False`` result from
+ ``oslo.policy`` or a 403 from the API call and a ``True`` result from
+ ``oslo.policy`` are failing results.
+
+-------------------------------
+The RBAC Rule Validation Module
+-------------------------------
+
+High-level module that provides the decorator that wraps around Tempest tests
+and serves as the entry point for RBAC testing validation. The workflow
+described above is ultimately carried out by the decorator.
+
+For more information about this module, please see :ref:`rbac-validation`.
+
+---------------------------
+The Policy Authority Module
+---------------------------
+
+Module called by :ref:`rbac-validation` to verify whether the test
+role is allowed to execute a policy action by querying ``oslo.policy`` with
+required test data. The result is used by :ref:`rbac-validation` as the
+"Expected" result.
+
+For more information about this module, please see :ref:`policy-authority`.
+
+---------------------
+The RBAC Utils Module
+---------------------
+
+This module is responsible for handling role switching, the mechanism by which
+Patrole is able to set up, tear down and execute APIs using the same set
+of credentials. Every RBAC test must perform a role switch even if the role
+that is being switched to is admin.
+
+For more information about this module, please see :ref:`rbac-utils`.
diff --git a/doc/source/framework/policy_authority.rst b/doc/source/framework/policy_authority.rst
new file mode 100644
index 0000000..7cd4421
--- /dev/null
+++ b/doc/source/framework/policy_authority.rst
@@ -0,0 +1,30 @@
+.. _policy-authority:
+
+Policy Authority Module
+=======================
+
+Overview
+--------
+
+This module is only called for calculating the "Expected" result if
+``[patrole] test_custom_requirements`` is ``False``.
+
+Using the Policy Authority Module, policy verification is performed by:
+
+#. Pooling together the default `in-code` policy rules.
+#. Overriding the defaults with custom policy rules located in a policy.json,
+ if the policy file exists and the custom policy definition is explicitly
+ defined therein.
+#. Confirming that the policy action -- for example, "list_users" -- exists.
+ (``oslo.policy`` otherwise claims that role "foo" is allowed to
+ perform policy action "bar", for example, because it defers to the
+ "default" policy rule and oftentimes the default can be "anyone allowed").
+#. Performing a call with all necessary data to ``oslo.policy`` and returning
+ the expected result back to ``rbac_rule_validation`` decorator.
+
+Implementation
+--------------
+
+.. automodule:: patrole_tempest_plugin.policy_authority
+ :members:
+ :special-members:
diff --git a/doc/source/framework/rbac_utils.rst b/doc/source/framework/rbac_utils.rst
new file mode 100644
index 0000000..0f000ff
--- /dev/null
+++ b/doc/source/framework/rbac_utils.rst
@@ -0,0 +1,103 @@
+.. _rbac-utils:
+
+The RBAC Utils Module
+=====================
+
+Overview
+--------
+
+Patrole manipulates the ``os_primary`` `Tempest credentials`_, which are the
+primary set of Tempest credentials. It is necessary to use the same credentials
+across the entire test setup/test execution/test teardown workflow
+because otherwise 400-level errors will be thrown by OpenStack services.
+
+This is because many services check the request context's project scope -- and
+in very rare cases, user scope. However, each set of Tempest credentials (via
+`dynamic credentials`_) is allocated its own distinct project. For example, the
+``os_admin`` and ``os_primary`` credentials each have a distinct project,
+meaning that it is not always possible for the ``os_primary`` credentials to
+access resources created by the ``os_admin`` credentials.
+
+The only foolproof solution is to manipulate the role for the same set of
+credentials, rather than using distinct credentials for setup/teardown
+and test execution, respectively. This is especially true when considering
+custom policy rule definitions, which can be arbitrarily complex.
+
+Patrole, therefore, implicitly splits up each test into 3 stages: set up,
+test execution, and teardown.
+
+The role workflow is as follows:
+
+#. Setup: Admin role is used automatically. The primary credentials are
+ overridden with the admin role.
+#. Test execution: ``[patrole] rbac_test_role`` is used manually via a call
+ to ``rbac_utils.switch_role(self, toggle_rbac_role=True)``. Everything that
+ is executed after this call, until the end of the test, uses the primary
+ credentials overridden with the ``rbac_test_role``.
+#. Teardown: Admin role is used automatically. The primary credentials have
+ been overridden with the admin role.
+
+.. _Tempest credentials: https://docs.openstack.org/tempest/latest/library/credential_providers.html
+.. _dynamic credentials: https://docs.openstack.org/tempest/latest/configuration.html#dynamic-credentials
+
+Test Setup
+----------
+
+Automatic role switch in background.
+
+Resources can be set up inside the ``resource_setup`` class method that Tempest
+provides. These resources are typically reserved for "expensive" resources
+in terms of memory or storage requirements, like volumes and VMs. These
+resources are **always** created via the admin role; Patrole automatically
+handles this.
+
+Like Tempest, however, Patrole must also create resources inside tests
+themselves. At the beginning of each test, the primary credentials have already
+been overridden with the admin role. One can create whatever test-level
+resources one needs, without having to worry about permissions.
+
+Test Execution
+--------------
+
+Manual role switch required.
+
+"Test execution" here means calling the API endpoint that enforces the policy
+action expected by the ``rbac_rule_validation`` decorator. Test execution
+should be performed *only after* calling
+``rbac_utils.switch_role(self, toggle_rbac_role=True)``.
+
+Immediately after that call, the API endpoint that enforces the policy should
+be called.
+
+Example::
+
+ # Always apply the RBAC decorator to the test.
+ @rbac_rule_validation.action(
+ service="nova",
+ rule="os_compute_api:os-aggregates:show")
+ def test_show_aggregate_rbac(self):
+ # Do test setup before the switch_role call.
+ aggregate_id = self._create_aggregate()
+ # Call the switch_role method so that the primary credentials have
+ # the test role needed for test execution.
+ self.rbac_utils.switch_role(self, toggle_rbac_role=True)
+ # Call the endpoint that enforces the expected policy action, described
+ # by the "rule" kwarg in the decorator above.
+ self.aggregates_client.show_aggregate(aggregate_id)
+
+Test Cleanup
+------------
+
+Automatic role switch in background.
+
+After the test -- no matter whether it ended successfully or in failure --
+the credentials are overridden with the admin role by the Patrole framework,
+*before* ``tearDown`` or ``tearDownClass`` are called. This means that
+resources are always cleaned up using the admin role.
+
+Implementation
+--------------
+
+.. automodule:: patrole_tempest_plugin.rbac_utils
+ :members:
+ :private-members:
diff --git a/doc/source/framework/rbac_validation.rst b/doc/source/framework/rbac_validation.rst
new file mode 100644
index 0000000..186dfe2
--- /dev/null
+++ b/doc/source/framework/rbac_validation.rst
@@ -0,0 +1,19 @@
+.. _rbac-validation:
+
+RBAC Rule Validation Module
+===========================
+
+Overview
+--------
+
+Module that implements the decorator which serves as the entry point for
+RBAC validation testing. The decorator should be applied to every RBAC test
+with the appropriate ``service`` (OpenStack service) and ``rule`` (OpenStack
+policy name defined by the ``service``).
+
+Implementation
+--------------
+
+.. automodule:: patrole_tempest_plugin.rbac_rule_validation
+ :members:
+ :private-members: