Patrole Coding Guide¶

Patrole Specific Commandments¶

Patrole borrows the following commandments from Tempest; refer to Tempest’s Commandments for more information:

• [T102] Cannot import OpenStack python clients in patrole_tempest_plugin/tests/api
• [T105] Tests cannot use setUpClass/tearDownClass
• [T107] Check that a service tag isn’t in the module path
• [T108] Check no hyphen at the end of rand_name() argument
• [T109] Cannot use testtools.skip decorator; instead use decorators.skip_because from tempest.lib
• [T113] Check that tests use data_utils.rand_uuid() instead of uuid.uuid4()
• [N322] Method’s default argument shouldn’t be mutable

The following are Patrole’s specific Commandments:

• [P100] The rbac_rule_validation.action decorator must be applied to all RBAC tests
• [P101] RBAC test filenames must end with “_rbac.py”; for example, test_servers_rbac.py, not test_servers.py
• [P102] RBAC test class names must end in ‘RbacTest’
• [P103] self.client must not be used as a client alias; this allows for code that is more maintainable and easier to read
• [P104] RBAC extension test class names must end in ‘ExtRbacTest’

Supported OpenStack Components¶

Patrole only offers in-tree integration testing coverage for the following components:

• Cinder
• Glance
• Keystone
• Neutron
• Nova

Patrole currently has no stable library, so reliance upon Patrole’s framework for external RBAC testing should be done with caution. Nonetheless, even when Patrole has a stable library, it will only offer in-tree RBAC testing for the components listed above.

Role Overriding¶

Correct role overriding is vital to correct RBAC testing within Patrole. If a test does not call self.override_role() within the RBAC test, followed by the API endpoint that enforces the expected policy action, then the test is not a valid Patrole test: The API endpoint under test will be performed with admin role, which is always wrong unless CONF.patrole.rbac_test_role is also admin.

Branchless Patrole Considerations¶

Like Tempest, Patrole is branchless. This is to better ensure API and RBAC consistency between releases because API and RBAC behavior should not change between releases. This means that the stable branches are also gated by the Patrole master branch, which also means that proposed commits to Patrole must work against both the master and all the currently supported stable branches of the projects. As such there are a few special considerations that have to be accounted for when pushing new changes to Patrole.

Black Box vs. White Box Testing¶

Tempest is a black box testing framework, meaning that it is concerned with testing public API endpoints and doesn’t concern itself with testing internal implementation details. Patrole, as a Tempest plugin, also falls underneath the category of black box testing. However, even with policy in code documentation, some degree of white box testing is required in order to correctly write RBAC tests.

This is because Policy in Code documentation, while useful in many respects, is usually quite brief and its main purpose is to help operators understand how to customize policy configuration rather than to help developers understand complex policy authorization work flows. For example, policy in code documentation doesn’t make deriving multiple policies easy. Such documentation also doesn’t usually mention that a specific parameter needs to be set, or that a particular microversion must be enabled, or that a particular set of prerequisite API or policy actions must be executed, in order for the policy under test to be enforced by the server. This means that test writers must account for the internal RBAC implementation in API code in order to correctly understand the complete RBAC work flow within an API.

Besides, as mentioned elsewhere in this documentation, not all services currently implement policy in code, making some degree of white box testing a “necessary evil” for writing robust RBAC tests.