| Felipe Monteiro | 8a5f69a | 2017-07-14 20:12:33 +0100 | [diff] [blame] | 1 | .. _patrole-configuration: |
| 2 | |
| 3 | Patrole Configuration Guide |
| 4 | =========================== |
| 5 | |
| 6 | Patrole can be customized by updating Tempest's ``tempest.conf`` configuration |
| 7 | file. All Patrole-specific configuration options should be included under |
| 8 | the ``rbac`` group. |
| 9 | |
| 10 | RBAC Test Role |
| 11 | -------------- |
| 12 | |
| 13 | The RBAC test role governs which role is used when running Patrole tests. For |
| 14 | example, setting ``rbac_test_role`` to "admin" will execute all RBAC tests |
| 15 | using admin credentials. Changing the ``rbac_test_role`` value will `override` |
| 16 | Tempest's primary credentials to use that role. |
| 17 | |
| 18 | This implies that, if ``rbac_test_role`` is "admin", regardless of the Tempest |
| 19 | credentials used by a client, the client will be calling APIs using the admin |
| 20 | role. That is, ``self.os_primary.servers_client`` will run as though it were |
| 21 | ``self.os_admin.servers_client``. |
| 22 | |
| 23 | Similarly, setting ``rbac_test_role`` to a non-admin role results in Tempest's |
| 24 | primary credentials being overriden by the role specified by |
| 25 | ``rbac_test_role``. |
| 26 | |
| 27 | .. note:: |
| 28 | |
| 29 | Only the role of the primary Tempest credentials ("os_primary") is |
| 30 | modified. The ``user_id`` and ``project_id`` remain unchanged. |
| 31 | |
| 32 | Enable RBAC |
| 33 | ----------- |
| 34 | |
| 35 | Given the value of ``enable_rbac``, enables or disables Patrole tests. If |
| 36 | ``enable_rbac`` is ``False``, then Patrole tests are skipped. |
| 37 | |
| 38 | Strict Policy Check |
| 39 | ------------------- |
| 40 | |
| 41 | Currently, many services define their "default" rule to be "anyone allowed". |
| 42 | If a policy action is not explicitly defined in a policy file, then |
| 43 | ``oslo.policy`` will fall back to the "default" rule. This implies that if |
| 44 | there's a typo in a policy action specified in a Patrole test, ``oslo.policy`` |
| 45 | can report that the ``rbac_test_role`` will be able to perform the |
| 46 | non-existent policy action. For a testing framework, this is undesirable |
| 47 | behavior. |
| 48 | |
| 49 | Hence, ``strict_policy_check``, if ``True``, will throw an error in the event |
| 50 | that a non-existent or bogus policy action is passed to a Patrole test. If |
| 51 | ``False``, however, a ``self.skipException`` will be raised. |
| 52 | |
| 53 | Custom Policy Files |
| 54 | ------------------- |
| 55 | |
| 56 | Patrole supports testing custom policy file definitions, along with default |
| 57 | policy definitions. Default policy definitions are used if custom file |
| 58 | definitions are not specified. If both are specified, the custom policy |
| 59 | definition takes precedence (that is, replaces the default definition, |
| 60 | as this is the default behavior in OpenStack). |
| 61 | |
| 62 | The ``custom_policy_files`` option allows a user to specify a comma-separated |
| 63 | list of custom policy file locations that are on the same host as Patrole. |
| 64 | Each policy file must include the name of the service that is being tested: |
| 65 | for example, if "compute" tests are executed, then Patrole will use the first |
| 66 | policy file contained in ``custom_policy_files`` that contains the "nova" |
| 67 | keyword. |
| 68 | |
| 69 | .. note:: |
| 70 | |
| 71 | Patrole currently does not support policy files located on a host different |
| 72 | than the one on which it is running. |
| 73 | .. |