docs: Add Patrole overview documentation
This patchset adds a Patrole overview documentation
section which is sorely needed. It combines the previous
usage documentation into it.
Change-Id: Ia7412f2e99f33fbdfd2e60ba54ffdba757d1f886
diff --git a/doc/source/framework/rbac_utils.rst b/doc/source/framework/rbac_utils.rst
index 69ba045..7143928 100644
--- a/doc/source/framework/rbac_utils.rst
+++ b/doc/source/framework/rbac_utils.rst
@@ -23,8 +23,19 @@
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.
+.. _role-overriding:
+
+Role Overriding
+^^^^^^^^^^^^^^^
+
+Role overriding is the way Patrole is able to create resources and delete
+resources -- including those that require admin credentials -- while still
+being able to exercise the same set of Tempest credentials to perform the API
+action that authorizes the policy under test, by manipulating the role of
+the Tempest credentials.
+
+Patrole implicitly splits up each test into 3 stages: set up, test execution,
+and teardown.
The role workflow is as follows:
@@ -43,7 +54,7 @@
Test Setup
----------
-Automatic role switch in background.
+Automatic role override in background.
Resources can be set up inside the ``resource_setup`` class method that Tempest
provides. These resources are typically reserved for "expensive" resources
@@ -59,7 +70,7 @@
Test Execution
--------------
-Manual role switch required.
+Manual role override required.
"Test execution" here means calling the API endpoint that enforces the policy
action expected by the ``rbac_rule_validation`` decorator. Test execution
@@ -152,7 +163,7 @@
Test Cleanup
------------
-Automatic role switch in background.
+Automatic role override 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,