Patrole Configuration Guide

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 Role

The RBAC test role governs which role is used when running Patrole tests. For example, setting rbac_test_role to “admin” will execute all RBAC tests using admin credentials. Changing the rbac_test_role value will override Tempest’s primary credentials to use that role.

This implies that, if rbac_test_role 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_role to a non-admin role results in Tempest’s primary credentials being overridden by the role specified by rbac_test_role.

Note

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

Enable RBAC

Given the value of enable_rbac, enables or disables Patrole tests. If enable_rbac is False, then Patrole tests are skipped.

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
#

# The current RBAC role against which to run
# Patrole tests. (string value)
#rbac_test_role = admin

# DEPRECATED: Enables Patrole RBAC tests. (boolean value)
# This option is deprecated for removal since R.
# Its value may be silently ignored in the future.
# Reason: This is a legacy option that was
# meaningful when Patrole existed downstream as a suite of tests
# inside Tempest.
# Installing the Patrole plugin necessarily means that RBAC tests
# should be run.
# This option is paradoxical with the Tempest plugin architecture.
#enable_rbac = true

# 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. The
# first path that is found to contain the service's policy file will
# be used.
#  (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>


[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 withreport_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
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.