policy_dirs help text does not indicate the relationship to policy_file

[Michael McCune]

The current help text for policy_dirs is "Directories where policy configuration files are stored", this does not explain the relationship between the root policy file and the search pattern that occurs.

For example, one reading of this entry gives the user the impression that the policy_dirs will be searched to find the authoritative policy file. Under this assumption an error is produced when searching for the default, or root, policy file if it does not exist. In this case the user is left without a clear indication that the root policy file must exist.

[Doug Hellmann (doug-hellmann)]

Based on my reading of the code, the main policy.json file needs to exist (although it isn't clear if it has to contain anything) [1]. The policy_dirs are then searched *after* loading the main policy.json by combining the paths where oslo.config is looking for configuration files (--config-dirs) with the subdir names in the policy_dirs configuration value [2]. That is, policy_dirs should not contain a full path, but a partial path to be appended to values like /etc/myapp to produce /etc/myapp/policy.d.

[1] https://github.com/openstack/oslo-incubator/blob/master/openstack/common/policy.py#L247 will result in an exception if the file does not exist
[2] https://github.com/openstack/oslo-incubator/blob/master/openstack/common/policy.py#L250

[Doug Hellmann (doug-hellmann)]

We should update the help text for the policy_dirs config value to explain in more detail how it is actually used.

[Michael McCune (mimccune)]

just to add on, i confirmed through testing that policy_dirs will accept relative and absolute paths.