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`.