Patrole Configuration Guide

Patrole can be customized by updating Tempest’s tempest.conf configuration file. All Patrole-specific configuration options should be included under the patrole group.

RBAC Test Roles

The RBAC test roles govern the list of roles to be used when running Patrole tests. For example, setting rbac_test_roles to “admin” will execute all RBAC tests using admin credentials. Changing the rbac_test_roles value will override Tempest’s primary credentials to use that role.

This implies that, if rbac_test_roles is “admin”, regardless of the Tempest credentials used by a client, the client will be calling APIs using the admin role. That is, self.os_primary.servers_client will run as though it were self.os_admin.servers_client.

Similarly, setting rbac_test_roles with various roles, results in Tempest’s primary credentials being overridden by the roles specified by rbac_test_roles.

Note

Only the roles of the primary Tempest credentials (“os_primary”) are modified. The user_id and project_id remain unchanged.

Custom Policy Files

Patrole supports testing custom policy file definitions, along with default policy definitions. Default policy definitions are used if custom file definitions are not specified. If both are specified, the custom policy definition takes precedence (that is, replaces the default definition, as this is the default behavior in OpenStack).

The custom_policy_files option allows a user to specify a comma-separated list of custom policy file locations that are on the same host as Patrole. Each policy file must include the name of the service that is being tested: for example, if “compute” tests are executed, then Patrole will use the first policy file contained in custom_policy_files that contains the “nova” keyword.

Note

Patrole currently does not support policy files located on a host different than the one on which it is running.

Policy Feature Flags

Patrole’s [policy-feature-enabled] configuration group includes one option per supported policy feature flag. These feature flags are introduced when an OpenStack service introduces a new policy or changes a policy in a backwards-incompatible way. Since Patrole is branchless, it copes with the unexpected policy change by making the relevant policy change as well, but also introduces a new policy feature flag so that the test won’t break N-1/N-2 releases where N is the currently supported release.

The default value for the feature flag is enabled for N and disabled for any releases prior to N in which the feature is not available. This is done by overriding the default value of the feature flag in DevStack’s lib/patrole installation script. The change is made in Tempest’s DevStack script because Patrole’s DevStack plugin is hosted in-repo, which is branch-less (whereas the former is branched).

After the backwards-incompatible change no longer affects any supported release, then the corresponding policy feature flag is removed.

For more information on feature flags, reference the relevant Tempest documentation.

Sample Configuration File

The following is a sample Patrole configuration for adaptation and use. It is auto-generated from Patrole when this documentation is built, so if you are having issues with an option, please compare your version of Patrole with the version of this documentation.

Note that the Patrole configuration options actually live inside the Tempest configuration file; at runtime, Tempest populates its own configuration file with Patrole groups and options, assuming that Patrole is correctly installed and recognized as a plugin.

The sample configuration can also be viewed in file form.

[DEFAULT]


[patrole]

#
# From patrole.config
#

# DEPRECATED: The current RBAC role against which to run
# Patrole tests. (string value)
# This option is deprecated for removal.
# Its value may be silently ignored in the future.
# Reason: This option is deprecated and being
# replaced with ``rbac_test_roles``.
#rbac_test_role = admin

# List of the RBAC roles against which to run
# Patrole tests. (list value)
#rbac_test_roles = admin

# List of the paths to search for policy files. Each
# policy path assumes that the service name is included in the path
# once. Also
# assumes Patrole is on the same host as the policy files. The paths
# should be
# ordered by precedence, with high-priority paths before low-priority
# paths. All
# the paths that are found to contain the service's policy file will
# be used and
# all policy files will be merged. Allowed ``json`` or ``yaml``
# formats.
#  (list value)
#custom_policy_files = /etc/%s/policy.json

#
# This option determines whether Patrole should run against a
# ``custom_requirements_file`` which defines RBAC requirements. The
# purpose of setting this flag to ``True`` is to verify that RBAC
# policy
# is in accordance to requirements. The idea is that the
# ``custom_requirements_file`` precisely defines what the RBAC
# requirements are.
#
# Here are the possible outcomes when running the Patrole tests
# against
# a ``custom_requirements_file``:
#
# YAML definition: allowed
# test run: allowed
# test result: pass
#
# YAML definition: allowed
# test run: not allowed
# test result: fail (under-permission)
#
# YAML definition: not allowed
# test run: allowed
# test result: fail (over-permission)
#  (boolean value)
#test_custom_requirements = false

