Improving documentation about target resources

Sometimes it's not easy to identify the target resource based on the API call.

Adding some more details on how API attribute is used as a targer, with an
example on how to compare the API calls logs with the target resource would
help to debug policy issues.

Change-Id: I1318cceb5c0a32c258e6799a872a5dea6482c6de
Closes-Bug: #1886857

1 files changed, 13 insertions, 1 deletions

diff --git a/doc/source/admin/policy-yaml-file.rst b/doc/source/admin/policy-yaml-file.rst
index 5757dc7..9d9b85a 100644
--- a/doc/source/admin/policy-yaml-file.rst
+++ b/doc/source/admin/policy-yaml-file.rst
@@ -239,7 +239,19 @@ Target object attributes are fields from the object description in the
 database. For example in the case of the ``"compute:start"`` API, the
 object is the instance to be started. The policy for starting instances
 could use the ``%(project_id)s`` attribute, that is the project that
-owns the instance. The trailing ``s`` indicates this is a string.
+owns the instance. The trailing ``s`` indicates this is a string. The same
+case would be valid for API attributes like ``%(user_id)s`` and
+``%(domain_id)s``.
+
+During a debug logging phase, it's common to have the target object
+attributes retrieved in the API calls. Comparing the API call on the logs
+with the policy enforced for the corresponding API, you can check which API
+attribute has been used as the target object. For example in the policy.yaml
+for the Nova project you can find ``"compute:start"`` API, the policy will show as
+``"rule:admin_or_owner"`` which will point for
+``"admin_or_owner":  "is_admin:True or project_id:%(project_id)s"`` and in this
+way you can check that the target object in the debug logging it needs to be a
+``project_id`` attribute.
 
 ``is_admin`` indicates that administrative privileges are granted via
 the admin token mechanism (the ``--os-token`` option of the ``keystone``