doc/source/configuration.rst - packaging/sources/patrole - Gitiles

 .. _patrole-configuration:

 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`_.

 .. _Tempest documentation: https://docs.openstack.org/tempest/latest/HACKING.html#1-new-tests-for-new-features

 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 <_static/patrole.conf.sample>`_.

 .. literalinclude:: _static/patrole.conf.sample
	.. _patrole-configuration:

	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`_.

	.. _Tempest documentation: https://docs.openstack.org/tempest/latest/HACKING.html#1-new-tests-for-new-features

	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 <_static/patrole.conf.sample>`_.

	.. literalinclude:: _static/patrole.conf.sample