#
# File path of the YAML file that defines your RBAC requirements. This
# file must be located on the same host that Patrole runs on. The YAML
# file should be written as follows:
#
# .. code-block:: yaml
#
#     <service_foo>:
#       <api_action_a>:
#         - <allowed_role_1>
#         - <allowed_role_2>
#         - <allowed_role_3>
#       <api_action_b>:
#         - <allowed_role_2>
#         - <allowed_role_4>
#     <service_bar>:
#       <api_action_c>:
#         - <allowed_role_3>
#
# Where:
#
# service = the service that is being tested (Cinder, Nova, etc.).
#
# api_action = the policy action that is being tested. Examples:
#
# * volume:create
# * os_compute_api:servers:start
# * add_image
#
# allowed_role = the ``oslo.policy`` role that is allowed to perform
# the API.
#  (string value)
#custom_requirements_file = <None>

# Some of the policy rules have deprecated version,
# Patrole should be able to run check against default and deprecated
# rules,
# otherwise the result of the tests may not be correct.
#  (boolean value)
#validate_deprecated_rules = true


[patrole_log]

#
# From patrole.config
#

# Enables reporting on RBAC expected and actual test results for each
# Patrole test (boolean value)
#enable_reporting = false

# Name of file where output from 'enable_reporting' is logged. Note
# that this file is recreated on each invocation of patrole (string
# value)
#report_log_name = patrole.log

# Path (relative or absolute) where the output from 'enable_reporting'
# is logged. This is combined with report_log_name to generate the
# full path. (string value)
#report_log_path = .


[policy-feature-enabled]

#
# From patrole.config
#

# Is the Neutron policy
# "create_port:fixed_ips:ip_address" available in the cloud? This
# policy was
# changed in a backwards-incompatible way. (boolean value)
#create_port_fixed_ips_ip_address_policy = true

# Is the Neutron policy
# "update_port:fixed_ips:ip_address" available in the cloud? This
# policy was
# changed in a backwards-incompatible way. (boolean value)
#update_port_fixed_ips_ip_address_policy = true

# Is the Cinder policy
# "limits_extension:used_limits" available in the cloud? This policy
# was
# changed in a backwards-incompatible way. (boolean value)
#limits_extension_used_limits_policy = true

# Is the Cinder policy
# "volume_extension:volume_actions:attach" available in the cloud?
# This policy
# was changed in a backwards-incompatible way. (boolean value)
#volume_extension_volume_actions_attach_policy = true

# Is the Cinder policy
# "volume_extension:volume_actions:reserve" available in the cloud?
# This policy
# was changed in a backwards-incompatible way. (boolean value)
#volume_extension_volume_actions_reserve_policy = true

# Is the Cinder policy
# "volume_extension:volume_actions:unreserve" available in the cloud?
# This policy
# was changed in a backwards-incompatible way. (boolean value)
#volume_extension_volume_actions_unreserve_policy = true

# Are the Nova API extension policies available in the
# cloud (e.g. os_compute_api:os-extended-availability-zone)? These
# policies were
# removed in Stein because Nova API extension concept was removed in
# Pike. (boolean value)
#removed_nova_policies_stein = true

# Are the Nova API policies being removed in wallaby
# cycle (e.g. os_compute_api:os-agents)? (boolean value)
#removed_nova_policies_wallaby = true

# Are the obsolete Keystone policies available in the
# cloud (e.g. identity:[create|update|get|delete]_credential)? These
# policies
# were removed in Stein. (boolean value)
#removed_keystone_policies_stein = true

# Are the Cinder Stein policies available in the cloud
# (e.g. [create|update|get|delete]_encryption_policy)? These policies
# are added
# in Stein. (boolean value)
#added_cinder_policies_stein = true

# Is the cloud running the Train release or newer? If
# so, the Keystone Trust API is enforced differently depending on
# passed
# arguments (boolean value)
#keystone_policy_enforcement_train = true

# Are the Nova API policies available in the
# cloud (e.g. os_compute_api:os-services)? These policies were
# changed in Ussuri. (boolean value)
#changed_nova_policies_ussuri = true

# Are the Nova deprecated API policies available in the
# cloud (e.g. os_compute_api:os-networks)? These policies were
# changed in Victoria. (boolean value)
#changed_nova_policies_victoria = true

# Are the Cinder API policies changed in the
# cloud (e.g. 'group:group_types_specs')? These policies were
# changed in Xena. (boolean value)
#changed_cinder_policies_xena = true