Merge "docs: Update configuration docs"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
49b2132db0
|
|
@ -0,0 +1,73 @@
|
|||
.. _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 ``rbac`` 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 overriden 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.
|
||||
|
||||
Strict Policy Check
|
||||
-------------------
|
||||
|
||||
Currently, many services define their "default" rule to be "anyone allowed".
|
||||
If a policy action is not explicitly defined in a policy file, then
|
||||
``oslo.policy`` will fall back to the "default" rule. This implies that if
|
||||
there's a typo in a policy action specified in a Patrole test, ``oslo.policy``
|
||||
can report that the ``rbac_test_role`` will be able to perform the
|
||||
non-existent policy action. For a testing framework, this is undesirable
|
||||
behavior.
|
||||
|
||||
Hence, ``strict_policy_check``, if ``True``, will throw an error in the event
|
||||
that a non-existent or bogus policy action is passed to a Patrole test. If
|
||||
``False``, however, a ``self.skipException`` will be raised.
|
||||
|
||||
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.
|
||||
..
|
||||
|
|
@ -1,24 +1,30 @@
|
|||
.. patrole documentation master file, created by
|
||||
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
========================================
|
||||
Patrole: Tempest Plugin for RBAC Testing
|
||||
========================================
|
||||
|
||||
Patrole - an OpenStack Tempest Plugin for RBAC Testing
|
||||
========================================================
|
||||
User's Guide
|
||||
============
|
||||
|
||||
Contents:
|
||||
Patrole Configuration Guide
|
||||
---------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
readme
|
||||
installation
|
||||
configuration
|
||||
usage
|
||||
sampleconf
|
||||
|
||||
Developer's Guide
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
contributing
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
============
|
||||
Installation
|
||||
============
|
||||
.. _patrole-installation:
|
||||
|
||||
Installation Information
|
||||
========================
|
||||
==========================
|
||||
Patrole Installation Guide
|
||||
==========================
|
||||
|
||||
Manual Installation Information
|
||||
===============================
|
||||
|
||||
At the command line::
|
||||
|
||||
|
|
@ -30,45 +32,3 @@ Patrole can be installed like any other DevStack plugin by including the
|
|||
...
|
||||
|
||||
enable_plugin patrole git://git.openstack.org/openstack/patrole
|
||||
|
||||
Configuration Information
|
||||
=========================
|
||||
|
||||
tempest.conf
|
||||
++++++++++++
|
||||
|
||||
To run the RBAC tempest api test, you have to make the following changes to
|
||||
the tempest.conf file.
|
||||
|
||||
#. ``auth`` section updates ::
|
||||
|
||||
# Allows test cases to create/destroy projects and users. This option
|
||||
# requires that OpenStack Identity API admin credentials are known. If
|
||||
# false, isolated test cases and parallel execution, can still be
|
||||
# achieved configuring a list of test accounts (boolean value)
|
||||
use_dynamic_credentials = True
|
||||
|
||||
#. ``rbac`` section updates ::
|
||||
|
||||
# The role that you want the RBAC tests to use for RBAC testing
|
||||
# This needs to be edited to run the test as a different role.
|
||||
rbac_test_role = _member_
|
||||
|
||||
# Enables RBAC Tempest tests if set to True. Otherwise, they are
|
||||
# skipped.
|
||||
enable_rbac = True
|
||||
|
||||
# If set to true, tests throw a RbacParsingException for policies
|
||||
# not found in the policy.json. Otherwise, they throw a
|
||||
# skipException.
|
||||
strict_policy_check = False
|
||||
|
||||
# The following config options set the location of the service's
|
||||
# policy file. For services that have their policy in code (e.g.,
|
||||
# Nova), this would be the location of a custom policy.json, if
|
||||
# one exists.
|
||||
cinder_policy_file = /etc/cinder/policy.json
|
||||
glance_policy_file = /etc/glance/policy.json
|
||||
keystone_policy_file = /etc/keystone/policy.json
|
||||
neutron_policy_file = /etc/neutron/policy.json
|
||||
nova_policy_file = /etc/nova/policy.json
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
.. include:: ../../README.rst
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
.. _patrole-sampleconf:
|
||||
|
||||
Sample Configuration File
|
||||
==========================
|
||||
|
||||
The following is a sample Patrole configuration for adaptation and use.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[rbac]
|
||||
|
||||
# The role that you want the RBAC tests to use for RBAC testing
|
||||
# This needs to be edited to run the test as a different role.
|
||||
rbac_test_role = Member
|
||||
|
||||
# Enables RBAC Tempest tests if set to True. Otherwise, they are
|
||||
# skipped.
|
||||
enable_rbac = True
|
||||
|
||||
# If set to True, tests throw a RbacParsingException for policies
|
||||
# not found in the policy file. Otherwise, they throw a skipException.
|
||||
strict_policy_check = False
|
||||
|
||||
# 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.
|
||||
custom_policy_files = /etc/nova/policy.json,/etc/neutron/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` perfectly defines what the RBAC requirements
|
||||
# are.
|
||||
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:
|
||||
custom_requirements_file = patrole/requirements.txt
|
||||
|
||||
# DEPRECATED: The following config options set the location of the service's
|
||||
# policy file. For services that have their policy in code (e.g., Nova),
|
||||
# this would be the location of a custom policy.json, if one exists.
|
||||
cinder_policy_file = /etc/cinder/policy.json
|
||||
glance_policy_file = /etc/glance/policy.json
|
||||
keystone_policy_file = /etc/keystone/policy.json
|
||||
neutron_policy_file = /etc/neutron/policy.json
|
||||
nova_policy_file = /etc/nova/policy.json
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
..
|
||||
.. _patrole-usage:
|
||||
|
||||
========
|
||||
Usage
|
||||
|
|
|
|||
Loading…
Reference in New Issue