Open Stack

On Mon, Mar 23, 2015 at 9:36 AM, Bernd Bausch <berndbausch at gmail.com> wrote:

> I can't believe that this is caused by a rather simple rst file. My
> environment must be incompatible somewhere. I use virtualenv as well, then
> pip install tox+sphinx+openstackdocstheme, then tox -e docs.
>
> The file is below if you are really interested. In any case, I have just
> uploaded it to Gerrit (https://review.openstack.org/#/c/166853/2), so that
> there is some content for review. My build problems can be resolved
> separately.
>
> Thanks for all the suggestions.
>
> Bernd
>
> Policy.json document:
>

Just a quick note that we can't use RST files for anything but the End User
Guide and Admin User Guide. So please convert the content to DocBook for
placement in the correct guide so we can review in context. Pandoc should
handle it fine.

Thanks,
Anne


>
> ====================
> The policy.json file
> ====================
>
> The policy.json file contains a list of policy rules, each setting the
> conditions for permitting an action, typically an API request.
>
> Whether a user is allowed to carry out a request depends on the request
> itself,
> the target object of the request and the user making the request.
>
> General form:
>
> .. code::
>
>    action : access condition
>
> Access conditions can be:
>
> * always true, so that the action is permitted. This can be written as
>   ``""`` (empty string), ``[]``, or ``"@"``.
> * always false, so that the action is not allowed. Written as ``"!"``.
> * a comparison of two values
> * complex conditions formed with boolean operators ``not``, ``and``, ``or``
>   and parentheses
> * aliases, using the ``rule`` keyword.
>
> Two values are compared in the following way
>
> .. code::
>
>    value1 : value2
>
> Possible values are
>
> * constants: Strings, numbers, ``true``, ``false``
> * attributes of the user making the request
> * attributes of the target object
> * API attributes
> * the flag ``is_admin``
>
> User attributes can be ``project_id``, ``user_id``, ``domain_id`` or
> ``role``.
>
> Target object attributes are database fields. Example: ``%(project_id)s``
> means the tenant (project) that owns the object. The trailing ``s``
> indicates
> this is a string.
>
> This example compares the user ID of the user making the request with
> the user ID of the target object
>
> .. code::
>
>    user_id : %(user_id)s
>
> An alias is shorthand for a complex or hard to understand access condition.
> It is defined in the same way as an access rule
>
> .. code::
>
>    alias name : access condition
>
> Once an alias is defined, use the ``rule`` keyword to use it in a policy
> rule.
> See examples below.
>
>
> Examples
> ~~~~~~~~
>
> Unconditionally grant permission to create an instance:
>
> .. code::
>
>    "compute:create": ""
>
> Disable shelving of an instance, perhaps as a temporary measure or because
> you
> don't want users to be able to shelve instances at all:
>
> .. code::
>
>    "compute:shelve": "!"
>
> Define an alias for the condition "target object's user_id is equal to
> user's
> user_id", which means that the user owns the object. The condition features
> a
> user attribute ``user_id`` and a target object attribute ``%(user_id)s``:
>
> .. code::
>
>    "owner" : "user_id:%(user_id)s",
>
> Define an alias for "user is administrator or owns the object". It is based
> on two previously defined aliases, combined with ``or``:
>
> .. code::
>
>    "admin_or_owner": "rule:admin_required or rule:owner",
>
> Another definition for ``admin or owner``. Here the user's tenant ID is
> compared
> with the target object's tenant ID. The definition also uses a constant
> value
> ``True``:
>
> .. code::
>
>    "admin_or_owner":  "is_admin:True or project_id:%(project_id)s"
>
> This is how an alias is used:
>
> .. code::
>
>    "compute:start": "rule:admin_or_owner"
>
> Here, only the administrator or the owner
> of an instance are allowed to start it.
>
> A slightly more complex condition demonstrating the use of boolean
> expressions.
> To delete an EC2 credential, an Identity service API, one must either be
> administrator, or both own the credential and have a matching user ID:
>
> .. code::
>
>    "identity:ec2_delete_credential": "rule:admin_required or
>          (rule:owner and user_id:%(target.credential.user_id)s)"
>
> Older syntax
> ~~~~~~~~~~~~
>
> Older policy.json files may feature a different syntax not based on boolean
> expressions but nested JavaScript arrays.
> For example, the EC2 credentials condition above would have been written as
> follows:
>
> .. code::
>
>    "identity:ec2_delete_credential": [ [ "rule:admin_required ],
>          [ "rule:owner", "user_id:%(target.credential.user_id)s)" ] ]
>
> The condition is an array of arrays. The innermost arrays are or'ed
> together,
> whereas elements inside the innermost arrays are and'ed.
>
> While the old syntax is still supported, we recommend using the newer, more
> intuitive syntax.
>
> # end of file
>
> -----Original Message-----
> From: Christian Berendt [mailto:christian at berendt.io]
> Sent: Monday, March 23, 2015 9:27 PM
> To: openstack-docs at lists.openstack.org
> Subject: Re: [OpenStack-docs] Sphinx error when building in
> openstack-manuals
>
> On 03/23/2015 11:21 AM, Bernd Bausch wrote:
> > 1- add policy.rst to
> > openstack-manuals/doc/playground-user-guide/source
> > 2- add it to the table of contents in index.rst
> > 3- in the source directory, "sphinx-build -b html . my-output-directory"
>
> The following is working for me to build the playground-user-guide. Can you
> please share your policy.rst file.
>
> git clone https://github.com/openstack/openstack-manuals
> cd openstack-manuals
> virtualenv .venv
> source .venv/bin/activate
> pip install -r test-requirements.txt
> cd doc/playground-user-guide/source
> mkdir build
> sphinx-build -b html . build
>
> HTH, Christian.
>
> --
> Christian Berendt
> Cloud Solution Architect
> Mail: berendt at b1-systems.de
>
> B1 Systems GmbH
> Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150323/da4c3152/attachment.html>